/ Hex Artifact Content
Login

Artifact a31c8b7782a0388b4bd823ed3a3a3e4b93b0cf42:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
07d0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
07e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
07f0: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0800: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0810: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0820: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0830: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0840: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0850: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0860: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
0870: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
0880: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
0890: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08a0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08b0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08c0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
08d0: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
08e0: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
08f0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0900: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0910: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0920: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0930: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0940: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0950: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0960: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
0970: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
0980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0990: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09b0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09c0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
09d0: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
09e0: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
09f0: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a00: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a20: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a30: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a40: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a50: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a60: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0a70: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0a80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0a90: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0aa0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ab0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0ac0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0ad0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0ae0: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0af0: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b00: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b10: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b20: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b30: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b40: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b50: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b60: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0b70: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0b80: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0b90: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0ba0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0bb0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bc0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0bd0: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0be0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0bf0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c00: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c20: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c30: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c40: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c50: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c60: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0c70: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0c80: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0c90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0ca0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0cb0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cc0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0cd0: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0ce0: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0cf0: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d00: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d10: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d20: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d30: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d40: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d50: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d60: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0d70: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0d80: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0d90: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0da0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0db0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0dc0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0dd0: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0de0: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0df0: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e00: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e10: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e20: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e30: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e40: 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a  ro evaluates to.
0e50: 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  ** a string whic
0e60: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70  h identifies a p
0e70: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d  articular check-
0e80: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  in of SQLite.** 
0e90: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69  within its confi
0ea0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
0eb0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68  ent system.  ^Th
0ec0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
0ed0: 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ID.** string con
0ee0: 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61  tains the date a
0ef0: 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63  nd time of the c
0f00: 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e  heck-in (UTC) an
0f10: 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73  d an SHA1.** has
0f20: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
0f30: 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a  source tree..**.
0f40: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
0f50: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
0f60: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
0f70: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
0f80: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  er()], [sqlite3_
0f90: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20  sourceid()],.** 
0fa0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
0fb0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
0fc0: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
0fd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
0fe0: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d  ERSION        "-
0ff0: 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65  -VERS--".#define
1000: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
1010: 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e  NUMBER --VERSION
1020: 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e  -NUMBER--.#defin
1030: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
1040: 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43  ID      "--SOURC
1050: 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43  E-ID--"../*.** C
1060: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1070: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
1080: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59  n Numbers.** KEY
1090: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
10a0: 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f  ersion, sqlite3_
10b0: 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54  sourceid.**.** T
10c0: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
10d0: 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65  provide the same
10e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20   information as 
10f0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  the [SQLITE_VERS
1100: 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  ION],.** [SQLITE
1110: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d  _VERSION_NUMBER]
1120: 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f  , and [SQLITE_SO
1130: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72  URCE_ID] C prepr
1140: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a  ocessor macros.*
1150: 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69  * but are associ
1160: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69  ated with the li
1170: 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66  brary instead of
1180: 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65   the header file
1190: 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a  .  ^(Cautious.**
11a0: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
11b0: 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72  ht include asser
11c0: 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69  t() statements i
11d0: 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74  n their applicat
11e0: 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79  ion to.** verify
11f0: 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74   that values ret
1200: 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69  urned by these i
1210: 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20  nterfaces match 
1220: 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a  the macros in.**
1230: 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64   the header, and
1240: 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61   thus insure tha
1250: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
1260: 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  n is.** compiled
1270: 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c   with matching l
1280: 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65  ibrary and heade
1290: 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c  r files..**.** <
12a0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
12b0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69  .** assert( sqli
12c0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
12d0: 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f  umber()==SQLITE_
12e0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29  VERSION_NUMBER )
12f0: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72  ;.** assert( str
1300: 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72  cmp(sqlite3_sour
1310: 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f  ceid(),SQLITE_SO
1320: 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a  URCE_ID)==0 );.*
1330: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70  * assert( strcmp
1340: 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  (sqlite3_libvers
1350: 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52  ion(),SQLITE_VER
1360: 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c  SION)==0 );.** <
1370: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1380: 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1390: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
13a0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
13b0: 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74  t contains the t
13c0: 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56  ext of [SQLITE_V
13d0: 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f  ERSION].** macro
13e0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
13f0: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e  libversion() fun
1400: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20  ction returns a 
1410: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
1420: 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  * to the sqlite3
1430: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
1440: 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65  g constant.  The
1450: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1460: 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f  ion().** functio
1470: 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f  n is provided fo
1480: 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69  r use in DLLs si
1490: 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73  nce DLL users us
14a0: 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76  ually do not hav
14b0: 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65  e.** direct acce
14c0: 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e  ss to string con
14d0: 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68  stants within th
14e0: 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20  e DLL.  ^The.** 
14f0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1500: 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63  on_number() func
1510: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20  tion returns an 
1520: 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f  integer equal to
1530: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
1540: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54  ION_NUMBER].  ^T
1550: 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  he sqlite3_sourc
1560: 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  eid() function r
1570: 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69  eturns .** a poi
1580: 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67  nter to a string
1590: 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20   constant whose 
15a0: 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d  value is the sam
15b0: 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51  e as the .** [SQ
15c0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20  LITE_SOURCE_ID] 
15d0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
15e0: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  acro..**.** See 
15f0: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65  also: [sqlite_ve
1600: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
1610: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
1620: 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54  ]..*/.SQLITE_EXT
1630: 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73  ERN const char s
1640: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
1650: 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
1660: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1670: 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68  (void);.const ch
1680: 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72  ar *sqlite3_sour
1690: 63 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20  ceid(void);.int 
16a0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
16b0: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b  on_number(void);
16c0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16d0: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61  : Run-Time Libra
16e0: 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f  ry Compilation O
16f0: 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69  ptions Diagnosti
1700: 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  cs.**.** ^The sq
1710: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1720: 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74  ion_used() funct
1730: 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72  ion returns 0 or
1740: 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e   1 .** indicatin
1750: 67 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70  g whether the sp
1760: 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77  ecified option w
1770: 61 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a  as defined at .*
1780: 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  * compile time. 
1790: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72   ^The SQLITE_ pr
17a0: 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74  efix may be omit
17b0: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a  ted from the .**
17c0: 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73   option name pas
17d0: 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  sed to sqlite3_c
17e0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
17f0: 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  d().  .**.** ^Th
1800: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  e sqlite3_compil
1810: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75  eoption_get() fu
1820: 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74  nction allows it
1830: 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20  erating.** over 
1840: 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69  the list of opti
1850: 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65  ons that were de
1860: 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  fined at compile
1870: 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75   time by.** retu
1880: 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63  rning the N-th c
1890: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69  ompile time opti
18a0: 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20  on string.  ^If 
18b0: 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
18c0: 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  e,.** sqlite3_co
18d0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
18e0: 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
18f0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
1900: 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66  SQLITE_ .** pref
1910: 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  ix is omitted fr
1920: 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72  om any strings r
1930: 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73  eturned by .** s
1940: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1950: 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a  tion_get()..**.*
1960: 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74  * ^Support for t
1970: 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75  he diagnostic fu
1980: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f  nctions sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
19a0: 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ed().** and sqli
19b0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19c0: 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f  n_get() may be o
19d0: 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66  mitted by specif
19e0: 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51  ying the .** [SQ
19f0: 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c  LITE_OMIT_COMPIL
1a00: 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f  EOPTION_DIAGS] o
1a10: 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65  ption at compile
1a20: 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   time..**.** See
1a30: 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74   also: SQL funct
1a40: 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d  ions [sqlite_com
1a50: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1a60: 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
1a70: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
1a80: 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b  get()] and the [
1a90: 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20  compile_options 
1aa0: 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e  pragma]..*/.#ifn
1ab0: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
1ac0: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49  COMPILEOPTION_DI
1ad0: 41 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  AGS.int sqlite3_
1ae0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
1af0: 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  ed(const char *z
1b00: 4f 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20  OptName);.const 
1b10: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
1b20: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1b30: 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a  int N);.#endif..
1b40: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b50: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
1b60: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68  he Library Is Th
1b70: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e  readsafe.**.** ^
1b80: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65  The sqlite3_thre
1b90: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
1ba0: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69  n returns zero i
1bb0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
1bc0: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70   SQLite was comp
1bd0: 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69  iled with mutexi
1be0: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20  ng code omitted 
1bf0: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53  due to the.** [S
1c00: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1c10: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
1c20: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20  ption being set 
1c30: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  to 0..**.** SQLi
1c40: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c  te can be compil
1c50: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f  ed with or witho
1c60: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65  ut mutexes.  Whe
1c70: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  n.** the [SQLITE
1c80: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70  _THREADSAFE] C p
1c90: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
1ca0: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74  o is 1 or 2, mut
1cb0: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
1cc0: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69  led and SQLite i
1cd0: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57  s threadsafe.  W
1ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  hen the.** [SQLI
1cf0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
1d00: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74  acro is 0, .** t
1d10: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f  he mutexes are o
1d20: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74  mitted.  Without
1d30: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74   the mutexes, it
1d40: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20   is not safe.** 
1d50: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f  to use SQLite co
1d60: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20  ncurrently from 
1d70: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68  more than one th
1d80: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62  read..**.** Enab
1d90: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63  ling mutexes inc
1da0: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65  urs a measurable
1db0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e   performance pen
1dc0: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73  alty..** So if s
1dd0: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73  peed is of utmos
1de0: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74  t importance, it
1df0: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20   makes sense to 
1e00: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d  disable.** the m
1e10: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72  utexes.  But for
1e20: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c   maximum safety,
1e30: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20   mutexes should 
1e40: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e  be enabled..** ^
1e50: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  The default beha
1e60: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65  vior is for mute
1e70: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65  xes to be enable
1e80: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  d..**.** This in
1e90: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
1ea0: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63  sed by an applic
1eb0: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75  ation to make su
1ec0: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76  re that the.** v
1ed0: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
1ee0: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b   that it is link
1ef0: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20  ing against was 
1f00: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
1f10: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74   the desired set
1f20: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c  ting of the [SQL
1f30: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
1f40: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  macro..**.** Thi
1f50: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79  s interface only
1f60: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20   reports on the 
1f70: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74  compile-time mut
1f80: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66  ex setting.** of
1f90: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
1fa0: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20  EADSAFE] flag.  
1fb0: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
1fc0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51  piled with.** SQ
1fd0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
1fe0: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74  1 or =2 then mut
1ff0: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
2000: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
2010: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
2020: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
2030: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
2040: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
2050: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
2060: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
2070: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
2080: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
2090: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
20a0: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
20b0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
20c0: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e  ].  ^(The return
20d0: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a   value of the.**
20e0: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
20f0: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73  afe() function s
2100: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f  hows only the co
2110: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69  mpile-time setti
2120: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20  ng of.** thread 
2130: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20  safety, not any 
2140: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73  run-time changes
2150: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67   to that setting
2160: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69   made by.** sqli
2170: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e  te3_config(). In
2180: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2190: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
21a0: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65  rom sqlite3_thre
21b0: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75  adsafe().** is u
21c0: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c  nchanged by call
21d0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  s to sqlite3_con
21e0: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  fig().)^.**.** S
21f0: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
2200: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
2210: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
2220: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
2230: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2240: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64  _threadsafe(void
2250: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2260: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
2270: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a  nection Handle.*
2280: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74  * KEYWORDS: {dat
2290: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22a0: 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  } {database conn
22b0: 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45  ections}.**.** E
22c0: 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20  ach open SQLite 
22d0: 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72  database is repr
22e0: 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69  esented by a poi
22f0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
2300: 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70  nce of.** the op
2310: 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e  aque structure n
2320: 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20  amed "sqlite3". 
2330: 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f   It is useful to
2340: 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c   think of an sql
2350: 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ite3.** pointer 
2360: 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54  as an object.  T
2370: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
2380: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
2390: 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  en16()], and.** 
23a0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
23b0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61  ()] interfaces a
23c0: 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74  re its construct
23d0: 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ors, and [sqlite
23e0: 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e  3_close()].** an
23f0: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
2400: 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73 20 64  _v2()] are its d
2410: 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65  estructors.  The
2420: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
2430: 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  r.** interfaces 
2440: 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c  (such as.** [sql
2450: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2460: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
2470: 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c  ate_function()],
2480: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2490: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
24a0: 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72   to name but thr
24b0: 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74  ee) that are met
24c0: 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71  hods on an.** sq
24d0: 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f  lite3 object..*/
24e0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
24f0: 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b  sqlite3 sqlite3;
2500: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2510: 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72  : 64-Bit Integer
2520: 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Types.** KEYWOR
2530: 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  DS: sqlite_int64
2540: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a   sqlite_uint64.*
2550: 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
2560: 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70  re is no cross-p
2570: 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73  latform way to s
2580: 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e  pecify 64-bit in
2590: 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53  teger types.** S
25a0: 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74  QLite includes t
25b0: 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62  ypedefs for 64-b
25c0: 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e  it signed and un
25d0: 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e  signed integers.
25e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
25f0: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  e3_int64 and sql
2600: 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20  ite3_uint64 are 
2610: 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 79  the preferred ty
2620: 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a  pe definitions..
2630: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e  ** The sqlite_in
2640: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2650: 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 20  int64 types are 
2660: 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61  supported for ba
2670: 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61  ckwards.** compa
2680: 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a  tibility only..*
2690: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
26a0: 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  3_int64 and sqli
26b0: 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63  te_int64 types c
26c0: 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72  an store integer
26d0: 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65   values.** betwe
26e0: 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 35  en -922337203685
26f0: 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32  4775808 and +922
2700: 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30 37  3372036854775807
2710: 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68   inclusive.  ^Th
2720: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e  e.** sqlite3_uin
2730: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2740: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
2750: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
2760: 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e  lues .** between
2770: 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34   0 and +18446744
2780: 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 63  073709551615 inc
2790: 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65  lusive..*/.#ifde
27a0: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
27b0: 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51  YPE.  typedef SQ
27c0: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
27d0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20  sqlite_int64;.  
27e0: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64  typedef unsigned
27f0: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
2800: 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  PE sqlite_uint64
2810: 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28  ;.#elif defined(
2820: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66  _MSC_VER) || def
2830: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
2840: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69  _).  typedef __i
2850: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36  nt64 sqlite_int6
2860: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2870: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71  igned __int64 sq
2880: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
2890: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e  se.  typedef lon
28a0: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
28b0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
28c0: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67  ef unsigned long
28d0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
28e0: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a  _uint64;.#endif.
28f0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69  typedef sqlite_i
2900: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74  nt64 sqlite3_int
2910: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69  64;.typedef sqli
2920: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  te_uint64 sqlite
2930: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a  3_uint64;../*.**
2940: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f   If compiling fo
2950: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68  r a processor th
2960: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e  at lacks floatin
2970: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c  g point support,
2980: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69  .** substitute i
2990: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74  nteger for float
29a0: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69  ing-point..*/.#i
29b0: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
29c0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
29d0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
29e0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
29f0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2a00: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
2a10: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2a20: 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ion.**.** ^The s
2a30: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61  qlite3_close() a
2a40: 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nd sqlite3_close
2a50: 5f 76 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61  _v2() routines a
2a60: 72 65 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a  re destructors.*
2a70: 2a 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  * for the [sqlit
2a80: 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e  e3] object..** ^
2a90: 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
2aa0: 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c  _close() and sql
2ab0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
2ac0: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
2ad0: 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69   if.** the [sqli
2ae0: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73  te3] object is s
2af0: 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74  uccessfully dest
2b00: 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73  royed and all as
2b10: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f  sociated.** reso
2b20: 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f  urces are deallo
2b30: 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  cated..**.** ^If
2b40: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2b50: 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f  nnection is asso
2b60: 63 69 61 74 65 64 20 77 69 74 68 20 75 6e 66 69  ciated with unfi
2b70: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64  nalized prepared
2b80: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  .** statements o
2b90: 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c  r unfinished sql
2ba0: 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65  ite3_backup obje
2bb0: 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33  cts then sqlite3
2bc0: 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c  _close().** will
2bd0: 20 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 62   leave the datab
2be0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
2bf0: 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  pen and return [
2c00: 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a  SQLITE_BUSY]..**
2c10: 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f   ^If sqlite3_clo
2c20: 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65  se_v2() is calle
2c30: 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a  d with unfinaliz
2c40: 65 64 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ed prepared stat
2c50: 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 20 75 6e  ements.** and un
2c60: 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33  finished sqlite3
2c70: 5f 62 61 63 6b 75 70 73 2c 20 74 68 65 6e 20 74  _backups, then t
2c80: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2c90: 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a  ection becomes.*
2ca0: 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a  * an unusable "z
2cb0: 6f 6d 62 69 65 22 20 77 68 69 63 68 20 77 69 6c  ombie" which wil
2cc0: 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  l automatically 
2cd0: 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 77  be deallocated w
2ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20  hen the.** last 
2cf0: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d00: 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 20  nt is finalized 
2d10: 6f 72 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69  or the last sqli
2d20: 74 65 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a  te3_backup is.**
2d30: 20 66 69 6e 69 73 68 65 64 2e 20 20 54 68 65 20   finished.  The 
2d40: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
2d50: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
2d60: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
2d70: 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61   with.** host la
2d80: 6e 67 75 61 67 65 73 20 74 68 61 74 20 61 72 65  nguages that are
2d90: 20 67 61 72 62 61 67 65 20 63 6f 6c 6c 65 63 74   garbage collect
2da0: 65 64 2c 20 61 6e 64 20 77 68 65 72 65 20 74 68  ed, and where th
2db0: 65 20 6f 72 64 65 72 20 69 6e 20 77 68 69 63 68  e order in which
2dc0: 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 73 20  .** destructors 
2dd0: 61 72 65 20 63 61 6c 6c 65 64 20 69 73 20 61 72  are called is ar
2de0: 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41  bitrary..**.** A
2df0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
2e00: 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ld [sqlite3_fina
2e10: 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d  lize | finalize]
2e20: 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73   all [prepared s
2e30: 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b  tatements],.** [
2e40: 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
2e50: 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20  se | close] all 
2e60: 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20  [BLOB handles], 
2e70: 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  and .** [sqlite3
2e80: 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c  _backup_finish |
2e90: 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71   finish] all [sq
2ea0: 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62  lite3_backup] ob
2eb0: 6a 65 63 74 73 20 61 73 73 6f 63 69 61 74 65 64  jects associated
2ec0: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73 71  .** with the [sq
2ed0: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72  lite3] object pr
2ee0: 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e  ior to attemptin
2ef0: 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f  g to close the o
2f00: 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73  bject.  ^If.** s
2f10: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
2f20: 29 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61  ) is called on a
2f30: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2f40: 63 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c  ction] that stil
2f50: 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e  l has.** outstan
2f60: 64 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73  ding [prepared s
2f70: 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f  tatements], [BLO
2f80: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f  B handles], and/
2f90: 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  or.** [sqlite3_b
2fa0: 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 74  ackup] objects t
2fb0: 68 65 6e 20 69 74 20 72 65 74 75 72 6e 73 20 53  hen it returns S
2fc0: 51 4c 49 54 45 5f 4f 4b 20 62 75 74 20 74 68 65  QLITE_OK but the
2fd0: 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a   deallocation.**
2fe0: 20 6f 66 20 72 65 73 6f 75 72 63 65 73 20 69 73   of resources is
2ff0: 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20   deferred until 
3000: 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74  all [prepared st
3010: 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42  atements], [BLOB
3020: 20 68 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e   handles],.** an
3030: 64 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  d [sqlite3_backu
3040: 70 5d 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61  p] objects are a
3050: 6c 73 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a  lso destroyed..*
3060: 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c  *.** ^If an [sql
3070: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20  ite3] object is 
3080: 64 65 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20  destroyed while 
3090: 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
30a0: 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72   open,.** the tr
30b0: 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74  ansaction is aut
30c0: 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65  omatically rolle
30d0: 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68  d back..**.** Th
30e0: 65 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e C parameter to
30f0: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
3100: 43 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  C)] and [sqlite3
3110: 5f 63 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a  _close_v2(C)].**
3120: 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
3130: 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
3140: 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33  r or an [sqlite3
3150: 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72  ] object pointer
3160: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
3170: 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  m [sqlite3_open(
3180: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
3190: 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  n16()], or.** [s
31a0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
31b0: 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69  ], and not previ
31c0: 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a  ously closed..**
31d0: 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65   ^Calling sqlite
31e0: 33 5f 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c  3_close() or sql
31f0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
3200: 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
3210: 74 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ter.** argument 
3220: 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
3230: 2d 6f 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  -op..*/.int sqli
3240: 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65  te3_close(sqlite
3250: 33 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  3*);.int sqlite3
3260: 5f 63 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65  _close_v2(sqlite
3270: 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20  3*);../*.** The 
3280: 74 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62  type for a callb
3290: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ack function..**
32a0: 20 54 68 69 73 20 69 73 20 6c 65 67 61 63 79 20   This is legacy 
32b0: 61 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e 20  and deprecated. 
32c0: 20 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20   It is included 
32d0: 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a  for historical.*
32e0: 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  * compatibility 
32f0: 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d  and is not docum
3300: 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65  ented..*/.typede
3310: 66 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f  f int (*sqlite3_
3320: 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c  callback)(void*,
3330: 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72  int,char**, char
3340: 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  **);../*.** CAPI
3350: 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51  3REF: One-Step Q
3360: 75 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49  uery Execution I
3370: 6e 74 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54  nterface.**.** T
3380: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3390: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 61  ) interface is a
33a0: 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61   convenience wra
33b0: 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b  pper around.** [
33c0: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
33d0: 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v2()], [sqlite3_
33e0: 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71  step()], and [sq
33f0: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
3400: 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77  ],.** that allow
3410: 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  s an application
3420: 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65   to run multiple
3430: 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53   statements of S
3440: 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61  QL.** without ha
3450: 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f  ving to use a lo
3460: 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a  t of C code. .**
3470: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
3480: 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63  _exec() interfac
3490: 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d  e runs zero or m
34a0: 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  ore UTF-8 encode
34b0: 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d  d,.** semicolon-
34c0: 73 65 70 61 72 61 74 65 20 53 51 4c 20 73 74 61  separate SQL sta
34d0: 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69  tements passed i
34e0: 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75  nto its 2nd argu
34f0: 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20  ment,.** in the 
3500: 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b  context of the [
3510: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
3520: 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61  ion] passed in a
3530: 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67  s its 1st.** arg
3540: 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20  ument.  ^If the 
3550: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
3560: 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61 72 67  n of the 3rd arg
3570: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69  ument to.** sqli
3580: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f  te3_exec() is no
3590: 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20  t NULL, then it 
35a0: 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65  is invoked for e
35b0: 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a  ach result row.*
35c0: 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20  * coming out of 
35d0: 74 68 65 20 65 76 61 6c 75 61 74 65 64 20 53 51  the evaluated SQ
35e0: 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e  L statements.  ^
35f0: 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74  The 4th argument
3600: 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65   to.** sqlite3_e
3610: 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 65 64  xec() is relayed
3620: 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20   through to the 
3630: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  1st argument of 
3640: 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  each.** callback
3650: 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49   invocation.  ^I
3660: 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 70  f the callback p
3670: 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ointer to sqlite
3680: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e  3_exec().** is N
3690: 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c  ULL, then no cal
36a0: 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 69 6e  lback is ever in
36b0: 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 6c 74  voked and result
36c0: 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e   rows are.** ign
36d0: 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ored..**.** ^If 
36e0: 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
36f0: 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67  while evaluating
3700: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
3710: 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f 0a  nts passed into.
3720: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
3730: 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 69 6f  ), then executio
3740: 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  n of the current
3750: 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f 70 73   statement stops
3760: 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75 65   and.** subseque
3770: 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  nt statements ar
3780: 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 66 20  e skipped.  ^If 
3790: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
37a0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
37b0: 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55  c().** is not NU
37c0: 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 72 6f  LL then any erro
37d0: 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 72 69  r message is wri
37e0: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  tten into memory
37f0: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
3800: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
3810: 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 64 20  c()] and passed 
3820: 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65  back through the
3830: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 2e 0a   5th parameter..
3840: 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f  ** To avoid memo
3850: 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 61 70  ry leaks, the ap
3860: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
3870: 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33   invoke [sqlite3
3880: 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65  _free()].** on e
3890: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
38a0: 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 74 68  ings returned th
38b0: 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61  rough the 5th pa
38c0: 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66  rameter of.** of
38d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
38e0: 61 66 74 65 72 20 74 68 65 20 65 72 72 6f 72 20  after the error 
38f0: 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69  message string i
3900: 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64  s no longer need
3910: 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35  ed..** ^If the 5
3920: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
3930: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3940: 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e  s not NULL and n
3950: 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75  o errors.** occu
3960: 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  r, then sqlite3_
3970: 65 78 65 63 28 29 20 73 65 74 73 20 74 68 65 20  exec() sets the 
3980: 70 6f 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35  pointer in its 5
3990: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  th parameter to.
39a0: 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72  ** NULL before r
39b0: 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  eturning..**.** 
39c0: 5e 49 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65  ^If an sqlite3_e
39d0: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72  xec() callback r
39e0: 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
39f0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   the sqlite3_exe
3a00: 63 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  c().** routine r
3a10: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42  eturns SQLITE_AB
3a20: 4f 52 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f  ORT without invo
3a30: 6b 69 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63  king the callbac
3a40: 6b 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77  k again and.** w
3a50: 69 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61  ithout running a
3a60: 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 53 51  ny subsequent SQ
3a70: 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
3a80: 0a 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67  .** ^The 2nd arg
3a90: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
3aa0: 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c  ite3_exec() call
3ab0: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73  back function is
3ac0: 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
3ad0: 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
3ae0: 20 72 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33   result.  ^The 3
3af0: 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  rd argument to t
3b00: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3b10: 29 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73  ).** callback is
3b20: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
3b30: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
3b40: 20 6f 62 74 61 69 6e 65 64 20 61 73 20 69 66 20   obtained as if 
3b50: 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  from.** [sqlite3
3b60: 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c  _column_text()],
3b70: 20 6f 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f   one for each co
3b80: 6c 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c  lumn.  ^If an el
3b90: 65 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65  ement of a.** re
3ba0: 73 75 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c  sult row is NULL
3bb0: 20 74 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73   then the corres
3bc0: 70 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70  ponding string p
3bd0: 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a  ointer for the.*
3be0: 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  * sqlite3_exec()
3bf0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e   callback is a N
3c00: 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54  ULL pointer.  ^T
3c10: 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20  he 4th argument 
3c20: 74 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65  to the.** sqlite
3c30: 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63  3_exec() callbac
3c40: 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  k is an array of
3c50: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
3c60: 69 6e 67 73 20 77 68 65 72 65 20 65 61 63 68 0a  ings where each.
3c70: 2a 2a 20 65 6e 74 72 79 20 72 65 70 72 65 73 65  ** entry represe
3c80: 6e 74 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  nts the name of 
3c90: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65  corresponding re
3ca0: 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f  sult column as o
3cb0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
3cc0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
3cd0: 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  name()]..**.** ^
3ce0: 49 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  If the 2nd param
3cf0: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
3d00: 65 78 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c  exec() is a NULL
3d10: 20 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e   pointer, a poin
3d20: 74 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70  ter.** to an emp
3d30: 74 79 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20  ty string, or a 
3d40: 70 6f 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e  pointer that con
3d50: 74 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65  tains only white
3d60: 73 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a  space and/or .**
3d70: 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74   SQL comments, t
3d80: 68 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65  hen no SQL state
3d90: 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61  ments are evalua
3da0: 74 65 64 20 61 6e 64 20 74 68 65 20 64 61 74 61  ted and the data
3db0: 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63  base.** is not c
3dc0: 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65  hanged..**.** Re
3dd0: 73 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a  strictions:.**.*
3de0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  * <ul>.** <li> T
3df0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
3e00: 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 20  ust insure that 
3e10: 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65  the 1st paramete
3e20: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
3e30: 63 28 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61  c().**      is a
3e40: 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20   valid and open 
3e50: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3e60: 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54  tion]..** <li> T
3e70: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
3e80: 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68  ust not close th
3e90: 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
3ea0: 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65  ection] specifie
3eb0: 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65  d by.**      the
3ec0: 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74   1st parameter t
3ed0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
3ee0: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65   while sqlite3_e
3ef0: 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  xec() is running
3f00: 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70  ..** <li> The ap
3f10: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
3f20: 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51  ot modify the SQ
3f30: 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
3f40: 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20   passed into.** 
3f50: 20 20 20 20 20 74 68 65 20 32 6e 64 20 70 61 72       the 2nd par
3f60: 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65  ameter of sqlite
3f70: 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73  3_exec() while s
3f80: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3f90: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75   running..** </u
3fa0: 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l>.*/.int sqlite
3fb0: 33 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65  3_exec(.  sqlite
3fc0: 33 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  3*,             
3fd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fe0: 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20       /* An open 
3ff0: 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f  database */.  co
4000: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20  nst char *sql,  
4010: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4020: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20           /* SQL 
4030: 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20  to be evaluated 
4040: 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62  */.  int (*callb
4050: 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  ack)(void*,int,c
4060: 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20  har**,char**),  
4070: 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63  /* Callback func
4080: 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  tion */.  void *
4090: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
40a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40b0: 20 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75       /* 1st argu
40c0: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b  ment to callback
40d0: 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72   */.  char **err
40e0: 6d 73 67 20 20 20 20 20 20 20 20 20 20 20 20 20  msg             
40f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4100: 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72   /* Error msg wr
4110: 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b  itten here */.);
4120: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
4130: 3a 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a  : Result Codes.*
4140: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49  * KEYWORDS: SQLI
4150: 54 45 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f 64  TE_OK {error cod
4160: 65 7d 20 7b 65 72 72 6f 72 20 63 6f 64 65 73 7d  e} {error codes}
4170: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72  .** KEYWORDS: {r
4180: 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 72 65 73  esult code} {res
4190: 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a  ult codes}.**.**
41a0: 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e   Many SQLite fun
41b0: 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e  ctions return an
41c0: 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20   integer result 
41d0: 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65  code from the se
41e0: 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20  t shown.** here 
41f0: 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69  in order to indi
4200: 63 61 74 65 20 73 75 63 63 65 73 73 20 6f 72 20  cate success or 
4210: 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e  failure..**.** N
4220: 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20 6d  ew error codes m
4230: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
4240: 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
4250: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
4260: 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54  See also: [SQLIT
4270: 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65  E_IOERR_READ | e
4280: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
4290: 6f 64 65 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  odes],.** [sqlit
42a0: 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c  e3_vtab_on_confl
42b0: 69 63 74 28 29 5d 20 5b 53 51 4c 49 54 45 5f 52  ict()] [SQLITE_R
42c0: 4f 4c 4c 42 41 43 4b 20 7c 20 72 65 73 75 6c 74  OLLBACK | result
42d0: 20 63 6f 64 65 73 5d 2e 0a 2a 2f 0a 23 64 65 66   codes]..*/.#def
42e0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20  ine SQLITE_OK   
42f0: 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53          0   /* S
4300: 75 63 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74  uccessful result
4310: 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67   */./* beginning
4320: 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20  -of-error-codes 
4330: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4340: 45 5f 45 52 52 4f 52 20 20 20 20 20 20 20 20 31  E_ERROR        1
4350: 20 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20     /* SQL error 
4360: 6f 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62  or missing datab
4370: 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ase */.#define S
4380: 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20  QLITE_INTERNAL  
4390: 20 20 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e     2   /* Intern
43a0: 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69  al logic error i
43b0: 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66  n SQLite */.#def
43c0: 69 6e 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20  ine SQLITE_PERM 
43d0: 20 20 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41          3   /* A
43e0: 63 63 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e  ccess permission
43f0: 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69   denied */.#defi
4400: 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20  ne SQLITE_ABORT 
4410: 20 20 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61         4   /* Ca
4420: 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72  llback routine r
4430: 65 71 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72  equested an abor
4440: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
4450: 49 54 45 5f 42 55 53 59 20 20 20 20 20 20 20 20  ITE_BUSY        
4460: 20 35 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61   5   /* The data
4470: 62 61 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63  base file is loc
4480: 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ked */.#define S
4490: 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20  QLITE_LOCKED    
44a0: 20 20 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c     6   /* A tabl
44b0: 65 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73  e in the databas
44c0: 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23  e is locked */.#
44d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
44e0: 4d 45 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f  MEM        7   /
44f0: 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69  * A malloc() fai
4500: 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  led */.#define S
4510: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20  QLITE_READONLY  
4520: 20 20 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70     8   /* Attemp
4530: 74 20 74 6f 20 77 72 69 74 65 20 61 20 72 65 61  t to write a rea
4540: 64 6f 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a  donly database *
4550: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4560: 5f 49 4e 54 45 52 52 55 50 54 20 20 20 20 39 20  _INTERRUPT    9 
4570: 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74    /* Operation t
4580: 65 72 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c  erminated by sql
4590: 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
45a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
45b0: 45 5f 49 4f 45 52 52 20 20 20 20 20 20 20 31 30  E_IOERR       10
45c0: 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20     /* Some kind 
45d0: 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f  of disk I/O erro
45e0: 72 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64  r occurred */.#d
45f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52  efine SQLITE_COR
4600: 52 55 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a  RUPT     11   /*
4610: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 64 69   The database di
4620: 73 6b 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66  sk image is malf
4630: 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ormed */.#define
4640: 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44   SQLITE_NOTFOUND
4650: 20 20 20 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e      12   /* Unkn
4660: 6f 77 6e 20 6f 70 63 6f 64 65 20 69 6e 20 73 71  own opcode in sq
4670: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
4680: 6f 6c 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ol() */.#define 
4690: 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20  SQLITE_FULL     
46a0: 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72     13   /* Inser
46b0: 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61  tion failed beca
46c0: 75 73 65 20 64 61 74 61 62 61 73 65 20 69 73 20  use database is 
46d0: 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20  full */.#define 
46e0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
46f0: 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c     14   /* Unabl
4700: 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61  e to open the da
4710: 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23  tabase file */.#
4720: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52  define SQLITE_PR
4730: 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f  OTOCOL    15   /
4740: 2a 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20  * Database lock 
4750: 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a  protocol error *
4760: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4770: 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31 36 20  _EMPTY       16 
4780: 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69 73    /* Database is
4790: 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e   empty */.#defin
47a0: 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20  e SQLITE_SCHEMA 
47b0: 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65       17   /* The
47c0: 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
47d0: 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66   changed */.#def
47e0: 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49  ine SQLITE_TOOBI
47f0: 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53  G      18   /* S
4800: 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78  tring or BLOB ex
4810: 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74  ceeds size limit
4820: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4830: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31  TE_CONSTRAINT  1
4840: 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65  9   /* Abort due
4850: 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 76   to constraint v
4860: 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66  iolation */.#def
4870: 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41  ine SQLITE_MISMA
4880: 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44  TCH    20   /* D
4890: 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63  ata type mismatc
48a0: 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  h */.#define SQL
48b0: 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20  ITE_MISUSE      
48c0: 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20  21   /* Library 
48d0: 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79  used incorrectly
48e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
48f0: 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32  TE_NOLFS       2
4900: 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66  2   /* Uses OS f
4910: 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70  eatures not supp
4920: 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f  orted on host */
4930: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4940: 41 55 54 48 20 20 20 20 20 20 20 20 32 33 20 20  AUTH        23  
4950: 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f   /* Authorizatio
4960: 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66  n denied */.#def
4970: 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41  ine SQLITE_FORMA
4980: 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 41  T      24   /* A
4990: 75 78 69 6c 69 61 72 79 20 64 61 74 61 62 61 73  uxiliary databas
49a0: 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a  e format error *
49b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
49c0: 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32 35 20  _RANGE       25 
49d0: 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74    /* 2nd paramet
49e0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
49f0: 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20  nd out of range 
4a00: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4a10: 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36  E_NOTADB      26
4a20: 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65     /* File opene
4a30: 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20  d that is not a 
4a40: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f  database file */
4a50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4a60: 4e 4f 54 49 43 45 20 20 20 20 20 20 32 37 20 20  NOTICE      27  
4a70: 20 2f 2a 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e   /* Notification
4a80: 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c  s from sqlite3_l
4a90: 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  og() */.#define 
4aa0: 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 20  SQLITE_WARNING  
4ab0: 20 20 20 32 38 20 20 20 2f 2a 20 57 61 72 6e 69     28   /* Warni
4ac0: 6e 67 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ngs from sqlite3
4ad0: 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e  _log() */.#defin
4ae0: 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20  e SQLITE_ROW    
4af0: 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c       100  /* sql
4b00: 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20  ite3_step() has 
4b10: 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64  another row read
4b20: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4b30: 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20  ITE_DONE        
4b40: 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  101  /* sqlite3_
4b50: 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69 73  step() has finis
4b60: 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f  hed executing */
4b70: 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72  ./* end-of-error
4b80: 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  -codes */../*.**
4b90: 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e   CAPI3REF: Exten
4ba0: 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73  ded Result Codes
4bb0: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65  .** KEYWORDS: {e
4bc0: 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
4bd0: 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65 72  de} {extended er
4be0: 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45  ror codes}.** KE
4bf0: 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65  YWORDS: {extende
4c00: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b  d result code} {
4c10: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
4c20: 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  codes}.**.** In 
4c30: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
4c40: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
4c50: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
4c60: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20  eturn one of 26 
4c70: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49  integer.** [SQLI
4c80: 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63  TE_OK | result c
4c90: 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c  odes].  However,
4ca0: 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73 20   experience has 
4cb0: 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79 20  shown that many 
4cc0: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73 75  of.** these resu
4cd0: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f 6f  lt codes are too
4ce0: 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64 2e   coarse-grained.
4cf0: 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 72    They do not pr
4d00: 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68  ovide as.** much
4d10: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
4d20: 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 70  ut problems as p
4d30: 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74  rogrammers might
4d40: 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66   like.  In an ef
4d50: 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65  fort to.** addre
4d60: 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20 76  ss this, newer v
4d70: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4d80: 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38  e (version 3.3.8
4d90: 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c   and later) incl
4da0: 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66  ude.** support f
4db0: 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65  or additional re
4dc0: 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20  sult codes that 
4dd0: 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74  provide more det
4de0: 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f  ailed informatio
4df0: 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72  n.** about error
4e00: 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64 20  s. The extended 
4e10: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4e20: 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
4e30: 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72  bled.** on a per
4e40: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
4e50: 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67  tion basis using
4e60: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
4e70: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
4e80: 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a  _codes()] API..*
4e90: 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65  *.** Some of the
4ea0: 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65 6e   available exten
4eb0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4ec0: 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 72 65   are listed here
4ed0: 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70  ..** One may exp
4ee0: 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ect the number o
4ef0: 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  f extended resul
4f00: 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 69 6e 63  t codes will inc
4f10: 72 65 61 73 65 0a 2a 2a 20 6f 76 65 72 20 74 69  rease.** over ti
4f20: 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68  me.  Software th
4f30: 61 74 20 75 73 65 73 20 65 78 74 65 6e 64 65 64  at uses extended
4f40: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 73 68   result codes sh
4f50: 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20 74  ould expect.** t
4f60: 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75 6c 74  o see new result
4f70: 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75 72 65   codes in future
4f80: 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
4f90: 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  ite..**.** The S
4fa0: 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20  QLITE_OK result 
4fb0: 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  code will never 
4fc0: 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20 49 74  be extended.  It
4fd0: 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20   will always.** 
4fe0: 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e  be exactly zero.
4ff0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
5000: 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20  TE_IOERR_READ   
5010: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5020: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38  TE_IOERR | (1<<8
5030: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5040: 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45  E_IOERR_SHORT_RE
5050: 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  AD        (SQLIT
5060: 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29  E_IOERR | (2<<8)
5070: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5080: 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20  _IOERR_WRITE    
5090: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
50a0: 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29  _IOERR | (3<<8))
50b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
50c0: 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20  IOERR_FSYNC     
50d0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
50e0: 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a  IOERR | (4<<8)).
50f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5100: 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20  OERR_DIR_FSYNC  
5110: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5120: 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23  OERR | (5<<8)).#
5130: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5140: 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20  ERR_TRUNCATE    
5150: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5160: 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64  ERR | (6<<8)).#d
5170: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5180: 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20 20  RR_FSTAT        
5190: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
51a0: 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65  RR | (7<<8)).#de
51b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
51c0: 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_UNLOCK        
51d0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
51e0: 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66  R | (8<<8)).#def
51f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5200: 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  _RDLOCK         
5210: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5220: 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69   | (9<<8)).#defi
5230: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5240: 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20  DELETE          
5250: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5260: 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69  | (10<<8)).#defi
5270: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5280: 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20 20  BLOCKED         
5290: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
52a0: 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69  | (11<<8)).#defi
52b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
52c0: 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20 20  NOMEM           
52d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
52e0: 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 69  | (12<<8)).#defi
52f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5300: 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20 20  ACCESS          
5310: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5320: 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 69  | (13<<8)).#defi
5330: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5340: 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f 43  CHECKRESERVEDLOC
5350: 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20  K (SQLITE_IOERR 
5360: 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 69  | (14<<8)).#defi
5370: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5380: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20  LOCK            
5390: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
53a0: 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 69  | (15<<8)).#defi
53b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
53c0: 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20 20  CLOSE           
53d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
53e0: 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 69  | (16<<8)).#defi
53f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5400: 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20  DIR_CLOSE       
5410: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5420: 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 69  | (17<<8)).#defi
5430: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5440: 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20 20  SHMOPEN         
5450: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5460: 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66 69  | (18<<8)).#defi
5470: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5480: 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20 20  SHMSIZE         
5490: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
54a0: 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66 69  | (19<<8)).#defi
54b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
54c0: 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  SHMLOCK         
54d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
54e0: 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66 69  | (20<<8)).#defi
54f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5500: 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20  SHMMAP          
5510: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5520: 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66 69  | (21<<8)).#defi
5530: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5540: 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20 20  SEEK            
5550: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5560: 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66 69  | (22<<8)).#defi
5570: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5580: 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20 20  DELETE_NOENT    
5590: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
55a0: 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66 69  | (23<<8)).#defi
55b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
55c0: 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20  MMAP            
55d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
55e0: 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66 69  | (24<<8)).#defi
55f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5600: 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20 20  GETTEMPPATH     
5610: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5620: 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66 69  | (25<<8)).#defi
5630: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5640: 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20 20  CONVPATH        
5650: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5660: 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66 69  | (26<<8)).#defi
5670: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44  ne SQLITE_LOCKED
5680: 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20  _SHAREDCACHE    
5690: 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44    (SQLITE_LOCKED
56a0: 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66   |  (1<<8)).#def
56b0: 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f  ine SQLITE_BUSY_
56c0: 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 20  RECOVERY        
56d0: 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20     (SQLITE_BUSY 
56e0: 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65    |  (1<<8)).#de
56f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
5700: 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20 20  _SNAPSHOT       
5710: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
5720: 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64     |  (2<<8)).#d
5730: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
5740: 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20  TOPEN_NOTEMPDIR 
5750: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
5760: 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a  TOPEN | (1<<8)).
5770: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5780: 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20 20  ANTOPEN_ISDIR   
5790: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
57a0: 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29  ANTOPEN | (2<<8)
57b0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
57c0: 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 41  _CANTOPEN_FULLPA
57d0: 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  TH       (SQLITE
57e0: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c 3c  _CANTOPEN | (3<<
57f0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5800: 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e 56  TE_CANTOPEN_CONV
5810: 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49  PATH       (SQLI
5820: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 34  TE_CANTOPEN | (4
5830: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5840: 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54 41  LITE_CORRUPT_VTA
5850: 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  B            (SQ
5860: 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20 28  LITE_CORRUPT | (
5870: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5880: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52  QLITE_READONLY_R
5890: 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28 53  ECOVERY       (S
58a0: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c  QLITE_READONLY |
58b0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
58c0: 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59   SQLITE_READONLY
58d0: 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20  _CANTLOCK       
58e0: 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59  (SQLITE_READONLY
58f0: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
5900: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e  ne SQLITE_READON
5910: 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20  LY_ROLLBACK     
5920: 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e    (SQLITE_READON
5930: 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65  LY | (3<<8)).#de
5940: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
5950: 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20 20  ONLY_DBMOVED    
5960: 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44      (SQLITE_READ
5970: 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a 23  ONLY | (4<<8)).#
5980: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42  define SQLITE_AB
5990: 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20  ORT_ROLLBACK    
59a0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 42        (SQLITE_AB
59b0: 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  ORT | (2<<8)).#d
59c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
59d0: 53 54 52 41 49 4e 54 5f 43 48 45 43 4b 20 20 20  STRAINT_CHECK   
59e0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
59f0: 53 54 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38 29  STRAINT | (1<<8)
5a00: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5a10: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d 4d  _CONSTRAINT_COMM
5a20: 49 54 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54 45  ITHOOK   (SQLITE
5a30: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 32  _CONSTRAINT | (2
5a40: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5a50: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5a60: 46 4f 52 45 49 47 4e 4b 45 59 20 20 20 28 53 51  FOREIGNKEY   (SQ
5a70: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5a80: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (3<<8)).#defin
5a90: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5aa0: 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20  INT_FUNCTION    
5ab0: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5ac0: 49 4e 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64  INT | (4<<8)).#d
5ad0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5ae0: 53 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c 20  STRAINT_NOTNULL 
5af0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
5b00: 53 54 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38 29  STRAINT | (5<<8)
5b10: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5b20: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49 4d  _CONSTRAINT_PRIM
5b30: 41 52 59 4b 45 59 20 20 20 28 53 51 4c 49 54 45  ARYKEY   (SQLITE
5b40: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 36  _CONSTRAINT | (6
5b50: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5b60: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5b70: 54 52 49 47 47 45 52 20 20 20 20 20 20 28 53 51  TRIGGER      (SQ
5b80: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5b90: 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (7<<8)).#defin
5ba0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5bb0: 49 4e 54 5f 55 4e 49 51 55 45 20 20 20 20 20 20  INT_UNIQUE      
5bc0: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5bd0: 49 4e 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64  INT | (8<<8)).#d
5be0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5bf0: 53 54 52 41 49 4e 54 5f 56 54 41 42 20 20 20 20  STRAINT_VTAB    
5c00: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
5c10: 53 54 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38 29  STRAINT | (9<<8)
5c20: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5c30: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57 49  _CONSTRAINT_ROWI
5c40: 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  D        (SQLITE
5c50: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31 30  _CONSTRAINT |(10
5c60: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5c70: 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f  LITE_NOTICE_RECO
5c80: 56 45 52 5f 57 41 4c 20 20 20 20 20 20 28 53 51  VER_WAL      (SQ
5c90: 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 31  LITE_NOTICE | (1
5ca0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5cb0: 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f  LITE_NOTICE_RECO
5cc0: 56 45 52 5f 52 4f 4c 4c 42 41 43 4b 20 28 53 51  VER_ROLLBACK (SQ
5cd0: 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 32  LITE_NOTICE | (2
5ce0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5cf0: 4c 49 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55 54  LITE_WARNING_AUT
5d00: 4f 49 4e 44 45 58 20 20 20 20 20 20 20 28 53 51  OINDEX       (SQ
5d10: 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20 28  LITE_WARNING | (
5d20: 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41  1<<8))../*.** CA
5d30: 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f  PI3REF: Flags Fo
5d40: 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72  r File Open Oper
5d50: 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ations.**.** The
5d60: 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 72  se bit values ar
5d70: 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75  e intended for u
5d80: 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64  se in the.** 3rd
5d90: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
5da0: 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  e [sqlite3_open_
5db0: 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  v2()] interface 
5dc0: 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74  and.** in the 4t
5dd0: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
5de0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
5df0: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a  xOpen] method..*
5e00: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5e10: 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20  _OPEN_READONLY  
5e20: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
5e30: 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  1  /* Ok for sql
5e40: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
5e50: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5e60: 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20  _OPEN_READWRITE 
5e70: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
5e80: 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  2  /* Ok for sql
5e90: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
5ea0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5eb0: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20  _OPEN_CREATE    
5ec0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
5ed0: 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  4  /* Ok for sql
5ee0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
5ef0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5f00: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
5f10: 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30  OSE    0x0000000
5f20: 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  8  /* VFS only *
5f30: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5f40: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20  _OPEN_EXCLUSIVE 
5f50: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31         0x0000001
5f60: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
5f70: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5f80: 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20  _OPEN_AUTOPROXY 
5f90: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32         0x0000002
5fa0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
5fb0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5fc0: 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20  _OPEN_URI       
5fd0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34         0x0000004
5fe0: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
5ff0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6000: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6010: 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20  _OPEN_MEMORY    
6020: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38         0x0000008
6030: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
6040: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6050: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6060: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20  _OPEN_MAIN_DB   
6070: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30         0x0000010
6080: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6090: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
60a0: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20  _OPEN_TEMP_DB   
60b0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30         0x0000020
60c0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
60d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
60e0: 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f  _OPEN_TRANSIENT_
60f0: 44 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30  DB     0x0000040
6100: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6110: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6120: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e  _OPEN_MAIN_JOURN
6130: 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30  AL     0x0000080
6140: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6150: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6160: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e  _OPEN_TEMP_JOURN
6170: 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30  AL     0x0000100
6180: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6190: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
61a0: 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c  _OPEN_SUBJOURNAL
61b0: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30         0x0000200
61c0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
61d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
61e0: 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55  _OPEN_MASTER_JOU
61f0: 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30  RNAL   0x0000400
6200: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6210: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6220: 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20  _OPEN_NOMUTEX   
6230: 20 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30         0x0000800
6240: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
6250: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6260: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6270: 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20  _OPEN_FULLMUTEX 
6280: 20 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30         0x0001000
6290: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
62a0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
62b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
62c0: 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
62d0: 45 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30  E      0x0002000
62e0: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
62f0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6300: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6310: 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
6320: 48 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30  HE     0x0004000
6330: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
6340: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6350: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6360: 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20  _OPEN_WAL       
6370: 20 20 20 20 20 20 20 30 78 30 30 30 38 30 30 30         0x0008000
6380: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6390: 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20  /../* Reserved: 
63a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
63b0: 20 20 20 20 20 20 20 20 30 78 30 30 46 30 30 30          0x00F000
63c0: 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  00 */../*.** CAP
63d0: 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68  I3REF: Device Ch
63e0: 61 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a  aracteristics.**
63f0: 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 43  .** The xDeviceC
6400: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d  haracteristics m
6410: 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71  ethod of the [sq
6420: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
6430: 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75  ].** object retu
6440: 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77  rns an integer w
6450: 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72  hich is a vector
6460: 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69 74   of these.** bit
6470: 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69   values expressi
6480: 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72  ng I/O character
6490: 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61  istics of the ma
64a0: 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65  ss storage.** de
64b0: 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20  vice that holds 
64c0: 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68  the file that th
64d0: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
64e0: 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73  thods].** refers
64f0: 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53   to..**.** The S
6500: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6510: 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  IC property mean
6520: 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65  s that all write
6530: 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65  s of.** any size
6540: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
6550: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6560: 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a  TOMICnnn values.
6570: 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69  ** mean that wri
6580: 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68  tes of blocks th
6590: 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73  at are nnn bytes
65a0: 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20   in size and.** 
65b0: 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  are aligned to a
65c0: 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20  n address which 
65d0: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75  is an integer mu
65e0: 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e  ltiple of.** nnn
65f0: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
6600: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
6610: 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65  AFE_APPEND value
6620: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77   means.** that w
6630: 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65  hen data is appe
6640: 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20  nded to a file, 
6650: 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65  the data is appe
6660: 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68  nded.** first th
6670: 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  en the size of t
6680: 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e  he file is exten
6690: 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f  ded, never the o
66a0: 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75  ther.** way arou
66b0: 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  nd.  The SQLITE_
66c0: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
66d0: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
66e0: 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  that.** informat
66f0: 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74  ion is written t
6700: 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61  o disk in the sa
6710: 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c  me order as call
6720: 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29  s.** to xWrite()
6730: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
6740: 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  CAP_POWERSAFE_OV
6750: 45 52 57 52 49 54 45 20 70 72 6f 70 65 72 74 79  ERWRITE property
6760: 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61   means that.** a
6770: 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c  fter reboot foll
6780: 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f 72  owing a crash or
6790: 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68 65   power loss, the
67a0: 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20 61   only bytes in a
67b0: 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77 65  .** file that we
67c0: 72 65 20 77 72 69 74 74 65 6e 20 61 74 20 74 68  re written at th
67d0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65  e application le
67e0: 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20 63  vel might have c
67f0: 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68  hanged.** and th
6800: 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74 65  at adjacent byte
6810: 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77 69  s, even bytes wi
6820: 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73 65  thin the same se
6830: 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61 72  ctor are.** guar
6840: 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e 63  anteed to be unc
6850: 68 61 6e 67 65 64 2e 20 20 54 68 65 20 53 51 4c  hanged.  The SQL
6860: 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45  ITE_IOCAP_UNDELE
6870: 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a  TABLE_WHEN_OPEN.
6880: 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63 61 74 65  ** flag indicate
6890: 20 74 68 61 74 20 61 20 66 69 6c 65 20 63 61 6e   that a file can
68a0: 6e 6f 74 20 62 65 20 64 65 6c 65 74 65 64 20 77  not be deleted w
68b0: 68 65 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 23 64 65  hen open..*/.#de
68c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
68d0: 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20  P_ATOMIC        
68e0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
68f0: 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  001.#define SQLI
6900: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35  TE_IOCAP_ATOMIC5
6910: 31 32 20 20 20 20 20 20 20 20 20 20 20 20 20 20  12              
6920: 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69  0x00000002.#defi
6930: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6940: 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20  ATOMIC1K        
6950: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
6960: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
6970: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20  _IOCAP_ATOMIC2K 
6980: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6990: 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65  00000008.#define
69a0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
69b0: 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 20  OMIC4K          
69c0: 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a       0x00000010.
69d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
69e0: 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20  OCAP_ATOMIC8K   
69f0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6a00: 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53  000020.#define S
6a10: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6a20: 49 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 20  IC16K           
6a30: 20 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64     0x00000040.#d
6a40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6a50: 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20  AP_ATOMIC32K    
6a60: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6a70: 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0080.#define SQL
6a80: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6a90: 36 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  64K             
6aa0: 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66   0x00000100.#def
6ab0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6ac0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20  _SAFE_APPEND    
6ad0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32          0x000002
6ae0: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
6af0: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
6b00: 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 30  AL             0
6b10: 78 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e  x00000400.#defin
6b20: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55  e SQLITE_IOCAP_U
6b30: 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f  NDELETABLE_WHEN_
6b40: 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 30  OPEN  0x00000800
6b50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6b60: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
6b70: 4f 56 45 52 57 52 49 54 45 20 20 20 20 30 78 30  OVERWRITE    0x0
6b80: 30 30 30 31 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43  0001000../*.** C
6b90: 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f  API3REF: File Lo
6ba0: 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a  cking Levels.**.
6bb0: 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f  ** SQLite uses o
6bc0: 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65  ne of these inte
6bd0: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
6be0: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75  e second.** argu
6bf0: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74  ment to calls it
6c00: 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c   makes to the xL
6c10: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63  ock() and xUnloc
6c20: 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f  k() methods.** o
6c30: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f  f an [sqlite3_io
6c40: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
6c50: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
6c60: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20  ITE_LOCK_NONE   
6c70: 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
6c80: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41   SQLITE_LOCK_SHA
6c90: 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65  RED        1.#de
6ca0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
6cb0: 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32  _RESERVED      2
6cc0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6cd0: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20  LOCK_PENDING    
6ce0: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
6cf0: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
6d00: 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20  VE     4../*.** 
6d10: 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72  CAPI3REF: Synchr
6d20: 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46  onization Type F
6d30: 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  lags.**.** When 
6d40: 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74  SQLite invokes t
6d50: 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f  he xSync() metho
6d60: 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  d of an.** [sqli
6d70: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
6d80: 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61  object it uses a
6d90: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a   combination of.
6da0: 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72  ** these integer
6db0: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73   values as the s
6dc0: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  econd argument..
6dd0: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53  **.** When the S
6de0: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
6df0: 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64  NLY flag is used
6e00: 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20  , it means that 
6e10: 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72  the.** sync oper
6e20: 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73  ation only needs
6e30: 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74   to flush data t
6e40: 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20  o mass storage. 
6e50: 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d   Inode.** inform
6e60: 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62  ation need not b
6e70: 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68  e flushed. If th
6e80: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74  e lower four bit
6e90: 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a  s of the flag.**
6ea0: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
6eb0: 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20  NC_NORMAL, that 
6ec0: 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72  means to use nor
6ed0: 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61  mal fsync() sema
6ee0: 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65  ntics..** If the
6ef0: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73   lower four bits
6f00: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
6f10: 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65  NC_FULL, that me
6f20: 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61  ans.** to use Ma
6f30: 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c  c OS X style ful
6f40: 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66  lsync instead of
6f50: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20   fsync()..**.** 
6f60: 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74  Do not confuse t
6f70: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  he SQLITE_SYNC_N
6f80: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45  ORMAL and SQLITE
6f90: 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73  _SYNC_FULL flags
6fa0: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52  .** with the [PR
6fb0: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
6fc0: 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52  ]=NORMAL and [PR
6fd0: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
6fe0: 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e  ]=FULL.** settin
6ff0: 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72  gs.  The [synchr
7000: 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65  onous pragma] de
7010: 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61  termines when ca
7020: 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53  lls to the.** xS
7030: 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f  ync VFS method o
7040: 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73  ccur and applies
7050: 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73   uniformly acros
7060: 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e  s all platforms.
7070: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53  .** The SQLITE_S
7080: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
7090: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
70a0: 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20  flags determine 
70b0: 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63  how.** energetic
70c0: 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20   or rigorous or 
70d0: 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e  forceful the syn
70e0: 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65  c operations are
70f0: 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b   and.** only mak
7100: 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f  e a difference o
7110: 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68  n Mac OSX for th
7120: 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65  e default SQLite
7130: 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64   code..** (Third
7140: 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65  -party VFS imple
7150: 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74  mentations might
7160: 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64   also make the d
7170: 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65  istinction.** be
7180: 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e  tween SQLITE_SYN
7190: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c  C_NORMAL and SQL
71a0: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62  ITE_SYNC_FULL, b
71b0: 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20  ut among the.** 
71c0: 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
71d0: 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f  s natively suppo
71e0: 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20  rted by SQLite, 
71f0: 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20  only Mac OSX.** 
7200: 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 20  cares about the 
7210: 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a  difference.).*/.
7220: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
7230: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20  YNC_NORMAL      
7240: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e    0x00002.#defin
7250: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
7260: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30  LL          0x00
7270: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  003.#define SQLI
7280: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
7290: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f        0x00010../
72a0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
72b0: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e  S Interface Open
72c0: 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a   File Handle.**.
72d0: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66  ** An [sqlite3_f
72e0: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72  ile] object repr
72f0: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66  esents an open f
7300: 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b  ile in the .** [
7310: 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53  sqlite3_vfs | OS
7320: 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
7330: 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f  ].  Individual O
7340: 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  S interface.** i
7350: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
7360: 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73  ill.** want to s
7370: 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a  ubclass this obj
7380: 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67  ect by appending
7390: 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
73a0: 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20  ds.** for their 
73b0: 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d  own use.  The pM
73c0: 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20  ethods entry is 
73d0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
73e0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
73f0: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74  ethods] object t
7400: 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68  hat defines meth
7410: 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69  ods for performi
7420: 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74  ng.** I/O operat
7430: 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e  ions on the open
7440: 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65   file..*/.typede
7450: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
7460: 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69  _file sqlite3_fi
7470: 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  le;.struct sqlit
7480: 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73  e3_file {.  cons
7490: 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  t struct sqlite3
74a0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65  _io_methods *pMe
74b0: 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f  thods;  /* Metho
74c0: 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66  ds for an open f
74d0: 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ile */.};../*.**
74e0: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
74f0: 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72  terface File Vir
7500: 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a  tual Methods Obj
7510: 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  ect.**.** Every 
7520: 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74  file opened by t
7530: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
7540: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f  xOpen] method po
7550: 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73  pulates an.** [s
7560: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
7570: 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f  ect (or, more co
7580: 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61  mmonly, a subcla
7590: 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  ss of the.** [sq
75a0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
75b0: 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  ct) with a point
75c0: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
75d0: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
75e0: 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
75f0: 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74   defines the met
7600: 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72  hods used to per
7610: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65  form various ope
7620: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e  rations.** again
7630: 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  st the open file
7640: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
7650: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
7660: 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  e] object..**.**
7670: 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   If the [sqlite3
7680: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
7690: 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69  od sets the sqli
76a0: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
76b0: 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f  s element .** to
76c0: 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
76d0: 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71  ter, then the sq
76e0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
76f0: 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a  .xClose method.*
7700: 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64  * may be invoked
7710: 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71   even if the [sq
7720: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
7730: 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69   reported that i
7740: 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a  t failed.  The.*
7750: 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72  * only way to pr
7760: 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20  event a call to 
7770: 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67  xClose following
7780: 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74   a failed [sqlit
7790: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a  e3_vfs.xOpen].**
77a0: 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c   is for the [sql
77b0: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
77c0: 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 74  to set the sqlit
77d0: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
77e0: 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e   element.** to N
77f0: 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ULL..**.** The f
7800: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
7810: 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e   xSync may be on
7820: 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e  e of [SQLITE_SYN
7830: 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20  C_NORMAL] or.** 
7840: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c  [SQLITE_SYNC_FUL
7850: 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63  L].  The first c
7860: 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72  hoice is the nor
7870: 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20  mal fsync()..** 
7880: 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63  The second choic
7890: 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20  e is a Mac OS X 
78a0: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20  style fullsync. 
78b0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e   The [SQLITE_SYN
78c0: 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66  C_DATAONLY].** f
78d0: 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20  lag may be ORed 
78e0: 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  in to indicate t
78f0: 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74  hat only the dat
7900: 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a  a of the file.**
7910: 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f   and not its ino
7920: 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73  de needs to be s
7930: 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ynced..**.** The
7940: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
7950: 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78  to xLock() and x
7960: 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65  Unlock() are one
7970: 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c   of.** <ul>.** <
7980: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
7990: 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  _NONE],.** <li> 
79a0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41  [SQLITE_LOCK_SHA
79b0: 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  RED],.** <li> [S
79c0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
79d0: 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  VED],.** <li> [S
79e0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
79f0: 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  NG], or.** <li> 
7a00: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
7a10: 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c  LUSIVE]..** </ul
7a20: 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63  >.** xLock() inc
7a30: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e  reases the lock.
7a40: 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65   xUnlock() decre
7a50: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a  ases the lock..*
7a60: 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65  * The xCheckRese
7a70: 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f  rvedLock() metho
7a80: 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  d checks whether
7a90: 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f   any database co
7aa0: 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74  nnection,.** eit
7ab0: 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63  her in this proc
7ac0: 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f  ess or in some o
7ad0: 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73  ther process, is
7ae0: 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52   holding a RESER
7af0: 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c  VED,.** PENDING,
7b00: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f   or EXCLUSIVE lo
7b10: 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20  ck on the file. 
7b20: 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65   It returns true
7b30: 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f  .** if such a lo
7b40: 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61  ck exists and fa
7b50: 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a  lse otherwise..*
7b60: 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f  *.** The xFileCo
7b70: 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69  ntrol() method i
7b80: 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65  s a generic inte
7b90: 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77  rface that allow
7ba0: 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20  s custom.** VFS 
7bb0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
7bc0: 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74  to directly cont
7bd0: 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  rol an open file
7be0: 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
7bf0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
7c00: 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65  rol()] interface
7c10: 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f  .  The second "o
7c20: 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  p" argument is a
7c30: 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63  n.** integer opc
7c40: 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20  ode.  The third 
7c50: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65  argument is a ge
7c60: 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e  neric pointer in
7c70: 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69  tended to.** poi
7c80: 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72  nt to a structur
7c90: 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61  e that may conta
7ca0: 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  in arguments or 
7cb0: 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74  space in which t
7cc0: 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72  o.** write retur
7cd0: 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e  n values.  Poten
7ce0: 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46  tial uses for xF
7cf0: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67  ileControl() mig
7d00: 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  ht be.** functio
7d10: 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f  ns to enable blo
7d20: 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68  cking locks with
7d30: 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68   timeouts, to ch
7d40: 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b  ange the.** lock
7d50: 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f  ing strategy (fo
7d60: 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65  r example to use
7d70: 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29   dot-file locks)
7d80: 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20  , to inquire.** 
7d90: 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73  about the status
7da0: 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74   of a lock, or t
7db0: 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f  o break stale lo
7dc0: 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65  cks.  The SQLite
7dd0: 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65  .** core reserve
7de0: 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65  s all opcodes le
7df0: 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20  ss than 100 for 
7e00: 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20  its own use..** 
7e10: 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  A [SQLITE_FCNTL_
7e20: 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 74  LOCKSTATE | list
7e30: 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73   of opcodes] les
7e40: 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76  s than 100 is av
7e50: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c  ailable..** Appl
7e60: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65  ications that de
7e70: 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46  fine a custom xF
7e80: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
7e90: 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63  d should use opc
7ea0: 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20  odes.** greater 
7eb0: 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69  than 100 to avoi
7ec0: 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46  d conflicts.  VF
7ed0: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
7ee0: 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  s should.** retu
7ef0: 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  rn [SQLITE_NOTFO
7f00: 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f  UND] for file co
7f10: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68  ntrol opcodes th
7f20: 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a  at they do not.*
7f30: 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a  * recognize..**.
7f40: 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69  ** The xSectorSi
7f50: 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75  ze() method retu
7f60: 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73  rns the sector s
7f70: 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65  ize of the.** de
7f80: 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c  vice that underl
7f90: 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54  ies the file.  T
7fa0: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69  he sector size i
7fb0: 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d  s the.** minimum
7fc0: 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20   write that can 
7fd0: 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74  be performed wit
7fe0: 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a  hout disturbing.
7ff0: 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69  ** other bytes i
8000: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65  n the file.  The
8010: 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65   xDeviceCharacte
8020: 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74  ristics().** met
8030: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69  hod returns a bi
8040: 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62  t vector describ
8050: 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66  ing behaviors of
8060: 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69   the.** underlyi
8070: 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a  ng device:.**.**
8080: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
8090: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
80a0: 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  IC].** <li> [SQL
80b0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
80c0: 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  512].** <li> [SQ
80d0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
80e0: 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C1K].** <li> [SQ
80f0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8100: 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C2K].** <li> [SQ
8110: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8120: 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C4K].** <li> [SQ
8130: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8140: 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C8K].** <li> [SQ
8150: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8160: 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C16K].** <li> [S
8170: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
8180: 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC32K].** <li> [
8190: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
81a0: 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC64K].** <li> 
81b0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41  [SQLITE_IOCAP_SA
81c0: 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c  FE_APPEND].** <l
81d0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
81e0: 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20  _SEQUENTIAL].** 
81f0: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
8200: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8210: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
8220: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74  ns that all writ
8230: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a  es of.** any siz
8240: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  e are atomic.  T
8250: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
8260: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73  ATOMICnnn values
8270: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72  .** mean that wr
8280: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74  ites of blocks t
8290: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65  hat are nnn byte
82a0: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a  s in size and.**
82b0: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20   are aligned to 
82c0: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68  an address which
82d0: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d   is an integer m
82e0: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e  ultiple of.** nn
82f0: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  n are atomic.  T
8300: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
8310: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75  SAFE_APPEND valu
8320: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  e means.** that 
8330: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70  when data is app
8340: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c  ended to a file,
8350: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70   the data is app
8360: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74  ended.** first t
8370: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  hen the size of 
8380: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65  the file is exte
8390: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20  nded, never the 
83a0: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f  other.** way aro
83b0: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  und.  The SQLITE
83c0: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
83d0: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  L property means
83e0: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61   that.** informa
83f0: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20  tion is written 
8400: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73  to disk in the s
8410: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c  ame order as cal
8420: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28  ls.** to xWrite(
8430: 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61  )..**.** If xRea
8440: 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49  d() returns SQLI
8450: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
8460: 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f  EAD it must also
8470: 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20   fill.** in the 
8480: 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20  unread portions 
8490: 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 77 69  of the buffer wi
84a0: 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53  th zeros.  A VFS
84b0: 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74   that.** fails t
84c0: 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72  o zero-fill shor
84d0: 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 73 65  t reads might se
84e0: 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77  em to work.  How
84f0: 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65  ever,.** failure
8500: 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68   to zero-fill sh
8510: 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65  ort reads will e
8520: 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74  ventually lead t
8530: 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  o.** database co
8540: 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70  rruption..*/.typ
8550: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
8560: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73  te3_io_methods s
8570: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
8580: 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  s;.struct sqlite
8590: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20  3_io_methods {. 
85a0: 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20   int iVersion;. 
85b0: 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73   int (*xClose)(s
85c0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
85d0: 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71   int (*xRead)(sq
85e0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69  lite3_file*, voi
85f0: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
8600: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
8610: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69  t);.  int (*xWri
8620: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  te)(sqlite3_file
8630: 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
8640: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65  int iAmt, sqlite
8650: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a  3_int64 iOfst);.
8660: 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74    int (*xTruncat
8670: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
8680: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
8690: 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78  size);.  int (*x
86a0: 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69  Sync)(sqlite3_fi
86b0: 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b  le*, int flags);
86c0: 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69  .  int (*xFileSi
86d0: 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ze)(sqlite3_file
86e0: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
86f0: 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20   *pSize);.  int 
8700: 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33  (*xLock)(sqlite3
8710: 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20  _file*, int);.  
8720: 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73  int (*xUnlock)(s
8730: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8740: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65  t);.  int (*xChe
8750: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28  ckReservedLock)(
8760: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8770: 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20  nt *pResOut);.  
8780: 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72  int (*xFileContr
8790: 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ol)(sqlite3_file
87a0: 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20  *, int op, void 
87b0: 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a  *pArg);.  int (*
87c0: 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c  xSectorSize)(sql
87d0: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69  ite3_file*);.  i
87e0: 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72  nt (*xDeviceChar
87f0: 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c  acteristics)(sql
8800: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f  ite3_file*);.  /
8810: 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  * Methods above 
8820: 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65  are valid for ve
8830: 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74  rsion 1 */.  int
8840: 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c 69   (*xShmMap)(sqli
8850: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69  te3_file*, int i
8860: 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e  Pg, int pgsz, in
8870: 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65  t, void volatile
8880: 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68  **);.  int (*xSh
8890: 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  mLock)(sqlite3_f
88a0: 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74  ile*, int offset
88b0: 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61  , int n, int fla
88c0: 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53  gs);.  void (*xS
88d0: 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69 74  hmBarrier)(sqlit
88e0: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
88f0: 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 71   (*xShmUnmap)(sq
8900: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8910: 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20   deleteFlag);.  
8920: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65  /* Methods above
8930: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76   are valid for v
8940: 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e  ersion 2 */.  in
8950: 74 20 28 2a 78 46 65 74 63 68 29 28 73 71 6c 69  t (*xFetch)(sqli
8960: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
8970: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20  e3_int64 iOfst, 
8980: 69 6e 74 20 69 41 6d 74 2c 20 76 6f 69 64 20 2a  int iAmt, void *
8990: 2a 70 70 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55  *pp);.  int (*xU
89a0: 6e 66 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f  nfetch)(sqlite3_
89b0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
89c0: 6e 74 36 34 20 69 4f 66 73 74 2c 20 76 6f 69 64  nt64 iOfst, void
89d0: 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f   *p);.  /* Metho
89e0: 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c  ds above are val
89f0: 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33  id for version 3
8a00: 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f   */.  /* Additio
8a10: 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20  nal methods may 
8a20: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
8a30: 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d  re releases */.}
8a40: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
8a50: 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65  F: Standard File
8a60: 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73   Control Opcodes
8a70: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
8a80: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61  eger constants a
8a90: 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74  re opcodes for t
8aa0: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
8ab0: 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65  method.** of the
8ac0: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
8ad0: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64  hods] object and
8ae0: 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65   for the [sqlite
8af0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
8b00: 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a  ].** interface..
8b10: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
8b20: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
8b30: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
8b40: 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e  d for debugging.
8b50: 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65    This.** opcode
8b60: 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c   causes the xFil
8b70: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
8b80: 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72  to write the cur
8b90: 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a  rent state of.**
8ba0: 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f   the lock (one o
8bb0: 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  f [SQLITE_LOCK_N
8bc0: 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f  ONE], [SQLITE_LO
8bd0: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b  CK_SHARED],.** [
8be0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
8bf0: 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c  RVED], [SQLITE_L
8c00: 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72  OCK_PENDING], or
8c10: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58   [SQLITE_LOCK_EX
8c20: 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74  CLUSIVE]).** int
8c30: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61  o an integer tha
8c40: 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d  t the pArg argum
8c50: 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54  ent points to. T
8c60: 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a  his capability.*
8c70: 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67  * is used during
8c80: 20 74 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c   testing and onl
8c90: 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75  y needs to be su
8ca0: 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c  pported when SQL
8cb0: 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64  ITE_TEST.** is d
8cc0: 65 66 69 6e 65 64 2e 0a 2a 2a 20 3c 75 6c 3e 0a  efined..** <ul>.
8cd0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
8ce0: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d  FCNTL_SIZE_HINT]
8cf0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
8d00: 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54  _FCNTL_SIZE_HINT
8d10: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
8d20: 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69   by SQLite to gi
8d30: 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61  ve the VFS.** la
8d40: 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f  yer a hint of ho
8d50: 77 20 6c 61 72 67 65 20 74 68 65 20 64 61 74 61  w large the data
8d60: 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67  base file will g
8d70: 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67  row to be during
8d80: 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20   the.** current 
8d90: 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68  transaction.  Th
8da0: 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67  is hint is not g
8db0: 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20  uaranteed to be 
8dc0: 61 63 63 75 72 61 74 65 20 62 75 74 20 69 74 0a  accurate but it.
8dd0: 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73  ** is often clos
8de0: 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69  e.  The underlyi
8df0: 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f  ng VFS might cho
8e00: 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61  ose to prealloca
8e10: 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66  te database.** f
8e20: 69 6c 65 20 73 70 61 63 65 20 62 61 73 65 64 20  ile space based 
8e30: 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20  on this hint in 
8e40: 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72  order to help wr
8e50: 69 74 65 73 20 74 6f 20 74 68 65 20 64 61 74 61  ites to the data
8e60: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e  base.** file run
8e70: 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c   faster..**.** <
8e80: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
8e90: 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a  L_CHUNK_SIZE]].*
8ea0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
8eb0: 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20  NTL_CHUNK_SIZE] 
8ec0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
8ed0: 6f 20 72 65 71 75 65 73 74 20 74 68 61 74 20 74  o request that t
8ee0: 68 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64  he VFS.** extend
8ef0: 73 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20  s and truncates 
8f00: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
8f10: 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61  e in chunks of a
8f20: 20 73 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a   size specified.
8f30: 2a 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e 20  ** by the user. 
8f40: 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  The fourth argum
8f50: 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
8f60: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
8f70: 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74  should .** point
8f80: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28   to an integer (
8f90: 74 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69  type int) contai
8fa0: 6e 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75  ning the new chu
8fb0: 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a  nk-size to use.*
8fc0: 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61  * for the nomina
8fd0: 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c  ted database. Al
8fe0: 6c 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61 73  locating databas
8ff0: 65 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20  e file space in 
9000: 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20  large.** chunks 
9010: 28 73 61 79 20 31 4d 42 20 61 74 20 61 20 74 69  (say 1MB at a ti
9020: 6d 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20  me), may reduce 
9030: 66 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67  file-system frag
9040: 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a  mentation and.**
9050: 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d   improve perform
9060: 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73  ance on some sys
9070: 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  tems..**.** <li>
9080: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46  [[SQLITE_FCNTL_F
9090: 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a  ILE_POINTER]].**
90a0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
90b0: 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d  TL_FILE_POINTER]
90c0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
90d0: 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e  to obtain a poin
90e0: 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73  ter.** to the [s
90f0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
9100: 65 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77  ect associated w
9110: 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72  ith a particular
9120: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
9130: 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 74 68  nection.  See th
9140: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  e [sqlite3_file_
9150: 63 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 75 6d  control()] docum
9160: 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20  entation for.** 
9170: 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
9180: 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  mation..**.** <l
9190: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
91a0: 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a  _SYNC_OMITTED]].
91b0: 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20  ** No longer in 
91c0: 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  use..**.** <li>[
91d0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59  [SQLITE_FCNTL_SY
91e0: 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  NC]].** The [SQL
91f0: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20  ITE_FCNTL_SYNC] 
9200: 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61  opcode is genera
9210: 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  ted internally b
9220: 79 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20  y SQLite and.** 
9230: 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20  sent to the VFS 
9240: 69 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f  immediately befo
9250: 72 65 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74  re the xSync met
9260: 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  hod is invoked o
9270: 6e 20 61 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  n a.** database 
9280: 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 2e  file descriptor.
9290: 20 4f 72 2c 20 69 66 20 74 68 65 20 78 53 79 6e   Or, if the xSyn
92a0: 63 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74 20  c method is not 
92b0: 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61  invoked .** beca
92c0: 75 73 65 20 74 68 65 20 75 73 65 72 20 68 61 73  use the user has
92d0: 20 63 6f 6e 66 69 67 75 72 65 64 20 53 51 4c 69   configured SQLi
92e0: 74 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41  te with .** [PRA
92f0: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20  GMA synchronous 
9300: 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f  | PRAGMA synchro
9310: 6e 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69 73 20  nous=OFF] it is 
9320: 69 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65  invoked in place
9330: 20 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53 79 6e   .** of the xSyn
9340: 63 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73  c method. In mos
9350: 74 20 63 61 73 65 73 2c 20 74 68 65 20 70 6f 69  t cases, the poi
9360: 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 20 70 61  nter argument pa
9370: 73 73 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 69  ssed with.** thi
9380: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69  s file-control i
9390: 73 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c  s NULL. However,
93a0: 20 69 66 20 74 68 65 20 64 61 74 61 62 61 73 65   if the database
93b0: 20 66 69 6c 65 20 69 73 20 62 65 69 6e 67 20 73   file is being s
93c0: 79 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61 72 74  ynced.** as part
93d0: 20 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61 74 61   of a multi-data
93e0: 62 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65  base commit, the
93f0: 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73   argument points
9400: 20 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e   to a nul-termin
9410: 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63  ated.** string c
9420: 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 74 72  ontaining the tr
9430: 61 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73 74 65  ansactions maste
9440: 72 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e  r-journal file n
9450: 61 6d 65 2e 20 56 46 53 65 73 20 74 68 61 74 20  ame. VFSes that 
9460: 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20  .** do not need 
9470: 74 68 69 73 20 73 69 67 6e 61 6c 20 73 68 6f 75  this signal shou
9480: 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f  ld silently igno
9490: 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20  re this opcode. 
94a0: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a  Applications .**
94b0: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c   should not call
94c0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
94d0: 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74  ontrol()] with t
94e0: 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f  his opcode as do
94f0: 69 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64  ing so may .** d
9500: 69 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61  isrupt the opera
9510: 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63  tion of the spec
9520: 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68  ialized VFSes th
9530: 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74  at do require it
9540: 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  .  .**.** <li>[[
9550: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d  SQLITE_FCNTL_COM
9560: 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a  MIT_PHASETWO]].*
9570: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
9580: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45  NTL_COMMIT_PHASE
9590: 54 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20 67  TWO] opcode is g
95a0: 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61  enerated interna
95b0: 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a  lly by SQLite.**
95c0: 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 74 68 65   and sent to the
95d0: 20 56 46 53 20 61 66 74 65 72 20 61 20 74 72 61   VFS after a tra
95e0: 6e 73 61 63 74 69 6f 6e 20 68 61 73 20 62 65 65  nsaction has bee
95f0: 6e 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65  n committed imme
9600: 64 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62  diately.** but b
9610: 65 66 6f 72 65 20 74 68 65 20 64 61 74 61 62 61  efore the databa
9620: 73 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20  se is unlocked. 
9630: 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 6e 6f  VFSes that do no
9640: 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e  t need this sign
9650: 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c  al.** should sil
9660: 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69  ently ignore thi
9670: 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63  s opcode. Applic
9680: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f  ations should no
9690: 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74  t call.** [sqlit
96a0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
96b0: 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63  )] with this opc
96c0: 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20  ode as doing so 
96d0: 6d 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20  may disrupt the 
96e0: 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66  .** operation of
96f0: 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64   the specialized
9700: 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72   VFSes that do r
9710: 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a  equire it.  .**.
9720: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9730: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52  FCNTL_WIN32_AV_R
9740: 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  ETRY]].** ^The [
9750: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
9760: 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63  32_AV_RETRY] opc
9770: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63  ode is used to c
9780: 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74  onfigure automat
9790: 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e  ic.** retry coun
97a0: 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73  ts and intervals
97b0: 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73   for certain dis
97c0: 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73  k I/O operations
97d0: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64   for the.** wind
97e0: 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64  ows [VFS] in ord
97f0: 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f  er to provide ro
9800: 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20  bustness in the 
9810: 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61  presence of.** a
9820: 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61  nti-virus progra
9830: 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c  ms.  By default,
9840: 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53   the windows VFS
9850: 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65   will retry file
9860: 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77   read,.** file w
9870: 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64  rite, and file d
9880: 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73  elete operations
9890: 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c   up to 10 times,
98a0: 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a   with a delay.**
98b0: 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f   of 25 milliseco
98c0: 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66  nds before the f
98d0: 69 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77  irst retry and w
98e0: 69 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e  ith the delay in
98f0: 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61  creasing.** by a
9900: 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20  n additional 25 
9910: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74  milliseconds wit
9920: 68 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e  h each subsequen
9930: 74 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a  t retry.  This.*
9940: 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20  * opcode allows 
9950: 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73  these two values
9960: 20 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64   (10 retries and
9970: 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   25 milliseconds
9980: 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f   of delay).** to
9990: 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54   be adjusted.  T
99a0: 68 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68  he values are ch
99b0: 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61  anged for all da
99c0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
99d0: 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65  ns.** within the
99e0: 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20   same process.  
99f0: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
9a00: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
9a10: 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20  array of two.** 
9a20: 69 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74  integers where t
9a30: 68 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72  he first integer
9a40: 20 69 20 74 68 65 20 6e 65 77 20 72 65 74 72 79   i the new retry
9a50: 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73   count and the s
9a60: 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72  econd.** integer
9a70: 20 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20   is the delay.  
9a80: 49 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65  If either intege
9a90: 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  r is negative, t
9aa0: 68 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a  hen the setting.
9ab0: 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65  ** is not change
9ac0: 64 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68  d but instead th
9ad0: 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66  e prior value of
9ae0: 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73   that setting is
9af0: 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f   written.** into
9b00: 20 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79   the array entry
9b10: 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63  , allowing the c
9b20: 75 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74  urrent retry set
9b30: 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69  tings to be.** i
9b40: 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68  nterrogated.  Th
9b50: 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65  e zDbName parame
9b60: 74 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a  ter is ignored..
9b70: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9b80: 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54  TE_FCNTL_PERSIST
9b90: 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  _WAL]].** ^The [
9ba0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52  SQLITE_FCNTL_PER
9bb0: 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65  SIST_WAL] opcode
9bc0: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20   is used to set 
9bd0: 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20  or query the.** 
9be0: 70 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20  persistent [WAL 
9bf0: 7c 20 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f  | Write Ahead Lo
9c00: 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20  g] setting.  By 
9c10: 64 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78  default, the aux
9c20: 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20  iliary.** write 
9c30: 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68  ahead log and sh
9c40: 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65  ared memory file
9c50: 73 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73  s used for trans
9c60: 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a  action control.*
9c70: 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61  * are automatica
9c80: 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e  lly deleted when
9c90: 20 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e   the latest conn
9ca0: 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61  ection to the da
9cb0: 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73  tabase.** closes
9cc0: 2e 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69  .  Setting persi
9cd0: 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63  stent WAL mode c
9ce0: 61 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65  auses those file
9cf0: 73 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74  s to persist aft
9d00: 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65  er.** close.  Pe
9d10: 72 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c  rsisting the fil
9d20: 65 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65  es is useful whe
9d30: 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65  n other processe
9d40: 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a  s that do not.**
9d50: 20 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d   have write perm
9d60: 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69  ission on the di
9d70: 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69  rectory containi
9d80: 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ng the database 
9d90: 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20  file want.** to 
9da0: 72 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73  read the databas
9db0: 65 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57  e file, as the W
9dc0: 41 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65  AL and shared me
9dd0: 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20  mory files must 
9de0: 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65  exist.** in orde
9df0: 72 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61  r for the databa
9e00: 73 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c  se to be readabl
9e10: 65 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70  e.  The fourth p
9e20: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b  arameter to.** [
9e30: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
9e40: 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73  trol()] for this
9e50: 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62   opcode should b
9e60: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
9e70: 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68  n integer..** Th
9e80: 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20  at integer is 0 
9e90: 74 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69  to disable persi
9ea0: 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f  stent WAL mode o
9eb0: 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65  r 1 to enable pe
9ec0: 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20  rsistent.** WAL 
9ed0: 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e  mode.  If the in
9ee0: 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65  teger is -1, the
9ef0: 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74  n it is overwrit
9f00: 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72  ten with the cur
9f10: 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73  rent.** WAL pers
9f20: 69 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e  istence setting.
9f30: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9f40: 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53  ITE_FCNTL_POWERS
9f50: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a  AFE_OVERWRITE]].
9f60: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
9f70: 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f  FCNTL_POWERSAFE_
9f80: 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64  OVERWRITE] opcod
9f90: 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74  e is used to set
9fa0: 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a   or query the.**
9fb0: 20 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77   persistent "pow
9fc0: 65 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65  ersafe-overwrite
9fd0: 22 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74  " or "PSOW" sett
9fe0: 69 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73  ing.  The PSOW s
9ff0: 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d  etting.** determ
a000: 69 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45  ines the [SQLITE
a010: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45  _IOCAP_POWERSAFE
a020: 5f 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 20  _OVERWRITE] bit 
a030: 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63  of the.** xDevic
a040: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
a050: 20 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f   methods. The fo
a060: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
a070: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  o.** [sqlite3_fi
a080: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f  le_control()] fo
a090: 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68  r this opcode sh
a0a0: 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65  ould be a pointe
a0b0: 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e  r to an integer.
a0c0: 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72  .** That integer
a0d0: 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
a0e0: 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64   zero-damage mod
a0f0: 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65  e or 1 to enable
a100: 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20   zero-damage.** 
a110: 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e  mode.  If the in
a120: 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65  teger is -1, the
a130: 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74  n it is overwrit
a140: 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72  ten with the cur
a150: 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d  rent.** zero-dam
a160: 61 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67  age mode setting
a170: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
a180: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57  LITE_FCNTL_OVERW
a190: 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  RITE]].** ^The [
a1a0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45  SQLITE_FCNTL_OVE
a1b0: 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69  RWRITE] opcode i
a1c0: 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c  s invoked by SQL
a1d0: 69 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e  ite after openin
a1e0: 67 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61  g.** a write tra
a1f0: 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69  nsaction to indi
a200: 63 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73  cate that, unles
a210: 73 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62  s it is rolled b
a220: 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20  ack for some.** 
a230: 72 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69  reason, the enti
a240: 72 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  re database file
a250: 20 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69   will be overwri
a260: 74 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 72  tten by the curr
a270: 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74  ent .** transact
a280: 69 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65  ion. This is use
a290: 64 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72  d by VACUUM oper
a2a0: 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ations..**.** <l
a2b0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
a2c0: 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54  _VFSNAME]].** ^T
a2d0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
a2e0: 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65  _VFSNAME] opcode
a2f0: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
a300: 6f 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73  obtain the names
a310: 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65   of.** all [VFSe
a320: 73 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 74  s] in the VFS st
a330: 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20  ack.  The names 
a340: 61 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73  are of all VFS s
a350: 68 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20  hims and the.** 
a360: 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76  final bottom-lev
a370: 65 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 74  el VFS are writt
a380: 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  en into memory o
a390: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a  btained from .**
a3a0: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
a3b0: 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75  ()] and the resu
a3c0: 6c 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20  lt is stored in 
a3d0: 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62  the char* variab
a3e0: 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66  le.** that the f
a3f0: 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
a400: 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  of [sqlite3_file
a410: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e  _control()] poin
a420: 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61  ts to..** The ca
a430: 6c 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69  ller is responsi
a440: 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20  ble for freeing 
a450: 74 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20  the memory when 
a460: 64 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a  done.  As with.*
a470: 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72  * all file-contr
a480: 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72  ol actions, ther
a490: 65 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65  e is no guarante
a4a0: 65 20 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c  e that this will
a4b0: 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20   actually.** do 
a4c0: 61 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65  anything.  Calle
a4d0: 72 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61  rs should initia
a4e0: 6c 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76  lize the char* v
a4f0: 61 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c  ariable to a NUL
a500: 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20  L.** pointer in 
a510: 63 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63  case this file-c
a520: 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d  ontrol is not im
a530: 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73  plemented.  This
a540: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a   file-control.**
a550: 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72   is intended for
a560: 20 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20   diagnostic use 
a570: 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  only..**.** <li>
a580: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  [[SQLITE_FCNTL_P
a590: 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e  RAGMA]].** ^When
a5a0: 65 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20  ever a [PRAGMA] 
a5b0: 73 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72  statement is par
a5c0: 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f  sed, an [SQLITE_
a5d0: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a  FCNTL_PRAGMA] .*
a5e0: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  * file control i
a5f0: 73 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70  s sent to the op
a600: 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  en [sqlite3_file
a610: 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70  ] object corresp
a620: 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65  onding.** to the
a630: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74   database file t
a640: 6f 20 77 68 69 63 68 20 74 68 65 20 70 72 61 67  o which the prag
a650: 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66  ma statement ref
a660: 65 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65  ers. ^The argume
a670: 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51  nt.** to the [SQ
a680: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
a690: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
a6a0: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a  is an array of.*
a6b0: 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74  * pointers to st
a6c0: 72 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69  rings (char**) i
a6d0: 6e 20 77 68 69 63 68 20 74 68 65 20 73 65 63 6f  n which the seco
a6e0: 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68  nd element of th
a6f0: 65 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68  e array.** is th
a700: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72  e name of the pr
a710: 61 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69  agma and the thi
a720: 72 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68  rd element is th
a730: 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  e argument to th
a740: 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e  e.** pragma or N
a750: 55 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d  ULL if the pragm
a760: 61 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e  a has no argumen
a770: 74 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72  t.  ^The handler
a780: 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49   for an.** [SQLI
a790: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
a7a0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61   file control ca
a7b0: 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b  n optionally mak
a7c0: 65 20 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d  e the first elem
a7d0: 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68  ent.** of the ch
a7e0: 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f  ar** argument po
a7f0: 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20  int to a string 
a800: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
a810: 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
a820: 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69  ].** or the equi
a830: 76 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20  valent and that 
a840: 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f  string will beco
a850: 6d 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  me the result of
a860: 20 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a   the pragma or.*
a870: 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  * the error mess
a880: 61 67 65 20 69 66 20 74 68 65 20 70 72 61 67 6d  age if the pragm
a890: 61 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65  a fails. ^If the
a8a0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  .** [SQLITE_FCNT
a8b0: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63  L_PRAGMA] file c
a8c0: 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b  ontrol returns [
a8d0: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d  SQLITE_NOTFOUND]
a8e0: 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a  , then normal .*
a8f0: 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65  * [PRAGMA] proce
a900: 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e  ssing continues.
a910: 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54    ^If the [SQLIT
a920: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a  E_FCNTL_PRAGMA].
a930: 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  ** file control 
a940: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
a950: 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61  OK], then the pa
a960: 72 73 65 72 20 61 73 73 75 6d 65 73 20 74 68 61  rser assumes tha
a970: 74 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73  t the.** VFS has
a980: 20 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41   handled the PRA
a990: 47 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74  GMA itself and t
a9a0: 68 65 20 70 61 72 73 65 72 20 67 65 6e 65 72 61  he parser genera
a9b0: 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70  tes a no-op.** p
a9c0: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
a9d0: 74 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  t.  ^If the [SQL
a9e0: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
a9f0: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  ] file control r
aa00: 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65  eturns.** any re
aa10: 73 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20  sult code other 
aa20: 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  than [SQLITE_OK]
aa30: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46   or [SQLITE_NOTF
aa40: 4f 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e  OUND], that mean
aa50: 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46  s.** that the VF
aa60: 53 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e  S encountered an
aa70: 20 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e   error while han
aa80: 64 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d  dling the [PRAGM
aa90: 41 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f  A] and the.** co
aaa0: 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65  mpilation of the
aab0: 20 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69   PRAGMA fails wi
aac0: 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54  th an error.  ^T
aad0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
aae0: 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65  _PRAGMA].** file
aaf0: 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20   control occurs 
ab00: 61 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  at the beginning
ab10: 20 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74 65   of pragma state
ab20: 6d 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e  ment analysis an
ab30: 64 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62  d so.** it is ab
ab40: 6c 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62  le to override b
ab50: 75 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d  uilt-in [PRAGMA]
ab60: 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
ab70: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
ab80: 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45  FCNTL_BUSYHANDLE
ab90: 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  R]].** ^The [SQL
aba0: 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41  ITE_FCNTL_BUSYHA
abb0: 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63  NDLER].** file-c
abc0: 6f 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e  ontrol may be in
abd0: 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20  voked by SQLite 
abe0: 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  on the database 
abf0: 66 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73  file handle.** s
ac00: 68 6f 72 74 6c 79 20 61 66 74 65 72 20 69 74 20  hortly after it 
ac10: 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64  is opened in ord
ac20: 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 61 20  er to provide a 
ac30: 63 75 73 74 6f 6d 20 56 46 53 20 77 69 74 68 20  custom VFS with 
ac40: 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65  access.** to the
ac50: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73   connections bus
ac60: 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y-handler callba
ac70: 63 6b 2e 20 54 68 65 20 61 72 67 75 6d 65 6e 74  ck. The argument
ac80: 20 69 73 20 6f 66 20 74 79 70 65 20 28 76 6f 69   is of type (voi
ac90: 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72  d **).** - an ar
aca0: 72 61 79 20 6f 66 20 74 77 6f 20 28 76 6f 69 64  ray of two (void
acb0: 20 2a 29 20 76 61 6c 75 65 73 2e 20 54 68 65 20   *) values. The 
acc0: 66 69 72 73 74 20 28 76 6f 69 64 20 2a 29 20 61  first (void *) a
acd0: 63 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a  ctually points.*
ace0: 2a 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20  * to a function 
acf0: 6f 66 20 74 79 70 65 20 28 69 6e 74 20 28 2a 29  of type (int (*)
ad00: 28 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72  (void *)). In or
ad10: 64 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68  der to invoke th
ad20: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a  e connections.**
ad30: 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74   busy-handler, t
ad40: 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  his function sho
ad50: 75 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  uld be invoked w
ad60: 69 74 68 20 74 68 65 20 73 65 63 6f 6e 64 20 28  ith the second (
ad70: 76 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68  void *) in.** th
ad80: 65 20 61 72 72 61 79 20 61 73 20 74 68 65 20 6f  e array as the o
ad90: 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 49 66  nly argument. If
ada0: 20 69 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d   it returns non-
adb0: 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f  zero, then the o
adc0: 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75  peration.** shou
add0: 6c 64 20 62 65 20 72 65 74 72 69 65 64 2e 20 49  ld be retried. I
ade0: 66 20 69 74 20 72 65 74 75 72 6e 73 20 7a 65 72  f it returns zer
adf0: 6f 2c 20 74 68 65 20 63 75 73 74 6f 6d 20 56 46  o, the custom VF
ae00: 53 20 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e  S should abandon
ae10: 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20   the.** current 
ae20: 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  operation..**.**
ae30: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
ae40: 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45  NTL_TEMPFILENAME
ae50: 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69  ]].** ^Applicati
ae60: 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68  on can invoke th
ae70: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
ae80: 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69  TEMPFILENAME] fi
ae90: 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f  le-control.** to
aea0: 20 68 61 76 65 20 53 51 4c 69 74 65 20 67 65 6e   have SQLite gen
aeb0: 65 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f  erate a.** tempo
aec0: 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 20 75 73  rary filename us
aed0: 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67  ing the same alg
aee0: 6f 72 69 74 68 6d 20 74 68 61 74 20 69 73 20 66  orithm that is f
aef0: 6f 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65 72  ollowed to gener
af00: 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79  ate.** temporary
af10: 20 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54   filenames for T
af20: 45 4d 50 20 74 61 62 6c 65 73 20 61 6e 64 20 6f  EMP tables and o
af30: 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 20 75 73  ther internal us
af40: 65 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67 75  es.  The.** argu
af50: 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 61  ment should be a
af60: 20 63 68 61 72 2a 2a 20 77 68 69 63 68 20 77 69   char** which wi
af70: 6c 6c 20 62 65 20 66 69 6c 6c 65 64 20 77 69 74  ll be filled wit
af80: 68 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a  h the filename.*
af90: 2a 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d  * written into m
afa0: 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
afb0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
afc0: 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 63 61 6c  loc()].  The cal
afd0: 6c 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e  ler should.** in
afe0: 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72  voke [sqlite3_fr
aff0: 65 65 28 29 5d 20 6f 6e 20 74 68 65 20 72 65 73  ee()] on the res
b000: 75 6c 74 20 74 6f 20 61 76 6f 69 64 20 61 20 6d  ult to avoid a m
b010: 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a  emory leak..**.*
b020: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
b030: 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d  CNTL_MMAP_SIZE]]
b040: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
b050: 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d  FCNTL_MMAP_SIZE]
b060: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
b070: 20 75 73 65 64 20 74 6f 20 71 75 65 72 79 20 6f   used to query o
b080: 72 20 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78  r set the.** max
b090: 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62  imum number of b
b0a0: 79 74 65 73 20 74 68 61 74 20 77 69 6c 6c 20 62  ytes that will b
b0b0: 65 20 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72  e used for memor
b0c0: 79 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a  y-mapped I/O..**
b0d0: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
b0e0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
b0f0: 76 61 6c 75 65 20 6f 66 20 74 79 70 65 20 73 71  value of type sq
b100: 6c 69 74 65 33 5f 69 6e 74 36 34 20 74 68 61 74  lite3_int64 that
b110: 0a 2a 2a 20 69 73 20 61 6e 20 61 64 76 69 73 6f  .** is an adviso
b120: 72 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  ry maximum numbe
b130: 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
b140: 65 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79  e file to memory
b150: 20 6d 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f   map.  The.** po
b160: 69 6e 74 65 72 20 69 73 20 6f 76 65 72 77 72 69  inter is overwri
b170: 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 6f 6c  tten with the ol
b180: 64 20 76 61 6c 75 65 2e 20 20 54 68 65 20 6c 69  d value.  The li
b190: 6d 69 74 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  mit is not chang
b1a0: 65 64 20 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c  ed if.** the val
b1b0: 75 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f  ue originally po
b1c0: 69 6e 74 65 64 20 74 6f 20 69 73 20 6e 65 67 61  inted to is nega
b1d0: 74 69 76 65 2c 20 61 6e 64 20 73 6f 20 74 68 65  tive, and so the
b1e0: 20 63 75 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a   current limit .
b1f0: 2a 2a 20 63 61 6e 20 62 65 20 71 75 65 72 69 65  ** can be querie
b200: 64 20 62 79 20 70 61 73 73 69 6e 67 20 69 6e 20  d by passing in 
b210: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e  a pointer to a n
b220: 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2e 20  egative number. 
b230: 20 54 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f   This.** file-co
b240: 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 69 6e  ntrol is used in
b250: 74 65 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c  ternally to impl
b260: 65 6d 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d  ement [PRAGMA mm
b270: 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20  ap_size]..**.** 
b280: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
b290: 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68  TL_TRACE]].** Th
b2a0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
b2b0: 54 52 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74  TRACE] file cont
b2c0: 72 6f 6c 20 70 72 6f 76 69 64 65 73 20 61 64 76  rol provides adv
b2d0: 69 73 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f  isory informatio
b2e0: 6e 0a 2a 2a 20 74 6f 20 74 68 65 20 56 46 53 20  n.** to the VFS 
b2f0: 61 62 6f 75 74 20 77 68 61 74 20 74 68 65 20 68  about what the h
b300: 69 67 68 65 72 20 6c 61 79 65 72 73 20 6f 66 20  igher layers of 
b310: 74 68 65 20 53 51 4c 69 74 65 20 73 74 61 63 6b  the SQLite stack
b320: 20 61 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54   are doing..** T
b330: 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  his file control
b340: 20 69 73 20 75 73 65 64 20 62 79 20 73 6f 6d 65   is used by some
b350: 20 56 46 53 20 61 63 74 69 76 69 74 79 20 74 72   VFS activity tr
b360: 61 63 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a  acing [shims]..*
b370: 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69  * The argument i
b380: 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  s a zero-termina
b390: 74 65 64 20 73 74 72 69 6e 67 2e 20 20 48 69 67  ted string.  Hig
b3a0: 68 65 72 20 6c 61 79 65 72 73 20 69 6e 20 74 68  her layers in th
b3b0: 65 0a 2a 2a 20 53 51 4c 69 74 65 20 73 74 61 63  e.** SQLite stac
b3c0: 6b 20 6d 61 79 20 67 65 6e 65 72 61 74 65 20 69  k may generate i
b3d0: 6e 73 74 61 6e 63 65 73 20 6f 66 20 74 68 69 73  nstances of this
b3e0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66   file control if
b3f0: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
b400: 55 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d  USE_FCNTL_TRACE]
b410: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
b420: 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e  tion is enabled.
b430: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
b440: 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f  ITE_FCNTL_HAS_MO
b450: 56 45 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  VED]].** The [SQ
b460: 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d  LITE_FCNTL_HAS_M
b470: 4f 56 45 44 5d 20 66 69 6c 65 20 63 6f 6e 74 72  OVED] file contr
b480: 6f 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69 74  ol interprets it
b490: 73 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61 0a  s argument as a.
b4a0: 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e  ** pointer to an
b4b0: 20 69 6e 74 65 67 65 72 20 61 6e 64 20 69 74 20   integer and it 
b4c0: 77 72 69 74 65 73 20 61 20 62 6f 6f 6c 65 61 6e  writes a boolean
b4d0: 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67   into that integ
b4e0: 65 72 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20  er depending.** 
b4f0: 6f 6e 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  on whether or no
b500: 74 20 74 68 65 20 66 69 6c 65 20 68 61 73 20 62  t the file has b
b510: 65 65 6e 20 72 65 6e 61 6d 65 64 2c 20 6d 6f 76  een renamed, mov
b520: 65 64 2c 20 6f 72 20 64 65 6c 65 74 65 64 20 73  ed, or deleted s
b530: 69 6e 63 65 20 69 74 0a 2a 2a 20 77 61 73 20 66  ince it.** was f
b540: 69 72 73 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a  irst opened..**.
b550: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </ul>.*/.#def
b560: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
b570: 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20  _LOCKSTATE      
b580: 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
b590: 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f  ne SQLITE_GET_LO
b5a0: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20  CKPROXYFILE     
b5b0: 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
b5c0: 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43  e SQLITE_SET_LOC
b5d0: 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20  KPROXYFILE      
b5e0: 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
b5f0: 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52   SQLITE_LAST_ERR
b600: 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 20  NO              
b610: 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20        4.#define 
b620: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
b630: 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20 20 20  E_HINT          
b640: 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53       5.#define S
b650: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e  QLITE_FCNTL_CHUN
b660: 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 20  K_SIZE          
b670: 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51      6.#define SQ
b680: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f  LITE_FCNTL_FILE_
b690: 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 20  POINTER         
b6a0: 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c     7.#define SQL
b6b0: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f  ITE_FCNTL_SYNC_O
b6c0: 4d 49 54 54 45 44 20 20 20 20 20 20 20 20 20 20  MITTED          
b6d0: 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    8.#define SQLI
b6e0: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41  TE_FCNTL_WIN32_A
b6f0: 56 5f 52 45 54 52 59 20 20 20 20 20 20 20 20 20  V_RETRY         
b700: 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   9.#define SQLIT
b710: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
b720: 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 31  WAL            1
b730: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
b740: 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45  _FCNTL_OVERWRITE
b750: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 31                11
b760: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b770: 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20  FCNTL_VFSNAME   
b780: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 32 0a               12.
b790: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
b7a0: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
b7b0: 56 45 52 57 52 49 54 45 20 20 20 20 31 33 0a 23  VERWRITE    13.#
b7c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
b7d0: 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20 20 20 20  NTL_PRAGMA      
b7e0: 20 20 20 20 20 20 20 20 20 20 20 31 34 0a 23 64             14.#d
b7f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
b800: 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 20 20  TL_BUSYHANDLER  
b810: 20 20 20 20 20 20 20 20 20 20 31 35 0a 23 64 65            15.#de
b820: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
b830: 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20  L_TEMPFILENAME  
b840: 20 20 20 20 20 20 20 20 20 31 36 0a 23 64 65 66           16.#def
b850: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
b860: 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 20 20  _MMAP_SIZE      
b870: 20 20 20 20 20 20 20 20 31 38 0a 23 64 65 66 69          18.#defi
b880: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
b890: 54 52 41 43 45 20 20 20 20 20 20 20 20 20 20 20  TRACE           
b8a0: 20 20 20 20 20 20 20 31 39 0a 23 64 65 66 69 6e         19.#defin
b8b0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48  e SQLITE_FCNTL_H
b8c0: 41 53 5f 4d 4f 56 45 44 20 20 20 20 20 20 20 20  AS_MOVED        
b8d0: 20 20 20 20 20 20 32 30 0a 23 64 65 66 69 6e 65        20.#define
b8e0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59   SQLITE_FCNTL_SY
b8f0: 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20  NC              
b900: 20 20 20 20 20 32 31 0a 23 64 65 66 69 6e 65 20       21.#define 
b910: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d  SQLITE_FCNTL_COM
b920: 4d 49 54 5f 50 48 41 53 45 54 57 4f 20 20 20 20  MIT_PHASETWO    
b930: 20 20 20 20 32 32 0a 0a 2f 2a 0a 2a 2a 20 43 41      22../*.** CA
b940: 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61  PI3REF: Mutex Ha
b950: 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d  ndle.**.** The m
b960: 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68  utex module with
b970: 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65  in SQLite define
b980: 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  s [sqlite3_mutex
b990: 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62  ] to be an.** ab
b9a0: 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20  stract type for 
b9b0: 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20  a mutex object. 
b9c0: 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
b9d0: 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20   never looks.** 
b9e0: 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  at the internal 
b9f0: 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f  representation o
ba00: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75  f an [sqlite3_mu
ba10: 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a  tex].  It only.*
ba20: 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69  * deals with poi
ba30: 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71  nters to the [sq
ba40: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a  lite3_mutex] obj
ba50: 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78  ect..**.** Mutex
ba60: 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75  es are created u
ba70: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  sing [sqlite3_mu
ba80: 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f  tex_alloc()]..*/
ba90: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
baa0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71  sqlite3_mutex sq
bab0: 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a  lite3_mutex;../*
bac0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
bad0: 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63   Interface Objec
bae0: 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  t.**.** An insta
baf0: 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74  nce of the sqlit
bb00: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65  e3_vfs object de
bb10: 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66  fines the interf
bb20: 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74  ace between.** t
bb30: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61  he SQLite core a
bb40: 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  nd the underlyin
bb50: 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  g operating syst
bb60: 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a  em.  The "vfs".*
bb70: 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  * in the name of
bb80: 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e   the object stan
bb90: 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20  ds for "virtual 
bba0: 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20 53  file system".  S
bbb0: 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c  ee.** the [VFS |
bbc0: 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74 69   VFS documentati
bbd0: 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72 20  on] for further 
bbe0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
bbf0: 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20  ** The value of 
bc00: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65  the iVersion fie
bc10: 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20  ld is initially 
bc20: 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72  1 but may be lar
bc30: 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65  ger in.** future
bc40: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
bc50: 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c  ite.  Additional
bc60: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
bc70: 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a  ppended to this.
bc80: 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74  ** object when t
bc90: 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75  he iVersion valu
bca0: 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20  e is increased. 
bcb0: 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 73   Note that the s
bcc0: 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74  tructure.** of t
bcd0: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  he sqlite3_vfs o
bce0: 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e  bject changes in
bcf0: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
bd00: 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69   between.** SQLi
bd10: 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39  te version 3.5.9
bd20: 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79   and 3.6.0 and y
bd30: 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  et the iVersion 
bd40: 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a  field was not.**
bd50: 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a   modified..**.**
bd60: 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69   The szOsFile fi
bd70: 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20  eld is the size 
bd80: 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65  of the subclasse
bd90: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  d [sqlite3_file]
bda0: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73  .** structure us
bdb0: 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20  ed by this VFS. 
bdc0: 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74   mxPathname is t
bdd0: 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
bde0: 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61  h of.** a pathna
bdf0: 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a  me in this VFS..
be00: 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64  **.** Registered
be10: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a   sqlite3_vfs obj
be20: 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e  ects are kept on
be30: 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66   a linked list f
be40: 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20  ormed by.** the 
be50: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20  pNext pointer.  
be60: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  The [sqlite3_vfs
be70: 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20  _register()].** 
be80: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  and [sqlite3_vfs
be90: 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69  _unregister()] i
bea0: 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65  nterfaces manage
beb0: 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e   this list.** in
bec0: 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77   a thread-safe w
bed0: 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ay.  The [sqlite
bee0: 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e  3_vfs_find()] in
bef0: 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63  terface.** searc
bf00: 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e  hes the list.  N
bf10: 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c 69  either the appli
bf20: 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20  cation code nor 
bf30: 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65  the VFS.** imple
bf40: 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64  mentation should
bf50: 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 70   use the pNext p
bf60: 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  ointer..**.** Th
bf70: 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73  e pNext field is
bf80: 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20   the only field 
bf90: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  in the sqlite3_v
bfa0: 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  fs.** structure 
bfb0: 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
bfc0: 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53   ever modify.  S
bfd0: 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20  QLite will only 
bfe0: 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64  access.** or mod
bff0: 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77  ify this field w
c000: 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70  hile holding a p
c010: 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63  articular static
c020: 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61   mutex..** The a
c030: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
c040: 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61  d never modify a
c050: 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74  nything within t
c060: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a  he sqlite3_vfs.*
c070: 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68  * object once th
c080: 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65  e object has bee
c090: 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a  n registered..**
c0a0: 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69  .** The zName fi
c0b0: 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61  eld holds the na
c0c0: 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f  me of the VFS mo
c0d0: 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20  dule.  The name 
c0e0: 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75  must.** be uniqu
c0f0: 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53  e across all VFS
c100: 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20   modules..**.** 
c110: 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f  [[sqlite3_vfs.xO
c120: 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65  pen]].** ^SQLite
c130: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
c140: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
c150: 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65  arameter to xOpe
c160: 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61  n.** is either a
c170: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72   NULL pointer or
c180: 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64   string obtained
c190: 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61  .** from xFullPa
c1a0: 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61 6e  thname() with an
c1b0: 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 78   optional suffix
c1c0: 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61   added..** ^If a
c1d0: 20 73 75 66 66 69 78 20 69 73 20 61 64 64 65 64   suffix is added
c1e0: 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d   to the zFilenam
c1f0: 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74 20  e parameter, it 
c200: 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20  will.** consist 
c210: 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 20  of a single "-" 
c220: 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77  character follow
c230: 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68  ed by no more th
c240: 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75  an.** 11 alphanu
c250: 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22  meric and/or "-"
c260: 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20   characters..** 
c270: 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 20  ^SQLite further 
c280: 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a  guarantees that.
c290: 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 69  ** the string wi
c2a0: 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20  ll be valid and 
c2b0: 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20  unchanged until 
c2c0: 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63  xClose() is.** c
c2d0: 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f  alled. Because o
c2e0: 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73  f the previous s
c2f0: 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20  entence,.** the 
c300: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63  [sqlite3_file] c
c310: 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20  an safely store 
c320: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
c330: 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20  .** filename if 
c340: 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65  it needs to reme
c350: 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d  mber the filenam
c360: 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f  e for some reaso
c370: 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69  n..** If the zFi
c380: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
c390: 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 4e   to xOpen is a N
c3a0: 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
c3b0: 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69   xOpen.** must i
c3c0: 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65  nvent its own te
c3d0: 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72  mporary name for
c3e0: 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 65   the file.  ^Whe
c3f0: 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46  never the .** xF
c400: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
c410: 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c  r is NULL it wil
c420: 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61  l also be the ca
c430: 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66  se that the.** f
c440: 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 77  lags parameter w
c450: 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c  ill include [SQL
c460: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
c470: 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54  NCLOSE]..**.** T
c480: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
c490: 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63  t to xOpen() inc
c4a0: 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73  ludes all bits s
c4b0: 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61  et in.** the fla
c4c0: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  gs argument to [
c4d0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
c4e0: 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69  )].  Or if [sqli
c4f0: 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f  te3_open()].** o
c500: 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  r [sqlite3_open1
c510: 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68  6()] is used, th
c520: 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65  en flags include
c530: 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53  s at least.** [S
c540: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
c550: 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f  RITE] | [SQLITE_
c560: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a  OPEN_CREATE]. .*
c570: 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65  * If xOpen() ope
c580: 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f  ns a file read-o
c590: 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74 73  nly then it sets
c5a0: 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a   *pOutFlags to.*
c5b0: 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54  * include [SQLIT
c5c0: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
c5d0: 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e  .  Other bits in
c5e0: 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20   *pOutFlags may 
c5f0: 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28  be set..**.** ^(
c600: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f  SQLite will also
c610: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20   add one of the 
c620: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20  following flags 
c630: 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a  to the xOpen().*
c640: 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e  * call, dependin
c650: 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20  g on the object 
c660: 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a  being opened:.**
c670: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
c680: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
c690: 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  AIN_DB].** <li> 
c6a0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
c6b0: 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  IN_JOURNAL].** <
c6c0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
c6d0: 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c  N_TEMP_DB].** <l
c6e0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
c6f0: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  _TEMP_JOURNAL].*
c700: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
c710: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
c720: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
c730: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52  ITE_OPEN_SUBJOUR
c740: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
c750: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
c760: 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  R_JOURNAL].** <l
c770: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
c780: 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e  _WAL].** </ul>)^
c790: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20  .**.** The file 
c7a0: 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  I/O implementati
c7b0: 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f  on can use the o
c7c0: 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73  bject type flags
c7d0: 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68   to.** change th
c7e0: 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 77  e way it deals w
c7f0: 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20  ith files.  For 
c800: 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c  example, an appl
c810: 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20  ication.** that 
c820: 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62  does not care ab
c830: 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 65  out crash recove
c840: 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d  ry or rollback m
c850: 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65  ight make.** the
c860: 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e   open of a journ
c870: 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e  al file a no-op.
c880: 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 73    Writes to this
c890: 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a   journal would.*
c8a0: 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73  * also be no-ops
c8b0: 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70  , and any attemp
c8c0: 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f  t to read the jo
c8d0: 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75  urnal would retu
c8e0: 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45  rn.** SQLITE_IOE
c8f0: 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c  RR.  Or the impl
c900: 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74  ementation might
c910: 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20   recognize that 
c920: 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  a database.** fi
c930: 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67  le will be doing
c940: 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65   page-aligned se
c950: 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77  ctor reads and w
c960: 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f  rites in a rando
c970: 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73  m.** order and s
c980: 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75  et up its I/O su
c990: 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e  bsystem accordin
c9a0: 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  gly..**.** SQLit
c9b0: 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64  e might also add
c9c0: 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
c9d0: 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74  owing flags to t
c9e0: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a  he xOpen method:
c9f0: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
ca00: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  li> [SQLITE_OPEN
ca10: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a  _DELETEONCLOSE].
ca20: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
ca30: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a  OPEN_EXCLUSIVE].
ca40: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54  ** </ul>.**.** T
ca50: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
ca60: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66  DELETEONCLOSE] f
ca70: 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69  lag means the fi
ca80: 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  le should be.** 
ca90: 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20  deleted when it 
caa0: 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65  is closed.  ^The
cab0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
cac0: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20  LETEONCLOSE].** 
cad0: 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20  will be set for 
cae0: 54 45 4d 50 20 64 61 74 61 62 61 73 65 73 20 61  TEMP databases a
caf0: 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c  nd their journal
cb00: 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20  s, transient.** 
cb10: 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20 73  databases, and s
cb20: 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a  ubjournals..**.*
cb30: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  * ^The [SQLITE_O
cb40: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66  PEN_EXCLUSIVE] f
cb50: 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20 75 73  lag is always us
cb60: 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f  ed in conjunctio
cb70: 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53  n.** with the [S
cb80: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
cb90: 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61  E] flag, which a
cba0: 72 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79  re both directly
cbb0: 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f  .** analogous to
cbc0: 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20   the O_EXCL and 
cbd0: 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66  O_CREAT flags of
cbe0: 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28   the POSIX open(
cbf0: 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53  ).** API.  The S
cc00: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
cc10: 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20  SIVE flag, when 
cc20: 70 61 69 72 65 64 20 77 69 74 68 20 74 68 65 20  paired with the 
cc30: 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  .** SQLITE_OPEN_
cc40: 43 52 45 41 54 45 2c 20 69 73 20 75 73 65 64 20  CREATE, is used 
cc50: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
cc60: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77   file should alw
cc70: 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65  ays.** be create
cc80: 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20 69  d, and that it i
cc90: 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74  s an error if it
cca0: 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e   already exists.
ccb0: 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74  .** It is <i>not
ccc0: 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64  </i> used to ind
ccd0: 69 63 61 74 65 20 74 68 65 20 66 69 6c 65 20 73  icate the file s
cce0: 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20  hould be opened 
ccf0: 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76  .** for exclusiv
cd00: 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20  e access..**.** 
cd10: 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69  ^At least szOsFi
cd20: 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  le bytes of memo
cd30: 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64  ry are allocated
cd40: 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f   by SQLite.** to
cd50: 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69   hold the  [sqli
cd60: 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74  te3_file] struct
cd70: 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68  ure passed as th
cd80: 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d  e third.** argum
cd90: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54  ent to xOpen.  T
cda0: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  he xOpen method 
cdb0: 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f  does not have to
cdc0: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65  .** allocate the
cdd0: 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 73   structure; it s
cde0: 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20  hould just fill 
cdf0: 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61  it in.  Note tha
ce00: 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d  t.** the xOpen m
ce10: 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74  ethod must set t
ce20: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
ce30: 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68  pMethods to eith
ce40: 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73  er.** a valid [s
ce50: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
ce60: 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20  s] object or to 
ce70: 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73  NULL.  xOpen mus
ce80: 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65  t do.** this eve
ce90: 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61  n if the open fa
cea0: 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70  ils.  SQLite exp
ceb0: 65 63 74 73 20 74 68 61 74 20 74 68 65 20 73 71  ects that the sq
cec0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
ced0: 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77  ods.** element w
cee0: 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74  ill be valid aft
cef0: 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73  er xOpen returns
cf00: 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74   regardless of t
cf10: 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72  he success.** or
cf20: 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20   failure of the 
cf30: 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a  xOpen call..**.*
cf40: 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  * [[sqlite3_vfs.
cf50: 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68  xAccess]].** ^Th
cf60: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
cf70: 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61   to xAccess() ma
cf80: 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43  y be [SQLITE_ACC
cf90: 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74  ESS_EXISTS].** t
cfa0: 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 65  o test for the e
cfb0: 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69  xistence of a fi
cfc0: 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41  le, or [SQLITE_A
cfd0: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d  CCESS_READWRITE]
cfe0: 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74   to.** test whet
cff0: 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72 65  her a file is re
d000: 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61  adable and writa
d010: 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ble, or [SQLITE_
d020: 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20  ACCESS_READ].** 
d030: 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72 20  to test whether 
d040: 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61  a file is at lea
d050: 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54  st readable.   T
d060: 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61  he file can be a
d070: 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  .** directory..*
d080: 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  *.** ^SQLite wil
d090: 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74  l always allocat
d0a0: 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74  e at least mxPat
d0b0: 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f  hname+1 bytes fo
d0c0: 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20  r the.** output 
d0d0: 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68  buffer xFullPath
d0e0: 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74  name.  The exact
d0f0: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74   size of the out
d100: 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  put buffer.** is
d110: 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20   also passed as 
d120: 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  a parameter to b
d130: 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66  oth  methods. If
d140: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66   the output buff
d150: 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72  er.** is not lar
d160: 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49  ge enough, [SQLI
d170: 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f  TE_CANTOPEN] sho
d180: 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
d190: 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a   Since this is.*
d1a0: 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66  * handled as a f
d1b0: 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51  atal error by SQ
d1c0: 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d  Lite, vfs implem
d1d0: 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  entations should
d1e0: 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20   endeavor.** to 
d1f0: 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20  prevent this by 
d200: 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61  setting mxPathna
d210: 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65  me to a sufficie
d220: 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65  ntly large value
d230: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e  ..**.** The xRan
d240: 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65  domness(), xSlee
d250: 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69 6d  p(), xCurrentTim
d260: 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e  e(), and xCurren
d270: 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20  tTimeInt64().** 
d280: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 6e  interfaces are n
d290: 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61  ot strictly a pa
d2a0: 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79  rt of the filesy
d2b0: 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61  stem, but they a
d2c0: 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69  re.** included i
d2d0: 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74  n the VFS struct
d2e0: 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65  ure for complete
d2f0: 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61  ness..** The xRa
d300: 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74  ndomness() funct
d310: 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ion attempts to 
d320: 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79  return nBytes by
d330: 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71  tes.** of good-q
d340: 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73  uality randomnes
d350: 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68  s into zOut.  Th
d360: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69  e return value i
d370: 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20  s.** the actual 
d380: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
d390: 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62  of randomness ob
d3a0: 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78  tained..** The x
d3b0: 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63  Sleep() method c
d3c0: 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e  auses the callin
d3d0: 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65  g thread to slee
d3e0: 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73  p for at.** leas
d3f0: 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
d400: 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76  microseconds giv
d410: 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72 65  en.  ^The xCurre
d420: 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68  ntTime().** meth
d430: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c  od returns a Jul
d440: 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66  ian Day Number f
d450: 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  or the current d
d460: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73 0a  ate and time as.
d470: 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f  ** a floating po
d480: 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54  int value..** ^T
d490: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  he xCurrentTimeI
d4a0: 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72 65  nt64() method re
d4b0: 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74  turns, as an int
d4c0: 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e  eger, the Julian
d4d0: 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 6d  .** Day Number m
d4e0: 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36 34  ultiplied by 864
d4f0: 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62 65  00000 (the numbe
d500: 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
d510: 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f  s in .** a 24-ho
d520: 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53  ur day).  .** ^S
d530: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74  QLite will use t
d540: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  he xCurrentTimeI
d550: 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74 6f  nt64() method to
d560: 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e 74   get the current
d570: 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d  .** date and tim
d580: 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f 64  e if that method
d590: 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28 69   is available (i
d5a0: 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32 20  f iVersion is 2 
d5b0: 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 61  or .** greater a
d5c0: 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  nd the function 
d5d0: 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
d5e0: 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 61  ULL) and will fa
d5f0: 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43  ll back.** to xC
d600: 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66 20  urrentTime() if 
d610: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
d620: 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61 62  4() is unavailab
d630: 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78  le..**.** ^The x
d640: 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c  SetSystemCall(),
d650: 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 28   xGetSystemCall(
d660: 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73 74  ), and xNestSyst
d670: 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 61  emCall() interfa
d680: 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75  ces.** are not u
d690: 73 65 64 20 62 79 20 74 68 65 20 53 51 4c 69 74  sed by the SQLit
d6a0: 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20 6f  e core.  These o
d6b0: 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63  ptional interfac
d6c0: 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a  es are provided.
d6d0: 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65 73  ** by some VFSes
d6e0: 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20 74   to facilitate t
d6f0: 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56 46  esting of the VF
d700: 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 72  S code. By overr
d710: 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d  iding .** system
d720: 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e 63   calls with func
d730: 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 20  tions under its 
d740: 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 20  control, a test 
d750: 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73  program can.** s
d760: 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20 61  imulate faults a
d770: 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 69  nd error conditi
d780: 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20 6f  ons that would o
d790: 74 68 65 72 77 69 73 65 20 62 65 20 64 69 66 66  therwise be diff
d7a0: 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f  icult.** or impo
d7b0: 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 65  ssible to induce
d7c0: 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 73 79  .  The set of sy
d7d0: 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 20  stem calls that 
d7e0: 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65  can be overridde
d7f0: 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f 6d  n.** varies from
d800: 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f 74   one VFS to anot
d810: 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e  her, and from on
d820: 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65  e version of the
d830: 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68 65   same VFS to the
d840: 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69  .** next.  Appli
d850: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65  cations that use
d860: 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
d870: 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 61 72  s must be prepar
d880: 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72  ed for any.** or
d890: 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 6e   all of these in
d8a0: 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 20 4e  terfaces to be N
d8b0: 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 72  ULL or for their
d8c0: 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68 61   behavior to cha
d8d0: 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20  nge.** from one 
d8e0: 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e  release to the n
d8f0: 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ext.  Applicatio
d900: 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 65  ns must not atte
d910: 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a  mpt to access.**
d920: 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d 65   any of these me
d930: 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 56 65  thods if the iVe
d940: 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 53  rsion of the VFS
d950: 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33 2e   is less than 3.
d960: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
d970: 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73  ct sqlite3_vfs s
d980: 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 65  qlite3_vfs;.type
d990: 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74  def void (*sqlit
d9a0: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 28  e3_syscall_ptr)(
d9b0: 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73 71  void);.struct sq
d9c0: 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e  lite3_vfs {.  in
d9d0: 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20  t iVersion;     
d9e0: 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74         /* Struct
d9f0: 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  ure version numb
da00: 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33 29  er (currently 3)
da10: 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69   */.  int szOsFi
da20: 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  le;            /
da30: 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61  * Size of subcla
da40: 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c  ssed sqlite3_fil
da50: 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74  e */.  int mxPat
da60: 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20  hname;          
da70: 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20  /* Maximum file 
da80: 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20  pathname length 
da90: 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73  */.  sqlite3_vfs
daa0: 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a   *pNext;      /*
dab0: 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 64   Next registered
dac0: 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20   VFS */.  const 
dad0: 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20  char *zName;    
dae0: 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
daf0: 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20  is virtual file 
db00: 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64  system */.  void
db10: 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20   *pAppData;     
db20: 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20       /* Pointer 
db30: 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73  to application-s
db40: 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a  pecific data */.
db50: 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73    int (*xOpen)(s
db60: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
db70: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
db80: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20  sqlite3_file*,. 
db90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e                in
dba0: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f  t flags, int *pO
dbb0: 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20  utFlags);.  int 
dbc0: 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74  (*xDelete)(sqlit
dbd0: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
dbe0: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
dbf0: 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20  syncDir);.  int 
dc00: 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 74  (*xAccess)(sqlit
dc10: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
dc20: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
dc30: 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73  flags, int *pRes
dc40: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  Out);.  int (*xF
dc50: 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c  ullPathname)(sql
dc60: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
dc70: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
dc80: 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f  t nOut, char *zO
dc90: 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78  ut);.  void *(*x
dca0: 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  DlOpen)(sqlite3_
dcb0: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
dcc0: 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20   *zFilename);.  
dcd0: 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29  void (*xDlError)
dce0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
dcf0: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
dd00: 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64  zErrMsg);.  void
dd10: 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c   (*(*xDlSym)(sql
dd20: 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c  ite3_vfs*,void*,
dd30: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79   const char *zSy
dd40: 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20  mbol))(void);.  
dd50: 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29  void (*xDlClose)
dd60: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76  (sqlite3_vfs*, v
dd70: 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  oid*);.  int (*x
dd80: 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69  Randomness)(sqli
dd90: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42  te3_vfs*, int nB
dda0: 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29  yte, char *zOut)
ddb0: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70  ;.  int (*xSleep
ddc0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
ddd0: 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73  int microseconds
dde0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  );.  int (*xCurr
ddf0: 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33  entTime)(sqlite3
de00: 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b  _vfs*, double*);
de10: 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73  .  int (*xGetLas
de20: 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f  tError)(sqlite3_
de30: 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20  vfs*, int, char 
de40: 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  *);.  /*.  ** Th
de50: 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
de60: 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 31  are in version 1
de70: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
de80: 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64  fs object.  ** d
de90: 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73  efinition.  Thos
dea0: 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72  e that follow ar
deb0: 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73 69  e added in versi
dec0: 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 20  on 2 or later.  
ded0: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  */.  int (*xCurr
dee0: 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73 71  entTimeInt64)(sq
def0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69  lite3_vfs*, sqli
df00: 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f  te3_int64*);.  /
df10: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
df20: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
df30: 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 32  versions 1 and 2
df40: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
df50: 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20  fs object..  ** 
df60: 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 20  Those below are 
df70: 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61 6e  for version 3 an
df80: 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a  d greater..  */.
df90: 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73 74    int (*xSetSyst
dfa0: 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f  emCall)(sqlite3_
dfb0: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
dfc0: 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33   *zName, sqlite3
dfd0: 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20  _syscall_ptr);. 
dfe0: 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c   sqlite3_syscall
dff0: 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 74 65  _ptr (*xGetSyste
e000: 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76  mCall)(sqlite3_v
e010: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
e020: 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74  *zName);.  const
e030: 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 79   char *(*xNextSy
e040: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
e050: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
e060: 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a  ar *zName);.  /*
e070: 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
e080: 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
e090: 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 67  ersions 1 throug
e0a0: 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69 74  h 3 of the sqlit
e0b0: 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20  e_vfs object..  
e0c0: 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61  ** New fields ma
e0d0: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e  y be appended in
e0e0: 20 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73   figure versions
e0f0: 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a  .  The iVersion.
e100: 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20    ** value will 
e110: 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76  increment whenev
e120: 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e  er this happens.
e130: 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a   .  */.};../*.**
e140: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73   CAPI3REF: Flags
e150: 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73   for the xAccess
e160: 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a   VFS method.**.*
e170: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
e180: 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65  constants can be
e190: 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69   used as the thi
e1a0: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  rd parameter to.
e1b0: 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ** the xAccess m
e1c0: 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c  ethod of an [sql
e1d0: 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
e1e0: 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e  .  They determin
e1f0: 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f  e.** what kind o
e200: 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68  f permissions th
e210: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
e220: 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e   is looking for.
e230: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
e240: 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74  ACCESS_EXISTS, t
e250: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
e260: 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63  d.** simply chec
e270: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
e280: 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57  ile exists..** W
e290: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
e2a0: 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65  S_READWRITE, the
e2b0: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
e2c0: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
e2d0: 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65  r the named dire
e2e0: 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65  ctory is both re
e2f0: 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61  adable and writa
e300: 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72  ble.** (in other
e310: 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73   words, if files
e320: 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72   can be added, r
e330: 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61  emoved, and rena
e340: 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68  med within.** th
e350: 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a  e directory)..**
e360: 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45   The SQLITE_ACCE
e370: 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e  SS_READWRITE con
e380: 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74  stant is current
e390: 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20  ly used only by 
e3a0: 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f  the.** [temp_sto
e3b0: 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61  re_directory pra
e3c0: 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69  gma], though thi
e3d0: 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69  s could change i
e3e0: 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65  n a future.** re
e3f0: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
e400: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
e410: 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65  ACCESS_READ, the
e420: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
e430: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
e440: 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65  r the file is re
e450: 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c  adable.  The SQL
e460: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20  ITE_ACCESS_READ 
e470: 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63  constant is.** c
e480: 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c  urrently unused,
e490: 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74   though it might
e4a0: 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 66 75   be used in a fu
e4b0: 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a  ture release of.
e4c0: 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64  ** SQLite..*/.#d
e4d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
e4e0: 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a  ESS_EXISTS    0.
e4f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
e500: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20  CCESS_READWRITE 
e510: 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50  1   /* Used by P
e520: 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65  RAGMA temp_store
e530: 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64  _directory */.#d
e540: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
e550: 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 20  ESS_READ      2 
e560: 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a    /* Unused */..
e570: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
e580: 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 53  Flags for the xS
e590: 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f  hmLock VFS metho
e5a0: 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  d.**.** These in
e5b0: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
e5c0: 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f  define the vario
e5d0: 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61  us locking opera
e5e0: 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64  tions.** allowed
e5f0: 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b   by the xShmLock
e600: 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69   method of [sqli
e610: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e  te3_io_methods].
e620: 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69    The.** followi
e630: 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20  ng are the only 
e640: 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f  legal combinatio
e650: 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74  ns of flags to t
e660: 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d  he.** xShmLock m
e670: 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  ethod:.**.** <ul
e680: 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  >.** <li>  SQLIT
e690: 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c  E_SHM_LOCK | SQL
e6a0: 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a  ITE_SHM_SHARED.*
e6b0: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
e6c0: 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  HM_LOCK | SQLITE
e6d0: 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a  _SHM_EXCLUSIVE.*
e6e0: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
e6f0: 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49  HM_UNLOCK | SQLI
e700: 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a  TE_SHM_SHARED.**
e710: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
e720: 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  M_UNLOCK | SQLIT
e730: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a  E_SHM_EXCLUSIVE.
e740: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57  ** </ul>.**.** W
e750: 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74  hen unlocking, t
e760: 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f  he same SHARED o
e770: 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67  r EXCLUSIVE flag
e780: 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 65   must be supplie
e790: 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65  d as.** was give
e7a0: 6e 20 6e 6f 20 74 68 65 20 63 6f 72 72 65 73 70  n no the corresp
e7b0: 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a  onding lock.  .*
e7c0: 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63  *.** The xShmLoc
e7d0: 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61  k method can tra
e7e0: 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  nsition between 
e7f0: 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41  unlocked and SHA
e800: 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65  RED or.** betwee
e810: 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45  n unlocked and E
e820: 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61  XCLUSIVE.  It ca
e830: 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20  nnot transition 
e840: 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a  between SHARED.*
e850: 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e  * and EXCLUSIVE.
e860: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
e870: 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20  TE_SHM_UNLOCK   
e880: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
e890: 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20  LITE_SHM_LOCK   
e8a0: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
e8b0: 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45  SQLITE_SHM_SHARE
e8c0: 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e  D       4.#defin
e8d0: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  e SQLITE_SHM_EXC
e8e0: 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a  LUSIVE    8../*.
e8f0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78  ** CAPI3REF: Max
e900: 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e  imum xShmLock in
e910: 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  dex.**.** The xS
e920: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e  hmLock method on
e930: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
e940: 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61  hods] may use va
e950: 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  lues.** between 
e960: 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 72  0 and this upper
e970: 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f   bound as its "o
e980: 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e  ffset" argument.
e990: 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
e9a0: 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61  ore will never a
e9b0: 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72  ttempt to acquir
e9c0: 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a  e or release a.*
e9d0: 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f  * lock outside o
e9e0: 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a  f this range.*/.
e9f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
ea00: 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20  HM_NLOCK        
ea10: 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  8.../*.** CAPI3R
ea20: 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54  EF: Initialize T
ea30: 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72  he SQLite Librar
ea40: 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  y.**.** ^The sql
ea50: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
ea60: 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61  ) routine initia
ea70: 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c  lizes the.** SQL
ea80: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54  ite library.  ^T
ea90: 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  he sqlite3_shutd
eaa0: 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a  own() routine.**
eab0: 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79   deallocates any
eac0: 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20   resources that 
ead0: 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62  were allocated b
eae0: 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  y sqlite3_initia
eaf0: 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65  lize()..** These
eb00: 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65   routines are de
eb10: 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e  signed to aid in
eb20: 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c   process initial
eb30: 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73  ization and.** s
eb40: 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64  hutdown on embed
eb50: 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f  ded systems.  Wo
eb60: 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63  rkstation applic
eb70: 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20  ations using.** 
eb80: 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20  SQLite normally 
eb90: 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69  do not need to i
eba0: 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20  nvoke either of 
ebb0: 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
ebc0: 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
ebd0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
ebe0: 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  ze() is an "effe
ebf0: 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
ec00: 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73  t is.** the firs
ec10: 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69  t time sqlite3_i
ec20: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
ec30: 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68  nvoked during th
ec40: 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a  e lifetime of.**
ec50: 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72   the process, or
ec60: 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69   if it is the fi
ec70: 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
ec80: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
ec90: 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c   invoked.** foll
eca0: 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20  owing a call to 
ecb0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
ecc0: 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65  ().  ^(Only an e
ecd0: 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a  ffective call.**
ece0: 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   of sqlite3_init
ecf0: 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e  ialize() does an
ed00: 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  y initialization
ed10: 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c  .  All other cal
ed20: 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65  ls.** are harmle
ed30: 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a  ss no-ops.)^.**.
ed40: 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ** A call to sql
ed50: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
ed60: 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65  is an "effective
ed70: 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20  " call if it is 
ed80: 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c  the first.** cal
ed90: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
eda0: 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68  tdown() since th
edb0: 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69  e last sqlite3_i
edc0: 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28  nitialize().  ^(
edd0: 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63  Only.** an effec
ede0: 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c  tive call to sql
edf0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
ee00: 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69  does any deiniti
ee10: 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c  alization..** Al
ee20: 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61  l other valid ca
ee30: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  lls to sqlite3_s
ee40: 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61  hutdown() are ha
ee50: 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e  rmless no-ops.)^
ee60: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
ee70: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
ee80: 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 72  interface is thr
ee90: 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c  eadsafe, but sql
eea0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
eeb0: 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20  ** is not.  The 
eec0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
eed0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73  () interface mus
eee0: 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  t only be called
eef0: 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c   from a.** singl
ef00: 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f  e thread.  All o
ef10: 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f  pen [database co
ef20: 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20  nnections] must 
ef30: 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c  be closed and al
ef40: 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74  l.** other SQLit
ef50: 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74  e resources must
ef60: 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
ef70: 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e  prior to invokin
ef80: 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75  g.** sqlite3_shu
ef90: 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41  tdown()..**.** A
efa0: 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67  mong other thing
efb0: 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74  s, ^sqlite3_init
efc0: 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e  ialize() will in
efd0: 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  voke.** sqlite3_
efe0: 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69  os_init().  Simi
eff0: 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f  larly, ^sqlite3_
f000: 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69  shutdown().** wi
f010: 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ll invoke sqlite
f020: 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a  3_os_end()..**.*
f030: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
f040: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
f050: 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ine returns [SQL
f060: 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
f070: 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73  ss..** ^If for s
f080: 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69  ome reason, sqli
f090: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f0a0: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e   is unable to in
f0b0: 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20  itialize.** the 
f0c0: 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73  library (perhaps
f0d0: 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f   it is unable to
f0e0: 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64   allocate a need
f0f0: 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68  ed resource such
f100: 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20  .** as a mutex) 
f110: 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65  it returns an [e
f120: 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72  rror code] other
f130: 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b   than [SQLITE_OK
f140: 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ]..**.** ^The sq
f150: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f160: 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  () routine is ca
f170: 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  lled internally 
f180: 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a  by many other.**
f190: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
f1a0: 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70  es so that an ap
f1b0: 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c  plication usuall
f1c0: 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  y does not need 
f1d0: 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c  to.** invoke sql
f1e0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f1f0: 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72  ) directly.  For
f200: 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74   example, [sqlit
f210: 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61  e3_open()].** ca
f220: 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  lls sqlite3_init
f230: 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20  ialize() so the 
f240: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
f250: 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63  ill be automatic
f260: 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69  ally.** initiali
f270: 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  zed when [sqlite
f280: 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c  3_open()] is cal
f290: 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f  led if it has no
f2a0: 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64  t be initialized
f2b0: 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48  .** already.  ^H
f2c0: 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74  owever, if SQLit
f2d0: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
f2e0: 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  th the [SQLITE_O
f2f0: 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a  MIT_AUTOINIT].**
f300: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
f310: 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61  tion, then the a
f320: 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74  utomatic calls t
f330: 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
f340: 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d  lize().** are om
f350: 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70  itted and the ap
f360: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63  plication must c
f370: 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  all sqlite3_init
f380: 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c  ialize() directl
f390: 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73  y.** prior to us
f3a0: 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
f3b0: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
f3c0: 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72   For maximum por
f3d0: 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20  tability,.** it 
f3e0: 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
f3f0: 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  hat applications
f400: 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73   always invoke s
f410: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f420: 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20  e().** directly 
f430: 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61  prior to using a
f440: 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ny other SQLite 
f450: 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75  interface.  Futu
f460: 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f  re releases.** o
f470: 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71  f SQLite may req
f480: 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f  uire this.  In o
f490: 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
f4a0: 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74  behavior exhibit
f4b0: 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74  ed.** when SQLit
f4c0: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
f4d0: 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  th [SQLITE_OMIT_
f4e0: 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20  AUTOINIT] might 
f4f0: 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65  become the.** de
f500: 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69  fault behavior i
f510: 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65  n some future re
f520: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
f530: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
f540: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75  e3_os_init() rou
f550: 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74  tine does operat
f560: 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
f570: 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a  fic.** initializ
f580: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c  ation of the SQL
f590: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68  ite library.  Th
f5a0: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  e sqlite3_os_end
f5b0: 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e  ().** routine un
f5c0: 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20  does the effect 
f5d0: 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
f5e0: 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74  it().  Typical t
f5f0: 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65  asks.** performe
f600: 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69  d by these routi
f610: 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f  nes include allo
f620: 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f  cation or deallo
f630: 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61  cation.** of sta
f640: 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69  tic resources, i
f650: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66  nitialization of
f660: 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65   global variable
f670: 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70  s,.** setting up
f680: 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69   a default [sqli
f690: 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c  te3_vfs] module,
f6a0: 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a   or setting up.*
f6b0: 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  * a default conf
f6c0: 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20  iguration using 
f6d0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
f6e0: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  )]..**.** The ap
f6f0: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
f700: 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69   never invoke ei
f710: 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ther sqlite3_os_
f720: 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  init().** or sql
f730: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69  ite3_os_end() di
f740: 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70  rectly.  The app
f750: 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
f760: 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  only invoke.** s
f770: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f780: 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
f790: 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65  shutdown().  The
f7a0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
f7b0: 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
f7c0: 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61  is called automa
f7d0: 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74  tically by sqlit
f7e0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
f7f0: 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  and.** sqlite3_o
f800: 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65  s_end() is calle
f810: 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75  d by sqlite3_shu
f820: 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70  tdown().  Approp
f830: 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  riate.** impleme
f840: 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c  ntations for sql
f850: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
f860: 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
f870: 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74  d().** are built
f880: 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65   into SQLite whe
f890: 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64  n it is compiled
f8a0: 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f   for Unix, Windo
f8b0: 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20  ws, or OS/2..** 
f8c0: 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69  When [custom bui
f8d0: 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20  lds | built for 
f8e0: 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d  other platforms]
f8f0: 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b  .** (using the [
f900: 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d  SQLITE_OS_OTHER=
f910: 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a  1] compile-time.
f920: 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61  ** option) the a
f930: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
f940: 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c  supply a suitabl
f950: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
f960: 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
f970: 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71  os_init() and sq
f980: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20  lite3_os_end(). 
f990: 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   An application-
f9a0: 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c  supplied.** impl
f9b0: 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71  ementation of sq
f9c0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
f9d0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  or sqlite3_os_en
f9e0: 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75  d().** must retu
f9f0: 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  rn [SQLITE_OK] o
fa00: 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f  n success and so
fa10: 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20  me other [error 
fa20: 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61  code] upon.** fa
fa30: 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ilure..*/.int sq
fa40: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
fa50: 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69  (void);.int sqli
fa60: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69  te3_shutdown(voi
fa70: 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
fa80: 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69  os_init(void);.i
fa90: 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nt sqlite3_os_en
faa0: 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20  d(void);../*.** 
fab0: 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
fac0: 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65  uring The SQLite
fad0: 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54   Library.**.** T
fae0: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  he sqlite3_confi
faf0: 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
fb00: 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c   used to make gl
fb10: 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69  obal configurati
fb20: 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
fb30: 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72   SQLite in order
fb40: 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20   to tune SQLite 
fb50: 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20  to the specific 
fb60: 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20  needs of.** the 
fb70: 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68  application.  Th
fb80: 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  e default config
fb90: 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d  uration is recom
fba0: 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a  mended for most.
fbb0: 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** applications 
fbc0: 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74  and so this rout
fbd0: 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e  ine is usually n
fbe0: 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49  ot necessary.  I
fbf0: 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64  t is.** provided
fc00: 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65   to support rare
fc10: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69   applications wi
fc20: 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73  th unusual needs
fc30: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
fc40: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  te3_config() int
fc50: 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68  erface is not th
fc60: 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 20 61  readsafe.  The a
fc70: 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75  pplication.** mu
fc80: 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e  st insure that n
fc90: 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  o other SQLite i
fca0: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e  nterfaces are in
fcb0: 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a  voked by other.*
fcc0: 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20  * threads while 
fcd0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
fce0: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75   is running.  Fu
fcf0: 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74  rthermore, sqlit
fd00: 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d  e3_config().** m
fd10: 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b  ay only be invok
fd20: 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72  ed prior to libr
fd30: 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ary initializati
fd40: 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  on using.** [sql
fd50: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
fd60: 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74  )] or after shut
fd70: 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33  down by [sqlite3
fd80: 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a  _shutdown()]..**
fd90: 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e   ^If sqlite3_con
fda0: 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20  fig() is called 
fdb0: 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69  after [sqlite3_i
fdc0: 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64  nitialize()] and
fdd0: 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69   before.** [sqli
fde0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
fdf0: 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74  then it will ret
fe00: 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  urn SQLITE_MISUS
fe10: 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65  E..** Note, howe
fe20: 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74  ver, that ^sqlit
fe30: 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20  e3_config() can 
fe40: 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72  be called as par
fe50: 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c  t of the.** impl
fe60: 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e  ementation of an
fe70: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
fe80: 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73  ined [sqlite3_os
fe90: 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _init()]..**.** 
fea0: 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
feb0: 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  nt to sqlite3_co
fec0: 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74  nfig() is an int
fed0: 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75  eger.** [configu
fee0: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74  ration option] t
fef0: 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a  hat determines.*
ff00: 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74 79 20  * what property 
ff10: 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20  of SQLite is to 
ff20: 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20  be configured.  
ff30: 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d  Subsequent argum
ff40: 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70  ents.** vary dep
ff50: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63  ending on the [c
ff60: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
ff70: 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ion].** in the f
ff80: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
ff90: 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e  *.** ^When a con
ffa0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
ffb0: 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65  n is set, sqlite
ffc0: 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72  3_config() retur
ffd0: 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  ns [SQLITE_OK]..
ffe0: 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f  ** ^If the optio
fff0: 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20  n is unknown or 
10000 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
10010 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69   to set the opti
10020 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20  on.** then this 
10030 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
10040 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  a non-zero [erro
10050 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20  r code]..*/.int 
10060 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69  sqlite3_config(i
10070 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  nt, ...);../*.**
10080 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
10090 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f  gure database co
100a0 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  nnections.**.** 
100b0 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  The sqlite3_db_c
100c0 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
100d0 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b  e is used to mak
100e0 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a  e configuration.
100f0 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20  ** changes to a 
10100 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
10110 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65  tion].  The inte
10120 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72  rface is similar
10130 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
10140 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74  config()] except
10150 20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65   that the change
10160 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e  s apply to a sin
10170 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  gle.** [database
10180 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70   connection] (sp
10190 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66  ecified in the f
101a0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a  irst argument)..
101b0 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
101c0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
101d0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44  ite3_db_config(D
101e0 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a  ,V,...)  is the.
101f0 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ** [SQLITE_DBCON
10200 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20  FIG_LOOKASIDE | 
10210 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65  configuration ve
10220 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72  rb] - an integer
10230 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69   code .** that i
10240 6e 64 69 63 61 74 65 73 20 77 68 61 74 20 61 73  ndicates what as
10250 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74  pect of the [dat
10260 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
10270 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69  ] is being confi
10280 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71  gured..** Subseq
10290 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76  uent arguments v
102a0 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ary depending on
102b0 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
102c0 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e  on verb..**.** ^
102d0 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
102e0 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74  _db_config() ret
102f0 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66  urn SQLITE_OK if
10300 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
10310 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73  the call is cons
10320 69 64 65 72 65 64 20 73 75 63 63 65 73 73 66 75  idered successfu
10330 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
10340 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69  3_db_config(sqli
10350 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e  te3*, int op, ..
10360 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
10370 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
10380 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a  cation Routines.
10390 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
103a0 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
103b0 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74   defines the int
103c0 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53  erface between S
103d0 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77  QLite.** and low
103e0 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c  -level memory al
103f0 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
10400 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62  s..**.** This ob
10410 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20  ject is used in 
10420 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69  only one place i
10430 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74  n the SQLite int
10440 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69  erface..** A poi
10450 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
10460 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
10470 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65  ct is the argume
10480 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  nt to.** [sqlite
10490 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e  3_config()] when
104a0 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
104b0 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20  on option is.** 
104c0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
104d0 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54  ALLOC] or [SQLIT
104e0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
104f0 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65  OC].  .** By cre
10500 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63  ating an instanc
10510 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
10520 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20  .** and passing 
10530 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
10540 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43  onfig]([SQLITE_C
10550 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a  ONFIG_MALLOC]).*
10560 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75  * during configu
10570 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69  ration, an appli
10580 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69  cation can speci
10590 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76  fy an alternativ
105a0 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  e.** memory allo
105b0 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d  cation subsystem
105c0 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75   for SQLite to u
105d0 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  se for all of it
105e0 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d  s.** dynamic mem
105f0 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a  ory needs..**.**
10600 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74   Note that SQLit
10610 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76  e comes with sev
10620 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d  eral [built-in m
10630 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73  emory allocators
10640 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65  ].** that are pe
10650 72 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65  rfectly adequate
10660 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65   for the overwhe
10670 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f  lming majority o
10680 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  f applications.*
10690 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20  * and that this 
106a0 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75  object is only u
106b0 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20  seful to a tiny 
106c0 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c  minority of appl
106d0 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68  ications.** with
106e0 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d   specialized mem
106f0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
10700 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68  equirements.  Th
10710 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20  is object is.** 
10720 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67  also used during
10730 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69   testing of SQLi
10740 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73  te in order to s
10750 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e  pecify an altern
10760 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ative.** memory 
10770 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73  allocator that s
10780 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20  imulates memory 
10790 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f  out-of-memory co
107a0 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f  nditions in.** o
107b0 72 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74  rder to verify t
107c0 68 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76  hat SQLite recov
107d0 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66  ers gracefully f
107e0 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64  rom such.** cond
107f0 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  itions..**.** Th
10800 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c  e xMalloc, xReal
10810 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d  loc, and xFree m
10820 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b  ethods must work
10830 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c   like the.** mal
10840 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29  loc(), realloc()
10850 20 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63   and free() func
10860 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73  tions from the s
10870 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
10880 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75  y..** ^SQLite gu
10890 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
108a0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
108b0 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63  t to.** xRealloc
108c0 20 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c   is always a val
108d0 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 61  ue returned by a
108e0 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78   prior call to x
108f0 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78  Roundup..**.** x
10900 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75  Size should retu
10910 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  rn the allocated
10920 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72   size of a memor
10930 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
10940 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69  previously obtai
10950 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63  ned from xMalloc
10960 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54   or xRealloc.  T
10970 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
10980 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61  e.** is always a
10990 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61  t least as big a
109a0 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20  s the requested 
109b0 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20  size but may be 
109c0 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  larger..**.** Th
109d0 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f  e xRoundup metho
109e0 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77  d returns what w
109f0 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f  ould be the allo
10a00 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a  cated size of.**
10a10 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
10a20 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72  tion given a par
10a30 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65  ticular requeste
10a40 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65  d size.  Most me
10a50 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
10a60 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f  rs round up memo
10a70 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61  ry allocations a
10a80 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e  t least to the n
10a90 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20  ext multiple.** 
10aa0 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f  of 8.  Some allo
10ab0 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
10ac0 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74  to a larger mult
10ad0 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77  iple or to a pow
10ae0 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72  er of 2..** Ever
10af0 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  y memory allocat
10b00 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69  ion request comi
10b10 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73  ng in through [s
10b20 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
10b30 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
10b40 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74  realloc()] first
10b50 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e   calls xRoundup.
10b60 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65    If xRoundup re
10b70 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61  turns 0, .** tha
10b80 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72  t causes the cor
10b90 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72  responding memor
10ba0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
10bb0 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fail..**.** The 
10bc0 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69  xInit method ini
10bd0 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d  tializes the mem
10be0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20  ory allocator.  
10bf0 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20  For example,.** 
10c00 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74  it might allocat
10c10 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75  e any require mu
10c20 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c  texes or initial
10c30 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  ize internal dat
10c40 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e  a.** structures.
10c50 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20    The xShutdown 
10c60 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65  method is invoke
10c70 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62  d (indirectly) b
10c80 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68  y.** [sqlite3_sh
10c90 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68  utdown()] and sh
10ca0 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20  ould deallocate 
10cb0 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 63  any resources ac
10cc0 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e  quired.** by xIn
10cd0 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 74  it.  The pAppDat
10ce0 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65  a pointer is use
10cf0 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61  d as the only pa
10d00 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49  rameter to.** xI
10d10 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77  nit and xShutdow
10d20 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  n..**.** SQLite 
10d30 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54  holds the [SQLIT
10d40 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
10d50 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65  ASTER] mutex whe
10d60 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20  n it invokes.** 
10d70 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  the xInit method
10d80 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d  , so the xInit m
10d90 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62  ethod need not b
10da0 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54  e threadsafe.  T
10db0 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20  he.** xShutdown 
10dc0 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63  method is only c
10dd0 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  alled from [sqli
10de0 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
10df0 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f  so it does.** no
10e00 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72  t need to be thr
10e10 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e 20  eadsafe either. 
10e20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d   For all other m
10e30 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a  ethods, SQLite.*
10e40 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c  * holds the [SQL
10e50 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
10e60 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c  _MEM] mutex as l
10e70 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53  ong as the.** [S
10e80 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
10e90 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72  STATUS] configur
10ea0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20  ation option is 
10eb0 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68  turned on (which
10ec0 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65 66  .** it is by def
10ed0 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65  ault) and so the
10ee0 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75 74   methods are aut
10ef0 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61  omatically seria
10f00 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65  lized..** Howeve
10f10 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f  r, if [SQLITE_CO
10f20 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20  NFIG_MEMSTATUS] 
10f30 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65  is disabled, the
10f40 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d  n the other.** m
10f50 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74  ethods must be t
10f60 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73  hreadsafe or els
10f70 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e  e make their own
10f80 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f   arrangements fo
10f90 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69  r.** serializati
10fa0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  on..**.** SQLite
10fb0 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f   will never invo
10fc0 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20  ke xInit() more 
10fd0 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75  than once withou
10fe0 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67  t an intervening
10ff0 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75  .** call to xShu
11000 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65  tdown()..*/.type
11010 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
11020 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73  e3_mem_methods s
11030 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
11040 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  ds;.struct sqlit
11050 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b  e3_mem_methods {
11060 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c  .  void *(*xMall
11070 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20  oc)(int);       
11080 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f    /* Memory allo
11090 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20  cation function 
110a0 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65  */.  void (*xFre
110b0 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  e)(void*);      
110c0 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72      /* Free a pr
110d0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a  ior allocation *
110e0 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61  /.  void *(*xRea
110f0 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29  lloc)(void*,int)
11100 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20  ;  /* Resize an 
11110 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
11120 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69  int (*xSize)(voi
11130 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f  d*);           /
11140 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a  * Return the siz
11150 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69  e of an allocati
11160 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52  on */.  int (*xR
11170 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20  oundup)(int);   
11180 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20         /* Round 
11190 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 20  up request size 
111a0 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  to allocation si
111b0 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49  ze */.  int (*xI
111c0 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  nit)(void*);    
111d0 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61         /* Initia
111e0 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  lize the memory 
111f0 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76  allocator */.  v
11200 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29  oid (*xShutdown)
11210 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a  (void*);      /*
11220 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68   Deinitialize th
11230 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
11240 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41  or */.  void *pA
11250 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20  ppData;         
11260 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65         /* Argume
11270 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e  nt to xInit() an
11280 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f  d xShutdown() */
11290 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
112a0 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69  REF: Configurati
112b0 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45  on Options.** KE
112c0 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75  YWORDS: {configu
112d0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a  ration option}.*
112e0 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
112f0 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61  ants are the ava
11300 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63  ilable integer c
11310 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
11320 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e  ions that.** can
11330 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
11340 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
11350 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
11360 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
11370 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  face..**.** New 
11380 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
11390 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
113a0 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
113b0 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
113c0 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e  .** Existing con
113d0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
113e0 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63  ns might be disc
113f0 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69  ontinued.  Appli
11400 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
11410 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  d check the retu
11420 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71  rn code from [sq
11430 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
11440 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
11450 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f  t.** the call wo
11460 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69  rked.  The [sqli
11470 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
11480 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74  terface will ret
11490 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72  urn a.** non-zer
114a0 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  o [error code] i
114b0 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64  f a discontinued
114c0 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20   or unsupported 
114d0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
114e0 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b  tion.** is invok
114f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  ed..**.** <dl>.*
11500 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
11510 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d  G_SINGLETHREAD]]
11520 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
11530 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c  IG_SINGLETHREAD<
11540 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
11550 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
11560 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
11570 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  n.  ^This option
11580 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68   sets the.** [th
11590 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
115a0 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20   Single-thread. 
115b0 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
115c0 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20   it disables.** 
115d0 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64  all mutexing and
115e0 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74   puts SQLite int
115f0 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69  o a mode where i
11600 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73  t can only be us
11610 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c  ed.** by a singl
11620 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20  e thread.   ^If 
11630 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
11640 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
11650 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
11660 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
11670 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
11680 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
11690 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
116a0 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67  ossible to chang
116b0 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67  e the [threading
116c0 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20   mode] from its 
116d0 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65  default.** value
116e0 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61   of Single-threa
116f0 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65  d and so [sqlite
11700 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
11710 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c   return .** [SQL
11720 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61  ITE_ERROR] if ca
11730 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51  lled with the SQ
11740 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
11750 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66  LETHREAD.** conf
11760 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
11770 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
11780 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
11790 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53  TITHREAD]] <dt>S
117a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
117b0 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  TITHREAD</dt>.**
117c0 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
117d0 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
117e0 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
117f0 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
11800 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
11810 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d   mode] to Multi-
11820 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65  thread.  In othe
11830 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61  r words, it disa
11840 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67  bles.** mutexing
11850 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
11860 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70  nnection] and [p
11870 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
11880 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54  t] objects..** T
11890 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  he application i
118a0 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
118b0 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63  r serializing ac
118c0 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61  cess to.** [data
118d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
118e0 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
118f0 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75  statements].  Bu
11900 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a  t other mutexes.
11910 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73  ** are enabled s
11920 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  o that SQLite wi
11930 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73  ll be safe to us
11940 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72  e in a multi-thr
11950 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e  eaded.** environ
11960 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20  ment as long as 
11970 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61  no two threads a
11980 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68  ttempt to use th
11990 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62  e same.** [datab
119a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
119b0 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
119c0 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  .  ^If SQLite is
119d0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
119e0 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
119f0 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
11a00 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
11a10 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
11a20 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69  ion then.** it i
11a30 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
11a40 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d  o set the Multi-
11a50 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e  thread [threadin
11a60 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b  g mode] and.** [
11a70 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
11a80 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  ] will return [S
11a90 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
11aa0 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a  called with the.
11ab0 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ** SQLITE_CONFIG
11ac0 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e  _MULTITHREAD con
11ad0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
11ae0 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  n.</dd>.**.** [[
11af0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
11b00 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53  RIALIZED]] <dt>S
11b10 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
11b20 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20  IALIZED</dt>.** 
11b30 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
11b40 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
11b50 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69  is option.  ^Thi
11b60 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
11b70 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20  e.** [threading 
11b80 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69  mode] to Seriali
11b90 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f  zed. In other wo
11ba0 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e  rds, this option
11bb0 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20   enables.** all 
11bc0 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e  mutexes includin
11bd0 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a  g the recursive.
11be0 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64  ** mutexes on [d
11bf0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
11c00 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  on] and [prepare
11c10 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a  d statement] obj
11c20 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73  ects..** In this
11c30 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20   mode (which is 
11c40 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e  the default when
11c50 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
11c60 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c  led with.** [SQL
11c70 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31  ITE_THREADSAFE=1
11c80 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  ]) the SQLite li
11c90 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c  brary will itsel
11ca0 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65  f serialize acce
11cb0 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61  ss.** to [databa
11cc0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
11cd0 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
11ce0 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61  atements] so tha
11cf0 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61  t the.** applica
11d00 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20  tion is free to 
11d10 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61  use the same [da
11d20 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11d30 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d  n] or the.** sam
11d40 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
11d50 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72  ement] in differ
11d60 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74  ent threads at t
11d70 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a  he same time..**
11d80 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
11d90 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
11da0 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
11db0 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
11dc0 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
11dd0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
11de0 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20  n then.** it is 
11df0 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
11e00 73 65 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a  set the Serializ
11e10 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
11e20 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  de] and.** [sqli
11e30 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
11e40 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
11e50 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
11e60 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53  ed with the.** S
11e70 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
11e80 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72  IALIZED configur
11e90 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
11ea0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
11eb0 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
11ec0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
11ed0 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a  FIG_MALLOC</dt>.
11ee0 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
11ef0 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
11f00 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
11f10 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
11f20 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e   to an.** instan
11f30 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
11f40 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
11f50 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20  structure.  The 
11f60 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69  argument specifi
11f70 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76  es.** alternativ
11f80 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f  e low-level memo
11f90 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
11fa0 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65  utines to be use
11fb0 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a  d in place of.**
11fc0 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
11fd0 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20  cation routines 
11fe0 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
11ff0 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b  e.)^ ^SQLite mak
12000 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72  es.** its own pr
12010 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
12020 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
12030 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
12040 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
12050 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b  .** before the [
12060 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
12070 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c  ] call returns.<
12080 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
12090 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
120a0 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  LLOC]] <dt>SQLIT
120b0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
120c0 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OC</dt>.** <dd> 
120d0 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
120e0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
120f0 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
12100 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
12110 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  * instance of th
12120 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
12130 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
12140 65 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  e.  The [sqlite3
12150 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  _mem_methods].**
12160 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69   structure is fi
12170 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75  lled with the cu
12180 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20  rrently defined 
12190 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
121a0 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a  n routines.)^.**
121b0 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
121c0 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
121d0 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
121e0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
121f0 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77  on.** routines w
12200 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68  ith a wrapper th
12210 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d  at simulations m
12220 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12230 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74   failure or.** t
12240 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61  racks memory usa
12250 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e  ge, for example.
12260 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
12270 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
12280 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c  STATUS]] <dt>SQL
12290 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
122a0 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATUS</dt>.** <dd
122b0 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  > ^This option t
122c0 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75  akes single argu
122d0 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74  ment of type int
122e0 2c 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  , interpreted as
122f0 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20   a .** boolean, 
12300 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72  which enables or
12310 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f   disables the co
12320 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f  llection of memo
12330 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a  ry allocation .*
12340 2a 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28  * statistics. ^(
12350 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  When memory allo
12360 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
12370 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 2c 20  s are disabled, 
12380 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  the .** followin
12390 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  g SQLite interfa
123a0 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f  ces become non-o
123b0 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20  perational:.**  
123c0 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20   <ul>.**   <li> 
123d0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
123e0 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  used()].**   <li
123f0 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  > [sqlite3_memor
12400 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a  y_highwater()].*
12410 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
12420 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
12430 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  t64()].**   <li>
12440 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73   [sqlite3_status
12450 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e  ()].**   </ul>)^
12460 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f  .** ^Memory allo
12470 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
12480 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79  s are enabled by
12490 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20   default unless 
124a0 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d  SQLite is.** com
124b0 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49  piled with [SQLI
124c0 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54  TE_DEFAULT_MEMST
124d0 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68  ATUS]=0 in which
124e0 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20   case memory.** 
124f0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
12500 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c  stics are disabl
12510 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ed by default..*
12520 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  * </dd>.**.** [[
12530 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
12540 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49  RATCH]] <dt>SQLI
12550 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
12560 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  H</dt>.** <dd> ^
12570 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63  This option spec
12580 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d  ifies a static m
12590 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61  emory buffer tha
125a0 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65  t SQLite can use
125b0 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68 20   for.** scratch 
125c0 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 20 61  memory.  There a
125d0 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  re three argumen
125e0 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 61  ts:  A pointer a
125f0 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67  n 8-byte.** alig
12600 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  ned memory buffe
12610 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65  r from which the
12620 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
12630 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20  ions will be.** 
12640 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65 20  drawn, the size 
12650 6f 66 20 65 61 63 68 20 73 63 72 61 74 63 68 20  of each scratch 
12660 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c  allocation (sz),
12670 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78 69  .** and the maxi
12680 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73 63  mum number of sc
12690 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e  ratch allocation
126a0 73 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a  s (N).  The sz.*
126b0 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20  * argument must 
126c0 62 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66  be a multiple of
126d0 20 31 36 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73   16..** The firs
126e0 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20  t argument must 
126f0 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
12700 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  an 8-byte aligne
12710 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61  d buffer.** of a
12720 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74  t least sz*N byt
12730 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  es of memory..**
12740 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73   ^SQLite will us
12750 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20 74  e no more than t
12760 77 6f 20 73 63 72 61 74 63 68 20 62 75 66 66 65  wo scratch buffe
12770 72 73 20 70 65 72 20 74 68 72 65 61 64 2e 20 20  rs per thread.  
12780 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20 62  So.** N should b
12790 65 20 73 65 74 20 74 6f 20 74 77 69 63 65 20 74  e set to twice t
127a0 68 65 20 65 78 70 65 63 74 65 64 20 6d 61 78 69  he expected maxi
127b0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 68  mum number of th
127c0 72 65 61 64 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74  reads..** ^SQLit
127d0 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 65 71  e will never req
127e0 75 69 72 65 20 61 20 73 63 72 61 74 63 68 20 62  uire a scratch b
127f0 75 66 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f  uffer that is mo
12800 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d  re than 6.** tim
12810 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
12820 70 61 67 65 20 73 69 7a 65 2e 20 5e 49 66 20 53  page size. ^If S
12830 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65 64  QLite needs need
12840 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  s additional.** 
12850 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 62  scratch memory b
12860 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72  eyond what is pr
12870 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20 63  ovided by this c
12880 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
12890 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73  ion, then .** [s
128a0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
128b0 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74 6f   will be used to
128c0 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f   obtain the memo
128d0 72 79 20 6e 65 65 64 65 64 2e 3c 2f 64 64 3e 0a  ry needed.</dd>.
128e0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
128f0 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d  ONFIG_PAGECACHE]
12900 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
12910 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64  FIG_PAGECACHE</d
12920 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
12930 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
12940 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
12950 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51  y buffer that SQ
12960 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72  Lite can use for
12970 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
12980 20 70 61 67 65 20 63 61 63 68 65 20 77 69 74 68   page cache with
12990 20 74 68 65 20 64 65 66 61 75 6c 74 20 70 61 67   the default pag
129a0 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
129b0 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69  tation.  .** Thi
129c0 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
129d0 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73  should not be us
129e0 65 64 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61  ed if an applica
129f0 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65  tion-define page
12a00 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  .** cache implem
12a10 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64  entation is load
12a20 65 64 20 75 73 69 6e 67 20 74 68 65 20 53 51 4c  ed using the SQL
12a30 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
12a40 45 32 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68  E2 option..** Th
12a50 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
12a60 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
12a70 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e 74 65  option: A pointe
12a80 72 20 74 6f 20 38 2d 62 79 74 65 20 61 6c 69 67  r to 8-byte alig
12a90 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74  ned.** memory, t
12aa0 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  he size of each 
12ab0 70 61 67 65 20 62 75 66 66 65 72 20 28 73 7a 29  page buffer (sz)
12ac0 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72  , and the number
12ad0 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a   of pages (N)..*
12ae0 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e  * The sz argumen
12af0 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20  t should be the 
12b00 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67  size of the larg
12b10 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67  est database pag
12b20 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66  e.** (a power of
12b30 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32   two between 512
12b40 20 61 6e 64 20 33 32 37 36 38 29 20 70 6c 75 73   and 32768) plus
12b50 20 61 20 6c 69 74 74 6c 65 20 65 78 74 72 61 20   a little extra 
12b60 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65  for each.** page
12b70 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20 70   header.  ^The p
12b80 61 67 65 20 68 65 61 64 65 72 20 73 69 7a 65 20  age header size 
12b90 69 73 20 32 30 20 74 6f 20 34 30 20 62 79 74 65  is 20 to 40 byte
12ba0 73 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a  s depending on.*
12bb0 2a 20 74 68 65 20 68 6f 73 74 20 61 72 63 68 69  * the host archi
12bc0 74 65 63 74 75 72 65 2e 20 20 5e 49 74 20 69 73  tecture.  ^It is
12bd0 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74   harmless, apart
12be0 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64   from the wasted
12bf0 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d   memory,.** to m
12c00 61 6b 65 20 73 7a 20 61 20 6c 69 74 74 6c 65 20  ake sz a little 
12c10 74 6f 6f 20 6c 61 72 67 65 2e 20 20 54 68 65 20  too large.  The 
12c20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e  first.** argumen
12c30 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74  t should point t
12c40 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  o an allocation 
12c50 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e  of at least sz*N
12c60 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
12c70 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  ..** ^SQLite wil
12c80 6c 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  l use the memory
12c90 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65   provided by the
12ca0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
12cb0 74 6f 20 73 61 74 69 73 66 79 20 69 74 73 0a 2a  to satisfy its.*
12cc0 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20 66  * memory needs f
12cd0 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 70  or the first N p
12ce0 61 67 65 73 20 74 68 61 74 20 69 74 20 61 64 64  ages that it add
12cf0 73 20 74 6f 20 63 61 63 68 65 2e 20 20 5e 49 66  s to cache.  ^If
12d00 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70   additional.** p
12d10 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79  age cache memory
12d20 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e   is needed beyon
12d30 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64  d what is provid
12d40 65 64 20 62 79 20 74 68 69 73 20 6f 70 74 69 6f  ed by this optio
12d50 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74  n, then.** SQLit
12d60 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74  e goes to [sqlit
12d70 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72  e3_malloc()] for
12d80 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61 6c 20   the additional 
12d90 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e 0a 2a  storage space..*
12da0 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 69 6e  * The pointer in
12db0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
12dc0 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20 61  ent must.** be a
12dd0 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62  ligned to an 8-b
12de0 79 74 65 20 62 6f 75 6e 64 61 72 79 20 6f 72 20  yte boundary or 
12df0 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76  subsequent behav
12e00 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a  ior of SQLite.**
12e10 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e   will be undefin
12e20 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ed.</dd>.**.** [
12e30 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48  [SQLITE_CONFIG_H
12e40 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  EAP]] <dt>SQLITE
12e50 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74  _CONFIG_HEAP</dt
12e60 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
12e70 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
12e80 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79   a static memory
12e90 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c   buffer that SQL
12ea0 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20  ite will use.** 
12eb0 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64  for all of its d
12ec0 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c  ynamic memory al
12ed0 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 20 62  location needs b
12ee0 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76  eyond those prov
12ef0 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20 5b  ided.** for by [
12f00 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
12f10 52 41 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c 49  RATCH] and [SQLI
12f20 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
12f30 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 61  CHE]..** There a
12f40 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  re three argumen
12f50 74 73 3a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c  ts: An 8-byte al
12f60 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f  igned pointer to
12f70 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20   the memory,.** 
12f80 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
12f90 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72  tes in the memor
12fa0 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68  y buffer, and th
12fb0 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61  e minimum alloca
12fc0 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49  tion size..** ^I
12fd0 66 20 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e  f the first poin
12fe0 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20  ter (the memory 
12ff0 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c  pointer) is NULL
13000 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65  , then SQLite re
13010 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e  verts.** to usin
13020 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65  g its default me
13030 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28  mory allocator (
13040 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f  the system mallo
13050 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  c() implementati
13060 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20  on),.** undoing 
13070 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61  any prior invoca
13080 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f  tion of [SQLITE_
13090 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20  CONFIG_MALLOC]. 
130a0 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f   ^If the.** memo
130b0 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  ry pointer is no
130c0 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68 65  t NULL and eithe
130d0 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  r [SQLITE_ENABLE
130e0 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a 20  _MEMSYS3] or.** 
130f0 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d  [SQLITE_ENABLE_M
13100 45 4d 53 59 53 35 5d 20 61 72 65 20 64 65 66 69  EMSYS5] are defi
13110 6e 65 64 2c 20 74 68 65 6e 20 74 68 65 20 61 6c  ned, then the al
13120 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79  ternative memory
13130 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73  .** allocator is
13140 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64   engaged to hand
13150 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65  le all of SQLite
13160 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
13170 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68  ion needs..** Th
13180 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20  e first pointer 
13190 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  (the memory poin
131a0 74 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69  ter) must be ali
131b0 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74  gned to an 8-byt
131c0 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72  e.** boundary or
131d0 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61   subsequent beha
131e0 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77  vior of SQLite w
131f0 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64  ill be undefined
13200 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d  ..** The minimum
13210 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
13220 20 69 73 20 63 61 70 70 65 64 20 61 74 20 32 2a   is capped at 2*
13230 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20  *12. Reasonable 
13240 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68  values.** for th
13250 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61  e minimum alloca
13260 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 20 32 2a  tion size are 2*
13270 2a 35 20 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e  *5 through 2**8.
13280 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
13290 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
132a0 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  X]] <dt>SQLITE_C
132b0 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e  ONFIG_MUTEX</dt>
132c0 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
132d0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
132e0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
132f0 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
13300 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
13310 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
13320 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
13330 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
13340 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63  he argument spec
13350 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61  ifies.** alterna
13360 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d  tive low-level m
13370 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f  utex routines to
13380 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63   be used in plac
13390 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 20 72  e.** the mutex r
133a0 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e  outines built in
133b0 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53  to SQLite.)^  ^S
133c0 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f  QLite makes a co
133d0 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6e  py of the.** con
133e0 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c  tent of the [sql
133f0 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
13400 64 73 5d 20 73 74 72 75 63 74 75 72 65 20 62 65  ds] structure be
13410 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f  fore the call to
13420 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
13430 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20  fig()] returns. 
13440 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
13450 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
13460 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
13470 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
13480 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
13490 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
134a0 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74   then.** the ent
134b0 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62  ire mutexing sub
134c0 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65  system is omitte
134d0 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64  d from the build
134e0 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73   and hence calls
134f0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
13500 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74  config()] with t
13510 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
13520 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61  _MUTEX configura
13530 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c  tion option will
13540 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
13550 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a  TE_ERROR].</dd>.
13560 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
13570 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 5d  ONFIG_GETMUTEX]]
13580 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
13590 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e  IG_GETMUTEX</dt>
135a0 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
135b0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
135c0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
135d0 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
135e0 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
135f0 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
13600 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
13610 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
13620 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  he.** [sqlite3_m
13630 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  utex_methods].**
13640 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69   structure is fi
13650 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75  lled with the cu
13660 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20  rrently defined 
13670 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29  mutex routines.)
13680 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e  ^.** This option
13690 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
136a0 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66  overload the def
136b0 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63  ault mutex alloc
136c0 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65  ation.** routine
136d0 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72  s with a wrapper
136e0 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d   used to track m
136f0 75 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 70  utex usage for p
13700 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72  erformance.** pr
13710 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69  ofiling or testi
13720 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e  ng, for example.
13730 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73     ^If SQLite is
13740 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
13750 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
13760 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
13770 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
13780 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
13790 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ion then.** the 
137a0 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20  entire mutexing 
137b0 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69  subsystem is omi
137c0 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75  tted from the bu
137d0 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61  ild and hence ca
137e0 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
137f0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74  e3_config()] wit
13800 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  h the SQLITE_CON
13810 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e  FIG_GETMUTEX con
13820 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
13830 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e  n will.** return
13840 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e   [SQLITE_ERROR].
13850 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
13860 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
13870 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49  ASIDE]] <dt>SQLI
13880 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
13890 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  IDE</dt>.** <dd>
138a0 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
138b0 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e  akes two argumen
138c0 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  ts that determin
138d0 65 20 74 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a  e the default.**
138e0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
138f0 6f 6e 20 66 6f 72 20 74 68 65 20 6c 6f 6f 6b 61  on for the looka
13900 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  side memory allo
13910 63 61 74 6f 72 20 6f 6e 20 65 61 63 68 0a 2a 2a  cator on each.**
13920 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
13930 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 66 69 72  ction].  The fir
13940 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  st argument is t
13950 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61  he.** size of ea
13960 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ch lookaside buf
13970 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65  fer slot and the
13980 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e   second is the n
13990 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74  umber of.** slot
139a0 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65  s allocated to e
139b0 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
139c0 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 54 68  nection.)^  ^(Th
139d0 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
139e0 68 65 0a 2a 2a 20 3c 69 3e 64 65 66 61 75 6c 74  he.** <i>default
139f0 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73  </i> lookaside s
13a00 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54 45  ize. The [SQLITE
13a10 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
13a20 49 44 45 5d 0a 2a 2a 20 76 65 72 62 20 74 6f 20  IDE].** verb to 
13a30 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
13a40 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65  ig()] can be use
13a50 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  d to change the 
13a60 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e  lookaside.** con
13a70 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e  figuration on in
13a80 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74  dividual connect
13a90 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a  ions.)^ </dd>.**
13aa0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
13ab0 46 49 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64  FIG_PCACHE2]] <d
13ac0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
13ad0 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20  PCACHE2</dt>.** 
13ae0 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
13af0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
13b00 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
13b10 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
13b20 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f  .** an [sqlite3_
13b30 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d  pcache_methods2]
13b40 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f   object.  This o
13b50 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 73 20  bject specifies 
13b60 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  the interface.**
13b70 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67   to a custom pag
13b80 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
13b90 74 61 74 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69  tation.)^  ^SQLi
13ba0 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  te makes a copy 
13bb0 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 74  of the.** object
13bc0 20 61 6e 64 20 75 73 65 73 20 69 74 20 66 6f 72   and uses it for
13bd0 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f   page cache memo
13be0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c  ry allocations.<
13bf0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
13c00 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
13c10 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49  ACHE2]] <dt>SQLI
13c20 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
13c30 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  CHE2</dt>.** <dd
13c40 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
13c50 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
13c60 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
13c70 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
13c80 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63 61  .** [sqlite3_pca
13c90 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62  che_methods2] ob
13ca0 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f  ject.  SQLite co
13cb0 70 69 65 73 20 6f 66 20 74 68 65 20 63 75 72 72  pies of the curr
13cc0 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61 63 68  ent.** page cach
13cd0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
13ce0 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63   into that objec
13cf0 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  t.)^ </dd>.**.**
13d00 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
13d10 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  _LOG]] <dt>SQLIT
13d20 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74  E_CONFIG_LOG</dt
13d30 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51  >.** <dd> The SQ
13d40 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
13d50 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
13d60 6f 20 63 6f 6e 66 69 67 75 72 65 20 74 68 65 20  o configure the 
13d70 53 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c  SQLite.** global
13d80 20 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a   [error log]..**
13d90 20 28 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   (^The SQLITE_CO
13da0 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20  NFIG_LOG option 
13db0 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65  takes two argume
13dc0 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74  nts: a pointer t
13dd0 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  o a.** function 
13de0 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e  with a call sign
13df0 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29  ature of void(*)
13e00 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
13e10 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64   char*), .** and
13e20 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f   a pointer to vo
13e30 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63  id. ^If the func
13e40 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
13e50 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a  not NULL, it is.
13e60 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73  ** invoked by [s
13e70 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f  qlite3_log()] to
13e80 20 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f   process each lo
13e90 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49  gging event.  ^I
13ea0 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  f the.** functio
13eb0 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c  n pointer is NUL
13ec0 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  L, the [sqlite3_
13ed0 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  log()] interface
13ee0 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70   becomes a no-op
13ef0 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70  ..** ^The void p
13f00 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 74  ointer that is t
13f10 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
13f20 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e  nt to SQLITE_CON
13f30 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61  FIG_LOG is.** pa
13f40 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20  ssed through as 
13f50 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
13f60 74 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69  ter to the appli
13f70 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c  cation-defined l
13f80 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  ogger.** functio
13f90 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61 74 20  n whenever that 
13fa0 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f  function is invo
13fb0 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e  ked.  ^The secon
13fc0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  d parameter to.*
13fd0 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e  * the logger fun
13fe0 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20  ction is a copy 
13ff0 6f 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72  of the first par
14000 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f  ameter to the co
14010 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b  rresponding.** [
14020 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63  sqlite3_log()] c
14030 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e  all and is inten
14040 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73  ded to be a [res
14050 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a  ult code] or an.
14060 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
14070 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65  ult code].  ^The
14080 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
14090 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c   passed to the l
140a0 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20  ogger is.** log 
140b0 6d 65 73 73 61 67 65 20 61 66 74 65 72 20 66 6f  message after fo
140c0 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71  rmatting via [sq
140d0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
140e0 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  ]..** The SQLite
140f0 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61   logging interfa
14100 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72  ce is not reentr
14110 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20  ant; the logger 
14120 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70  function.** supp
14130 6c 69 65 64 20 62 79 20 74 68 65 20 61 70 70 6c  lied by the appl
14140 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
14150 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69   invoke any SQLi
14160 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  te interface..**
14170 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65   In a multi-thre
14180 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e  aded application
14190 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
141a0 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72  n-defined logger
141b0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  .** function mus
141c0 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e  t be threadsafe.
141d0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
141e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
141f0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
14200 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e  NFIG_URI.** <dd>
14210 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
14220 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
14230 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e  ument of type in
14240 74 2e 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  t. If non-zero, 
14250 74 68 65 6e 0a 2a 2a 20 55 52 49 20 68 61 6e 64  then.** URI hand
14260 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79  ling is globally
14270 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65   enabled. If the
14280 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65   parameter is ze
14290 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e  ro, then URI han
142a0 64 6c 69 6e 67 0a 2a 2a 20 69 73 20 67 6c 6f 62  dling.** is glob
142b0 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 29 5e  ally disabled.)^
142c0 20 5e 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e   ^If URI handlin
142d0 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e  g is globally en
142e0 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e  abled, all filen
142f0 61 6d 65 73 0a 2a 2a 20 70 61 73 73 65 64 20 74  ames.** passed t
14300 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
14310 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
14320 6e 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  n_v2()], [sqlite
14330 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a  3_open16()] or.*
14340 2a 20 73 70 65 63 69 66 69 65 64 20 61 73 20 70  * specified as p
14350 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d 20  art of [ATTACH] 
14360 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e 74  commands are int
14370 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73  erpreted as URIs
14380 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20  , regardless.** 
14390 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
143a0 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  t the [SQLITE_OP
143b0 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 20  EN_URI] flag is 
143c0 73 65 74 20 77 68 65 6e 20 74 68 65 20 64 61 74  set when the dat
143d0 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
143e0 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e  ion is opened. ^
143f0 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c  If it is globall
14400 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c 65  y disabled, file
14410 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c  names are.** onl
14420 79 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  y interpreted as
14430 20 55 52 49 73 20 69 66 20 74 68 65 20 53 51 4c   URIs if the SQL
14440 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61  ITE_OPEN_URI fla
14450 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68  g is set when th
14460 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
14470 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e  nnection is open
14480 65 64 2e 20 5e 28 42 79 20 64 65 66 61 75 6c 74  ed. ^(By default
14490 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  , URI handling i
144a0 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69  s globally.** di
144b0 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66 61  sabled. The defa
144c0 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62 65  ult value may be
144d0 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d 70   changed by comp
144e0 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a 2a  iling with the.*
144f0 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52  * [SQLITE_USE_UR
14500 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65  I] symbol define
14510 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d.)^.**.** [[SQL
14520 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52  ITE_CONFIG_COVER
14530 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d  ING_INDEX_SCAN]]
14540 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
14550 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  IG_COVERING_INDE
14560 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54  X_SCAN.** <dd>^T
14570 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
14580 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 65 67 65   a single intege
14590 72 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  r argument which
145a0 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
145b0 61 73 0a 2a 2a 20 61 20 62 6f 6f 6c 65 61 6e 20  as.** a boolean 
145c0 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e 61 62  in order to enab
145d0 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68  le or disable th
145e0 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e  e use of coverin
145f0 67 20 69 6e 64 69 63 65 73 20 66 6f 72 0a 2a 2a  g indices for.**
14600 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e   full table scan
14610 73 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 6f  s in the query o
14620 70 74 69 6d 69 7a 65 72 2e 20 20 5e 54 68 65 20  ptimizer.  ^The 
14630 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20  default setting 
14640 69 73 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a  is determined.**
14650 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   by the [SQLITE_
14660 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49  ALLOW_COVERING_I
14670 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69  NDEX_SCAN] compi
14680 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20  le-time option, 
14690 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66  or is "on".** if
146a0 20 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69   that compile-ti
146b0 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69  me option is omi
146c0 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69  tted..** The abi
146d0 6c 69 74 79 20 74 6f 20 64 69 73 61 62 6c 65 20  lity to disable 
146e0 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72  the use of cover
146f0 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20  ing indices for 
14700 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73  full table scans
14710 0a 2a 2a 20 69 73 20 62 65 63 61 75 73 65 20 73  .** is because s
14720 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c 79 20  ome incorrectly 
14730 63 6f 64 65 64 20 6c 65 67 61 63 79 20 61 70 70  coded legacy app
14740 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  lications might 
14750 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77  malfunction.** w
14760 68 65 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a 61  hen the optimiza
14770 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e  tion is enabled.
14780 20 20 50 72 6f 76 69 64 69 6e 67 20 74 68 65 20    Providing the 
14790 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69  ability to.** di
147a0 73 61 62 6c 65 20 74 68 65 20 6f 70 74 69 6d 69  sable the optimi
147b0 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68  zation allows th
147c0 65 20 6f 6c 64 65 72 2c 20 62 75 67 67 79 20 61  e older, buggy a
147d0 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20  pplication code 
147e0 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f  to work.** witho
147f0 75 74 20 63 68 61 6e 67 65 20 65 76 65 6e 20 77  ut change even w
14800 69 74 68 20 6e 65 77 65 72 20 76 65 72 73 69 6f  ith newer versio
14810 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  ns of SQLite..**
14820 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
14830 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53  FIG_PCACHE]] [[S
14840 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
14850 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e  PCACHE]].** <dt>
14860 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
14870 41 43 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f  ACHE and SQLITE_
14880 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
14890 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f  .** <dd> These o
148a0 70 74 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c  ptions are obsol
148b0 65 74 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e  ete and should n
148c0 6f 74 20 62 65 20 75 73 65 64 20 62 79 20 6e 65  ot be used by ne
148d0 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20  w code..** They 
148e0 61 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72  are retained for
148f0 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
14900 74 69 62 69 6c 69 74 79 20 62 75 74 20 61 72 65  tibility but are
14910 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20   now no-ops..** 
14920 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
14930 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c  LITE_CONFIG_SQLL
14940 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  OG]].** <dt>SQLI
14950 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47  TE_CONFIG_SQLLOG
14960 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
14970 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  ion is only avai
14980 6c 61 62 6c 65 20 69 66 20 73 71 6c 69 74 65 20  lable if sqlite 
14990 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
149a0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
149b0 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70  ENABLE_SQLLOG] p
149c0 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  re-processor mac
149d0 72 6f 20 64 65 66 69 6e 65 64 2e 20 54 68 65 20  ro defined. The 
149e0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 73  first argument s
149f0 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f  hould.** be a po
14a00 69 6e 74 65 72 20 74 6f 20 61 20 66 75 6e 63 74  inter to a funct
14a10 69 6f 6e 20 6f 66 20 74 79 70 65 20 76 6f 69 64  ion of type void
14a20 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
14a30 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  3*,const char*, 
14a40 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63  int)..** The sec
14a50 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65 20 6f 66  ond should be of
14a60 20 74 79 70 65 20 28 76 6f 69 64 2a 29 2e 20 54   type (void*). T
14a70 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  he callback is i
14a80 6e 76 6f 6b 65 64 20 62 79 20 74 68 65 20 6c 69  nvoked by the li
14a90 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65  brary.** in thre
14aa0 65 20 73 65 70 61 72 61 74 65 20 63 69 72 63 75  e separate circu
14ab0 6d 73 74 61 6e 63 65 73 2c 20 69 64 65 6e 74 69  mstances, identi
14ac0 66 69 65 64 20 62 79 20 74 68 65 20 76 61 6c 75  fied by the valu
14ad0 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 0a  e passed as the.
14ae0 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  ** fourth parame
14af0 74 65 72 2e 20 49 66 20 74 68 65 20 66 6f 75 72  ter. If the four
14b00 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
14b10 30 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  0, then the data
14b20 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
14b30 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ** passed as the
14b40 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
14b50 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 6f   has just been o
14b60 70 65 6e 65 64 2e 20 54 68 65 20 74 68 69 72 64  pened. The third
14b70 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69   argument.** poi
14b80 6e 74 73 20 74 6f 20 61 20 62 75 66 66 65 72 20  nts to a buffer 
14b90 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e  containing the n
14ba0 61 6d 65 20 6f 66 20 74 68 65 20 6d 61 69 6e 20  ame of the main 
14bb0 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20 49  database file. I
14bc0 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20  f the.** fourth 
14bd0 70 61 72 61 6d 65 74 65 72 20 69 73 20 31 2c 20  parameter is 1, 
14be0 74 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61  then the SQL sta
14bf0 74 65 6d 65 6e 74 20 74 68 61 74 20 74 68 65 20  tement that the 
14c00 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 0a  third parameter.
14c10 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 68 61 73  ** points to has
14c20 20 6a 75 73 74 20 62 65 65 6e 20 65 78 65 63 75   just been execu
14c30 74 65 64 2e 20 4f 72 2c 20 69 66 20 74 68 65 20  ted. Or, if the 
14c40 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
14c50 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74   is 2, then.** t
14c60 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65  he connection be
14c70 69 6e 67 20 70 61 73 73 65 64 20 61 73 20 74 68  ing passed as th
14c80 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
14c90 65 72 20 69 73 20 62 65 69 6e 67 20 63 6c 6f 73  er is being clos
14ca0 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64  ed. The.** third
14cb0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 61   parameter is pa
14cc0 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69  ssed NULL In thi
14cd0 73 20 63 61 73 65 2e 20 20 41 6e 20 65 78 61 6d  s case.  An exam
14ce0 70 6c 65 20 6f 66 20 75 73 69 6e 67 20 74 68 69  ple of using thi
14cf0 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  s.** configurati
14d00 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  on option can be
14d10 20 73 65 65 6e 20 69 6e 20 74 68 65 20 22 74 65   seen in the "te
14d20 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 20 73 6f 75  st_sqllog.c" sou
14d30 72 63 65 20 66 69 6c 65 20 69 6e 0a 2a 2a 20 74  rce file in.** t
14d40 68 65 20 63 61 6e 6f 6e 69 63 61 6c 20 53 51 4c  he canonical SQL
14d50 69 74 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e  ite source tree.
14d60 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
14d70 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50  LITE_CONFIG_MMAP
14d80 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  _SIZE]].** <dt>S
14d90 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41  QLITE_CONFIG_MMA
14da0 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53  P_SIZE.** <dd>^S
14db0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41  QLITE_CONFIG_MMA
14dc0 50 5f 53 49 5a 45 20 74 61 6b 65 73 20 74 77 6f  P_SIZE takes two
14dd0 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20   64-bit integer 
14de0 28 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 20  (sqlite3_int64) 
14df0 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 61  values.** that a
14e00 72 65 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  re the default m
14e10 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 20 28  map size limit (
14e20 74 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74  the default sett
14e30 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50 52 41 47  ing for.** [PRAG
14e40 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 29 20 61  MA mmap_size]) a
14e50 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 61  nd the maximum a
14e60 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65  llowed mmap size
14e70 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20   limit..** ^The 
14e80 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20  default setting 
14e90 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65  can be overridde
14ea0 6e 20 62 79 20 65 61 63 68 20 64 61 74 61 62 61  n by each databa
14eb0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73  se connection us
14ec0 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72 20 74 68  ing.** either th
14ed0 65 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73  e [PRAGMA mmap_s
14ee0 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72  ize] command, or
14ef0 20 62 79 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a   by using the.**
14f00 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d   [SQLITE_FCNTL_M
14f10 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63  MAP_SIZE] file c
14f20 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54 68 65 20 6d  ontrol.  ^(The m
14f30 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d  aximum allowed m
14f40 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 63 61 6e 6e  map size.** cann
14f50 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20 61 74  ot be changed at
14f60 20 72 75 6e 2d 74 69 6d 65 2e 20 20 4e 6f 72 20   run-time.  Nor 
14f70 6d 61 79 20 74 68 65 20 6d 61 78 69 6d 75 6d 20  may the maximum 
14f80 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a  allowed mmap siz
14f90 65 0a 2a 2a 20 65 78 63 65 65 64 20 74 68 65 20  e.** exceed the 
14fa0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 61 78  compile-time max
14fb0 69 6d 75 6d 20 6d 6d 61 70 20 73 69 7a 65 20 73  imum mmap size s
14fc0 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51  et by the.** [SQ
14fd0 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49  LITE_MAX_MMAP_SI
14fe0 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  ZE] compile-time
14ff0 20 6f 70 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49   option.)^.** ^I
15000 66 20 65 69 74 68 65 72 20 61 72 67 75 6d 65 6e  f either argumen
15010 74 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  t to this option
15020 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
15030 65 6e 20 74 68 61 74 20 61 72 67 75 6d 65 6e 74  en that argument
15040 20 69 73 0a 2a 2a 20 63 68 61 6e 67 65 64 20 74   is.** changed t
15050 6f 20 69 74 73 20 63 6f 6d 70 69 6c 65 2d 74 69  o its compile-ti
15060 6d 65 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a  me default..**.*
15070 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
15080 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
15090 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
150a0 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
150b0 41 50 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54  APSIZE.** <dd>^T
150c0 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e  his option is on
150d0 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
150e0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
150f0 65 64 20 66 6f 72 20 57 69 6e 64 6f 77 73 0a 2a  ed for Windows.*
15100 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49  * with the [SQLI
15110 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 5d  TE_WIN32_MALLOC]
15120 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d   pre-processor m
15130 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 0a 2a 2a  acro defined..**
15140 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57   SQLITE_CONFIG_W
15150 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 74 61  IN32_HEAPSIZE ta
15160 6b 65 73 20 61 20 33 32 2d 62 69 74 20 75 6e 73  kes a 32-bit uns
15170 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 76 61  igned integer va
15180 6c 75 65 0a 2a 2a 20 74 68 61 74 20 73 70 65 63  lue.** that spec
15190 69 66 69 65 73 20 74 68 65 20 6d 61 78 69 6d 75  ifies the maximu
151a0 6d 20 73 69 7a 65 20 6f 66 20 74 68 65 20 63 72  m size of the cr
151b0 65 61 74 65 64 20 68 65 61 70 2e 0a 2a 2a 20 3c  eated heap..** <
151c0 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
151d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
151e0 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f  NGLETHREAD  1  /
151f0 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
15200 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
15210 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20  ULTITHREAD   2  
15220 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
15230 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15240 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20  SERIALIZED    3 
15250 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
15260 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
15270 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34  _MALLOC        4
15280 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d    /* sqlite3_mem
15290 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
152a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
152b0 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20  IG_GETMALLOC    
152c0 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   5  /* sqlite3_m
152d0 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  em_methods* */.#
152e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
152f0 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20  NFIG_SCRATCH    
15300 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     6  /* void*, 
15310 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f  int sz, int N */
15320 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15330 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
15340 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a       7  /* void*
15350 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20  , int sz, int N 
15360 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
15370 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20  E_CONFIG_HEAP   
15380 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69         8  /* voi
15390 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69  d*, int nByte, i
153a0 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e  nt min */.#defin
153b0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
153c0 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 20  MEMSTATUS     9 
153d0 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23   /* boolean */.#
153e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
153f0 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20  NFIG_MUTEX      
15400 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33    10  /* sqlite3
15410 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20  _mutex_methods* 
15420 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
15430 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
15440 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c  X     11  /* sql
15450 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
15460 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f  ds* */./* previo
15470 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46  usly SQLITE_CONF
15480 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32  IG_CHUNKALLOC 12
15490 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e   which is now un
154a0 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e  used. */ .#defin
154b0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
154c0 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20  LOOKASIDE    13 
154d0 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23   /* int int */.#
154e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
154f0 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20 20  NFIG_PCACHE     
15500 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a    14  /* no-op *
15510 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15520 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
15530 45 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f  E    15  /* no-o
15540 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  p */.#define SQL
15550 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20  ITE_CONFIG_LOG  
15560 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20 78          16  /* x
15570 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23  Func, void* */.#
15580 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
15590 4e 46 49 47 5f 55 52 49 20 20 20 20 20 20 20 20  NFIG_URI        
155a0 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a    17  /* int */.
155b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
155c0 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 20 20  ONFIG_PCACHE2   
155d0 20 20 20 31 38 20 20 2f 2a 20 73 71 6c 69 74 65     18  /* sqlite
155e0 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
155f0 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  2* */.#define SQ
15600 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
15610 43 41 43 48 45 32 20 20 20 31 39 20 20 2f 2a 20  CACHE2   19  /* 
15620 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
15630 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66  ethods2* */.#def
15640 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
15650 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  G_COVERING_INDEX
15660 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20 69 6e 74  _SCAN 20  /* int
15670 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15680 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47  TE_CONFIG_SQLLOG
15690 20 20 20 20 20 20 20 32 31 20 20 2f 2a 20 78 53         21  /* xS
156a0 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f 0a  qllog, void* */.
156b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
156c0 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20  ONFIG_MMAP_SIZE 
156d0 20 20 20 32 32 20 20 2f 2a 20 73 71 6c 69 74 65     22  /* sqlite
156e0 33 5f 69 6e 74 36 34 2c 20 73 71 6c 69 74 65 33  3_int64, sqlite3
156f0 5f 69 6e 74 36 34 20 2a 2f 0a 23 64 65 66 69 6e  _int64 */.#defin
15700 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15710 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 20  WIN32_HEAPSIZE  
15720 20 20 20 20 32 33 20 20 2f 2a 20 69 6e 74 20 6e      23  /* int n
15730 42 79 74 65 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  Byte */../*.** C
15740 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73  API3REF: Databas
15750 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e  e Connection Con
15760 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f  figuration Optio
15770 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  ns.**.** These c
15780 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65  onstants are the
15790 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67   available integ
157a0 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  er configuration
157b0 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a   options that.**
157c0 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61   can be passed a
157d0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
157e0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71  ument to the [sq
157f0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
15800 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
15810 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72  .** New configur
15820 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61  ation options ma
15830 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
15840 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
15850 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73   SQLite..** Exis
15860 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ting configurati
15870 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74  on options might
15880 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64   be discontinued
15890 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a  .  Applications.
158a0 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20  ** should check 
158b0 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20  the return code 
158c0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62  from [sqlite3_db
158d0 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61  _config()] to ma
158e0 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20  ke sure that.** 
158f0 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e  the call worked.
15900 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f    ^The [sqlite3_
15910 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  db_config()] int
15920 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75  erface will retu
15930 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f  rn a.** non-zero
15940 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66   [error code] if
15950 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20   a discontinued 
15960 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63  or unsupported c
15970 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
15980 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65  ion.** is invoke
15990 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  d..**.** <dl>.**
159a0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
159b0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f  NFIG_LOOKASIDE</
159c0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
159d0 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  s option takes t
159e0 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20  hree additional 
159f0 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64  arguments that d
15a00 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a  etermine the .**
15a10 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f   [lookaside memo
15a20 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f  ry allocator] co
15a30 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20  nfiguration for 
15a40 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
15a50 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54  nnection]..** ^T
15a60 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
15a70 74 20 28 74 68 65 20 74 68 69 72 64 20 70 61 72  t (the third par
15a80 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
15a90 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
15aa0 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  is a.** pointer 
15ab0 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75 66 66  to a memory buff
15ac0 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f  er to use for lo
15ad0 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a  okaside memory..
15ae0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
15af0 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74 68 65  gument after the
15b00 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
15b10 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72 62 0a  _LOOKASIDE verb.
15b20 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69  ** may be NULL i
15b30 6e 20 77 68 69 63 68 20 63 61 73 65 20 53 51 4c  n which case SQL
15b40 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74  ite will allocat
15b50 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69  e the.** lookasi
15b60 64 65 20 62 75 66 66 65 72 20 69 74 73 65 6c 66  de buffer itself
15b70 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
15b80 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20  malloc()]. ^The 
15b90 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
15ba0 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f  is the.** size o
15bb0 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65  f each lookaside
15bc0 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e   buffer slot.  ^
15bd0 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
15be0 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  nt is the number
15bf0 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54   of.** slots.  T
15c00 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62  he size of the b
15c10 75 66 66 65 72 20 69 6e 20 74 68 65 20 66 69 72  uffer in the fir
15c20 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  st argument must
15c30 20 62 65 20 67 72 65 61 74 65 72 20 74 68 61 6e   be greater than
15c40 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  .** or equal to 
15c50 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74  the product of t
15c60 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68  he second and th
15c70 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 20 20  ird arguments.  
15c80 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75  The buffer.** mu
15c90 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f  st be aligned to
15ca0 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64   an 8-byte bound
15cb0 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20 73 65  ary.  ^If the se
15cc0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
15cd0 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  .** SQLITE_DBCON
15ce0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73  FIG_LOOKASIDE is
15cf0 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65 20   not a multiple 
15d00 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e 74 65  of 8, it is inte
15d10 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65  rnally.** rounde
15d20 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65  d down to the ne
15d30 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69  xt smaller multi
15d40 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54 68 65  ple of 8.  ^(The
15d50 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
15d60 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  y.** configurati
15d70 6f 6e 20 66 6f 72 20 61 20 64 61 74 61 62 61 73  on for a databas
15d80 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e  e connection can
15d90 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67 65 64   only be changed
15da0 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f   when that.** co
15db0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20  nnection is not 
15dc0 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e 67 20  currently using 
15dd0 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
15de0 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72 20 77 6f  , or in other wo
15df0 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20  rds.** when the 
15e00 22 63 75 72 72 65 6e 74 20 76 61 6c 75 65 22 20  "current value" 
15e10 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
15e20 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75  sqlite3_db_statu
15e30 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e  s](D,[SQLITE_CON
15e40 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e  FIG_LOOKASIDE],.
15e50 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20  ..) is zero..** 
15e60 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63  Any attempt to c
15e70 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73  hange the lookas
15e80 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69  ide memory confi
15e90 67 75 72 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f  guration when lo
15ea0 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72  okaside.** memor
15eb0 79 20 69 73 20 69 6e 20 75 73 65 20 6c 65 61 76  y is in use leav
15ec0 65 73 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  es the configura
15ed0 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64 20 61  tion unchanged a
15ee0 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b  nd returns .** [
15ef0 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c  SQLITE_BUSY].)^<
15f00 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
15f10 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
15f20 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a  NABLE_FKEY</dt>.
15f30 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
15f40 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
15f50 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
15f60 65 20 74 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e  e the enforcemen
15f70 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e  t of.** [foreign
15f80 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73   key constraints
15f90 5d 2e 20 20 54 68 65 72 65 20 73 68 6f 75 6c 64  ].  There should
15fa0 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e   be two addition
15fb0 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  al arguments..**
15fc0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
15fd0 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ent is an intege
15fe0 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20  r which is 0 to 
15ff0 64 69 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72  disable FK enfor
16000 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74  cement,.** posit
16010 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b  ive to enable FK
16020 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20   enforcement or 
16030 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76  negative to leav
16040 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
16050 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20 20  .** unchanged.  
16060 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
16070 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65  eter is a pointe
16080 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
16090 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73  into which.** is
160a0 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20   written 0 or 1 
160b0 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74  to indicate whet
160c0 68 65 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  her FK enforceme
160d0 6e 74 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a  nt is off or on.
160e0 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69  ** following thi
160f0 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63  s call.  The sec
16100 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61  ond parameter ma
16110 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  y be a NULL poin
16120 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68  ter, in.** which
16130 20 63 61 73 65 20 74 68 65 20 46 4b 20 65 6e 66   case the FK enf
16140 6f 72 63 65 6d 65 6e 74 20 73 65 74 74 69 6e 67  orcement setting
16150 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64   is not reported
16160 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a   back. </dd>.**.
16170 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
16180 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52  CONFIG_ENABLE_TR
16190 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  IGGER</dt>.** <d
161a0 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
161b0 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c  is used to enabl
161c0 65 20 6f 72 20 64 69 73 61 62 6c 65 20 5b 43 52  e or disable [CR
161d0 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74  EATE TRIGGER | t
161e0 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65  riggers]..** The
161f0 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f  re should be two
16200 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
16210 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69  ments..** The fi
16220 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
16230 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  an integer which
16240 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
16250 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f   triggers,.** po
16260 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65  sitive to enable
16270 20 74 72 69 67 67 65 72 73 20 6f 72 20 6e 65 67   triggers or neg
16280 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74  ative to leave t
16290 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61  he setting uncha
162a0 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63  nged..** The sec
162b0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
162c0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
162d0 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68   integer into wh
162e0 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65  ich.** is writte
162f0 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  n 0 or 1 to indi
16300 63 61 74 65 20 77 68 65 74 68 65 72 20 74 72 69  cate whether tri
16310 67 67 65 72 73 20 61 72 65 20 64 69 73 61 62 6c  ggers are disabl
16320 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a  ed or enabled.**
16330 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20   following this 
16340 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e  call.  The secon
16350 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  d parameter may 
16360 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  be a NULL pointe
16370 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63  r, in.** which c
16380 61 73 65 20 74 68 65 20 74 72 69 67 67 65 72 20  ase the trigger 
16390 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72  setting is not r
163a0 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f  eported back. </
163b0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a  dd>.**.** </dl>.
163c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
163d0 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
163e0 53 49 44 45 20 20 20 20 20 20 20 31 30 30 31 20  SIDE       1001 
163f0 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e   /* void* int in
16400 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
16410 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
16420 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 31 30 30  BLE_FKEY     100
16430 32 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  2  /* int int* *
16440 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16450 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
16460 5f 54 52 49 47 47 45 52 20 20 31 30 30 33 20 20  _TRIGGER  1003  
16470 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a  /* int int* */..
16480 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
16490 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62   Enable Or Disab
164a0 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  le Extended Resu
164b0 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e  lt Codes.**.** ^
164c0 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
164d0 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
164e0 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62  s() routine enab
164f0 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
16500 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64  the.** [extended
16510 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66   result codes] f
16520 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65  eature of SQLite
16530 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20  . ^The extended 
16540 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20  result.** codes 
16550 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20  are disabled by 
16560 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74  default for hist
16570 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69  orical compatibi
16580 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  lity..*/.int sql
16590 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
165a0 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74  sult_codes(sqlit
165b0 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b  e3*, int onoff);
165c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
165d0 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f  : Last Insert Ro
165e0 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20  wid.**.** ^Each 
165f0 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74 20 53 51  entry in most SQ
16600 4c 69 74 65 20 74 61 62 6c 65 73 20 28 65 78 63  Lite tables (exc
16610 65 70 74 20 66 6f 72 20 5b 57 49 54 48 4f 55 54  ept for [WITHOUT
16620 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 29 0a   ROWID] tables).
16630 2a 2a 20 68 61 73 20 61 20 75 6e 69 71 75 65 20  ** has a unique 
16640 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a  64-bit signed.**
16650 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c   integer key cal
16660 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c  led the [ROWID |
16670 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20   "rowid"]. ^The 
16680 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20  rowid is always 
16690 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20  available.** as 
166a0 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f  an undeclared co
166b0 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44  lumn named ROWID
166c0 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44  , OID, or _ROWID
166d0 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f  _ as long as tho
166e0 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20  se.** names are 
166f0 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79  not also used by
16700 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c   explicitly decl
16710 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49  ared columns. ^I
16720 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68  f.** the table h
16730 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  as a column of t
16740 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49  ype [INTEGER PRI
16750 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74  MARY KEY] then t
16760 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  hat column.** is
16770 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66   another alias f
16780 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a  or the rowid..**
16790 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
167a0 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
167b0 69 64 28 44 29 20 69 6e 74 65 72 66 61 63 65 20  id(D) interface 
167c0 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77  returns the [row
167d0 69 64 5d 20 6f 66 20 74 68 65 20 0a 2a 2a 20 6d  id] of the .** m
167e0 6f 73 74 20 72 65 63 65 6e 74 20 73 75 63 63 65  ost recent succe
167f0 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69  ssful [INSERT] i
16800 6e 74 6f 20 61 20 72 6f 77 69 64 20 74 61 62 6c  nto a rowid tabl
16810 65 20 6f 72 20 5b 76 69 72 74 75 61 6c 20 74 61  e or [virtual ta
16820 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61 74 61 62  ble].** on datab
16830 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44  ase connection D
16840 2e 0a 2a 2a 20 5e 49 6e 73 65 72 74 73 20 69 6e  ..** ^Inserts in
16850 74 6f 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49  to [WITHOUT ROWI
16860 44 5d 20 74 61 62 6c 65 73 20 61 72 65 20 6e 6f  D] tables are no
16870 74 20 72 65 63 6f 72 64 65 64 2e 0a 2a 2a 20 5e  t recorded..** ^
16880 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c  If no successful
16890 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e 74 6f 20   [INSERT]s into 
168a0 72 6f 77 69 64 20 74 61 62 6c 65 73 0a 2a 2a 20  rowid tables.** 
168b0 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72  have ever occurr
168c0 65 64 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61  ed on the databa
168d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c  se connection D,
168e0 20 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65   .** then sqlite
168f0 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
16900 77 69 64 28 44 29 20 72 65 74 75 72 6e 73 20 7a  wid(D) returns z
16910 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  ero..**.** ^(If 
16920 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75  an [INSERT] occu
16930 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 69 67  rs within a trig
16940 67 65 72 20 6f 72 20 77 69 74 68 69 6e 20 61 20  ger or within a 
16950 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a  [virtual table].
16960 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20  ** method, then 
16970 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c  this routine wil
16980 6c 20 72 65 74 75 72 6e 20 74 68 65 20 5b 72 6f  l return the [ro
16990 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65  wid] of the inse
169a0 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61 73 20 6c  rted.** row as l
169b0 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67  ong as the trigg
169c0 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61  er or virtual ta
169d0 62 6c 65 20 6d 65 74 68 6f 64 20 69 73 20 72 75  ble method is ru
169e0 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e  nning..** But on
169f0 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20 6f  ce the trigger o
16a00 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  r virtual table 
16a10 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20 74 68 65  method ends, the
16a20 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
16a30 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74  .** by this rout
16a40 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20 77  ine reverts to w
16a50 68 61 74 20 69 74 20 77 61 73 20 62 65 66 6f 72  hat it was befor
16a60 65 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72  e the trigger or
16a70 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62 6c   virtual.** tabl
16a80 65 20 6d 65 74 68 6f 64 20 62 65 67 61 6e 2e 29  e method began.)
16a90 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53  ^.**.** ^An [INS
16aa0 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20  ERT] that fails 
16ab0 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61  due to a constra
16ac0 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73  int violation is
16ad0 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73   not a.** succes
16ae0 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e  sful [INSERT] an
16af0 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67  d does not chang
16b00 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  e the value retu
16b10 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20  rned by this.** 
16b20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20  routine.  ^Thus 
16b30 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20  INSERT OR FAIL, 
16b40 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45  INSERT OR IGNORE
16b50 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c  , INSERT OR ROLL
16b60 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53  BACK,.** and INS
16b70 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b  ERT OR ABORT mak
16b80 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20  e no changes to 
16b90 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
16ba0 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74   of this.** rout
16bb0 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20 69  ine when their i
16bc0 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20  nsertion fails. 
16bd0 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f   ^(When INSERT O
16be0 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63  R REPLACE.** enc
16bf0 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72  ounters a constr
16c00 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20  aint violation, 
16c10 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c  it does not fail
16c20 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54  .  The.** INSERT
16c30 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f   continues to co
16c40 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64  mpletion after d
16c50 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61  eleting rows tha
16c60 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20  t caused.** the 
16c70 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c  constraint probl
16c80 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20  em so INSERT OR 
16c90 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77  REPLACE will alw
16ca0 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68  ays change.** th
16cb0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
16cc0 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  f this interface
16cd0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74  .)^.**.** ^For t
16ce0 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74  he purposes of t
16cf0 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20  his routine, an 
16d00 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73  [INSERT] is cons
16d10 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20  idered to.** be 
16d20 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20  successful even 
16d30 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71 75  if it is subsequ
16d40 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63  ently rolled bac
16d50 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  k..**.** This fu
16d60 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73  nction is access
16d70 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74  ible to SQL stat
16d80 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a  ements via the.*
16d90 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  * [last_insert_r
16da0 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74  owid() SQL funct
16db0 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  ion]..**.** If a
16dc0 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
16dd0 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20   performs a new 
16de0 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20  [INSERT] on the 
16df0 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65  same.** database
16e00 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c   connection whil
16e10 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  e the [sqlite3_l
16e20 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
16e30 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ()].** function 
16e40 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74  is running and t
16e50 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 20  hus changes the 
16e60 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77  last insert [row
16e70 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  id],.** then the
16e80 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
16e90 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  by [sqlite3_last
16ea0 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
16eb0 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74   is.** unpredict
16ec0 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e  able and might n
16ed0 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72 20  ot equal either 
16ee0 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e  the old or the n
16ef0 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72  ew.** last inser
16f00 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71  t [rowid]..*/.sq
16f10 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
16f20 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
16f30 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b  rowid(sqlite3*);
16f40 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16f50 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62  : Count The Numb
16f60 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66  er Of Rows Modif
16f70 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ied.**.** ^This 
16f80 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
16f90 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64   the number of d
16fa0 61 74 61 62 61 73 65 20 72 6f 77 73 20 74 68 61  atabase rows tha
16fb0 74 20 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a  t were changed.*
16fc0 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72  * or inserted or
16fd0 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 20   deleted by the 
16fe0 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f  most recently co
16ff0 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74  mpleted SQL stat
17000 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20  ement.** on the 
17010 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
17020 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
17030 62 79 20 74 68 65 20 66 69 72 73 74 20 70 61 72  by the first par
17040 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c  ameter..** ^(Onl
17050 79 20 63 68 61 6e 67 65 73 20 74 68 61 74 20 61  y changes that a
17060 72 65 20 64 69 72 65 63 74 6c 79 20 73 70 65 63  re directly spec
17070 69 66 69 65 64 20 62 79 20 74 68 65 20 5b 49 4e  ified by the [IN
17080 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c  SERT], [UPDATE],
17090 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20  .** or [DELETE] 
170a0 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f  statement are co
170b0 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72  unted.  Auxiliar
170c0 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  y changes caused
170d0 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20   by.** triggers 
170e0 6f 72 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  or [foreign key 
170f0 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 6e 6f 74  actions] are not
17100 20 63 6f 75 6e 74 65 64 2e 29 5e 20 55 73 65 20   counted.)^ Use 
17110 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
17120 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
17130 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 66 69 6e   function to fin
17140 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62  d the total numb
17150 65 72 20 6f 66 20 63 68 61 6e 67 65 73 0a 2a 2a  er of changes.**
17160 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67   including chang
17170 65 73 20 63 61 75 73 65 64 20 62 79 20 74 72 69  es caused by tri
17180 67 67 65 72 73 20 61 6e 64 20 66 6f 72 65 69 67  ggers and foreig
17190 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 2e 0a 2a  n key actions..*
171a0 2a 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 74 6f  *.** ^Changes to
171b0 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65   a view that are
171c0 20 73 69 6d 75 6c 61 74 65 64 20 62 79 20 61 6e   simulated by an
171d0 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69   [INSTEAD OF tri
171e0 67 67 65 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74  gger].** are not
171f0 20 63 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c 79 20   counted.  Only 
17200 72 65 61 6c 20 74 61 62 6c 65 20 63 68 61 6e 67  real table chang
17210 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a  es are counted..
17220 2a 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f 77 20 63  **.** ^(A "row c
17230 68 61 6e 67 65 22 20 69 73 20 61 20 63 68 61 6e  hange" is a chan
17240 67 65 20 74 6f 20 61 20 73 69 6e 67 6c 65 20 72  ge to a single r
17250 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 74  ow of a single t
17260 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20 62  able.** caused b
17270 79 20 61 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c  y an INSERT, DEL
17280 45 54 45 2c 20 6f 72 20 55 50 44 41 54 45 20 73  ETE, or UPDATE s
17290 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20  tatement.  Rows 
172a0 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e  that.** are chan
172b0 67 65 64 20 61 73 20 73 69 64 65 20 65 66 66 65  ged as side effe
172c0 63 74 73 20 6f 66 20 5b 52 45 50 4c 41 43 45 5d  cts of [REPLACE]
172d0 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f   constraint reso
172e0 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62  lution,.** rollb
172f0 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63 65  ack, ABORT proce
17300 73 73 69 6e 67 2c 20 5b 44 52 4f 50 20 54 41 42  ssing, [DROP TAB
17310 4c 45 5d 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f  LE], or by any o
17320 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73  ther.** mechanis
17330 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20  ms do not count 
17340 61 73 20 64 69 72 65 63 74 20 72 6f 77 20 63 68  as direct row ch
17350 61 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41  anges.)^.**.** A
17360 20 22 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78   "trigger contex
17370 74 22 20 69 73 20 61 20 73 63 6f 70 65 20 6f 66  t" is a scope of
17380 20 65 78 65 63 75 74 69 6f 6e 20 74 68 61 74 20   execution that 
17390 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e  begins and.** en
173a0 64 73 20 77 69 74 68 20 74 68 65 20 73 63 72 69  ds with the scri
173b0 70 74 20 6f 66 20 61 20 5b 43 52 45 41 54 45 20  pt of a [CREATE 
173c0 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65  TRIGGER | trigge
173d0 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c  r]. .** Most SQL
173e0 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a   statements are.
173f0 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 6f 75 74  ** evaluated out
17400 73 69 64 65 20 6f 66 20 61 6e 79 20 74 72 69 67  side of any trig
17410 67 65 72 2e 20 20 54 68 69 73 20 69 73 20 74 68  ger.  This is th
17420 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a  e "top level".**
17430 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
17440 2e 20 20 49 66 20 61 20 74 72 69 67 67 65 72 20  .  If a trigger 
17450 66 69 72 65 73 20 66 72 6f 6d 20 74 68 65 20 74  fires from the t
17460 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e  op level, a.** n
17470 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ew trigger conte
17480 78 74 20 69 73 20 65 6e 74 65 72 65 64 20 66 6f  xt is entered fo
17490 72 20 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f  r the duration o
174a0 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72  f that one.** tr
174b0 69 67 67 65 72 2e 20 20 53 75 62 74 72 69 67 67  igger.  Subtrigg
174c0 65 72 73 20 63 72 65 61 74 65 20 73 75 62 63 6f  ers create subco
174d0 6e 74 65 78 74 73 20 66 6f 72 20 74 68 65 69 72  ntexts for their
174e0 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   duration..**.**
174f0 20 5e 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74   ^Calling [sqlit
17500 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73  e3_exec()] or [s
17510 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72  qlite3_step()] r
17520 65 63 75 72 73 69 76 65 6c 79 20 64 6f 65 73 0a  ecursively does.
17530 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 61 20  ** not create a 
17540 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74  new trigger cont
17550 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ext..**.** ^This
17560 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
17570 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
17580 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67  direct row chang
17590 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73  es in the.** mos
175a0 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c  t recent INSERT,
175b0 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
175c0 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  TE statement wit
175d0 68 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  hin the same.** 
175e0 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e  trigger context.
175f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20 77 68  .**.** ^Thus, wh
17600 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  en called from t
17610 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68  he top level, th
17620 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
17630 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65  rns the.** numbe
17640 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20  r of changes in 
17650 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
17660 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
17670 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61  or DELETE.** tha
17680 74 20 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20  t also occurred 
17690 61 74 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c  at the top level
176a0 2e 20 20 5e 28 57 69 74 68 69 6e 20 74 68 65 20  .  ^(Within the 
176b0 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67 67 65  body of a trigge
176c0 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65  r,.** the sqlite
176d0 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 74 65  3_changes() inte
176e0 72 66 61 63 65 20 63 61 6e 20 62 65 20 63 61 6c  rface can be cal
176f0 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20  led to find the 
17700 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61  number of.** cha
17710 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74  nges in the most
17720 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65   recently comple
17730 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ted INSERT, UPDA
17740 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  TE, or DELETE.**
17750 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
17760 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68  n the body of th
17770 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a  e same trigger..
17780 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20  ** However, the 
17790 6e 75 6d 62 65 72 20 72 65 74 75 72 6e 65 64 20  number returned 
177a0 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
177b0 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73   changes.** caus
177c0 65 64 20 62 79 20 73 75 62 74 72 69 67 67 65 72  ed by subtrigger
177d0 73 20 73 69 6e 63 65 20 74 68 6f 73 65 20 68 61  s since those ha
177e0 76 65 20 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e  ve their own con
177f0 74 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65  text.)^.**.** Se
17800 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69  e also the [sqli
17810 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
17820 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20  s()] interface, 
17830 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68  the.** [count_ch
17840 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61  anges pragma], a
17850 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28  nd the [changes(
17860 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
17870 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
17880 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65  rate thread make
17890 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65  s changes on the
178a0 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
178b0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69  onnection.** whi
178c0 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  le [sqlite3_chan
178d0 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
178e0 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
178f0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20   returned.** is 
17900 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
17910 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
17920 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
17930 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33  _changes(sqlite3
17940 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
17950 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65  REF: Total Numbe
17960 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69  r Of Rows Modifi
17970 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  ed.**.** ^This f
17980 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
17990 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
179a0 77 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  w changes caused
179b0 20 62 79 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a   by [INSERT],.**
179c0 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 45   [UPDATE] or [DE
179d0 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73  LETE] statements
179e0 20 73 69 6e 63 65 20 74 68 65 20 5b 64 61 74 61   since the [data
179f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
17a00 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20   was opened..** 
17a10 5e 28 54 68 65 20 63 6f 75 6e 74 20 72 65 74 75  ^(The count retu
17a20 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
17a30 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20  total_changes() 
17a40 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63 68 61  includes all cha
17a50 6e 67 65 73 0a 2a 2a 20 66 72 6f 6d 20 61 6c 6c  nges.** from all
17a60 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52   [CREATE TRIGGER
17a70 20 7c 20 74 72 69 67 67 65 72 5d 20 63 6f 6e 74   | trigger] cont
17a80 65 78 74 73 20 61 6e 64 20 63 68 61 6e 67 65 73  exts and changes
17a90 20 6d 61 64 65 20 62 79 0a 2a 2a 20 5b 66 6f 72   made by.** [for
17aa0 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73  eign key actions
17ab0 5d 2e 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74  ]. However,.** t
17ac0 68 65 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f  he count does no
17ad0 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65  t include change
17ae0 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  s used to implem
17af0 65 6e 74 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f  ent [REPLACE] co
17b00 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f  nstraints,.** do
17b10 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42   rollbacks or AB
17b20 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20  ORT processing, 
17b30 6f 72 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 20  or [DROP TABLE] 
17b40 70 72 6f 63 65 73 73 69 6e 67 2e 20 20 54 68 65  processing.  The
17b50 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e  .** count does n
17b60 6f 74 20 69 6e 63 6c 75 64 65 20 72 6f 77 73 20  ot include rows 
17b70 6f 66 20 76 69 65 77 73 20 74 68 61 74 20 66 69  of views that fi
17b80 72 65 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f  re an [INSTEAD O
17b90 46 20 74 72 69 67 67 65 72 5d 2c 0a 2a 2a 20 74  F trigger],.** t
17ba0 68 6f 75 67 68 20 69 66 20 74 68 65 20 49 4e 53  hough if the INS
17bb0 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 20  TEAD OF trigger 
17bc0 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 66  makes changes of
17bd0 20 69 74 73 20 6f 77 6e 2c 20 74 68 6f 73 65 20   its own, those 
17be0 63 68 61 6e 67 65 73 20 0a 2a 2a 20 61 72 65 20  changes .** are 
17bf0 63 6f 75 6e 74 65 64 2e 29 5e 0a 2a 2a 20 5e 54  counted.)^.** ^T
17c00 68 65 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  he sqlite3_total
17c10 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74  _changes() funct
17c20 69 6f 6e 20 63 6f 75 6e 74 73 20 74 68 65 20 63  ion counts the c
17c30 68 61 6e 67 65 73 20 61 73 20 73 6f 6f 6e 20 61  hanges as soon a
17c40 73 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65  s.** the stateme
17c50 6e 74 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68  nt that makes th
17c60 65 6d 20 69 73 20 63 6f 6d 70 6c 65 74 65 64 20  em is completed 
17c70 28 77 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d  (when the statem
17c80 65 6e 74 20 68 61 6e 64 6c 65 0a 2a 2a 20 69 73  ent handle.** is
17c90 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69   passed to [sqli
17ca0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
17cb0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
17cc0 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  e()])..**.** See
17cd0 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74   also the [sqlit
17ce0 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e  e3_changes()] in
17cf0 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20  terface, the.** 
17d00 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70  [count_changes p
17d10 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20  ragma], and the 
17d20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  [total_changes()
17d30 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
17d40 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72  **.** If a separ
17d50 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73  ate thread makes
17d60 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20   changes on the 
17d70 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
17d80 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c  nnection.** whil
17d90 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  e [sqlite3_total
17da0 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72  _changes()] is r
17db0 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20  unning then the 
17dc0 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65  value.** returne
17dd0 64 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62  d is unpredictab
17de0 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69  le and not meani
17df0 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ngful..*/.int 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 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
17e20 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
17e30 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67  Interrupt A Long
17e40 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a  -Running Query.*
17e50 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
17e60 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70  ion causes any p
17e70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20  ending database 
17e80 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f  operation to abo
17e90 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e  rt and.** return
17ea0 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 74   at its earliest
17eb0 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68   opportunity. Th
17ec0 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79  is routine is ty
17ed0 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65  pically.** calle
17ee0 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f  d in response to
17ef0 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73   a user action s
17f00 75 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20  uch as pressing 
17f10 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43  "Cancel".** or C
17f20 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20  trl-C where the 
17f30 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e  user wants a lon
17f40 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f  g query operatio
17f50 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d  n to halt.** imm
17f60 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ediately..**.** 
17f70 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63  ^It is safe to c
17f80 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  all this routine
17f90 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64   from a thread d
17fa0 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68  ifferent from th
17fb0 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74  e.** thread that
17fc0 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75   is currently ru
17fd0 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61  nning the databa
17fe0 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42  se operation.  B
17ff0 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20  ut it.** is not 
18000 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
18010 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61  s routine with a
18020 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
18030 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69  ction] that.** i
18040 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68  s closed or migh
18050 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73  t close before s
18060 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
18070 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  () returns..**.*
18080 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65  * ^If an SQL ope
18090 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e  ration is very n
180a0 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61  early finished a
180b0 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a  t the time when.
180c0 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  ** sqlite3_inter
180d0 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64  rupt() is called
180e0 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20  , then it might 
180f0 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f  not have an oppo
18100 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65  rtunity.** to be
18110 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64   interrupted and
18120 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20   might continue 
18130 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a  to completion..*
18140 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65  *.** ^An SQL ope
18150 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69  ration that is i
18160 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20  nterrupted will 
18170 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49  return [SQLITE_I
18180 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49  NTERRUPT]..** ^I
18190 66 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65  f the interrupte
181a0 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  d SQL operation 
181b0 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50  is an INSERT, UP
181c0 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a  DATE, or DELETE.
181d0 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 64  ** that is insid
181e0 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72  e an explicit tr
181f0 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
18200 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73  the entire trans
18210 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62  action.** will b
18220 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75  e rolled back au
18230 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a  tomatically..**.
18240 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
18250 69 6e 74 65 72 72 75 70 74 28 44 29 20 63 61 6c  interrupt(D) cal
18260 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74 20 75  l is in effect u
18270 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74  ntil all current
18280 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51  ly running.** SQ
18290 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20  L statements on 
182a0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
182b0 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65  tion] D complete
182c0 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20  .  ^Any new SQL 
182d0 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
182e0 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
182f0 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33  fter the sqlite3
18300 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
18310 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65  l and before the
18320 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61   .** running sta
18330 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20  tements reaches 
18340 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75  zero are interru
18350 70 74 65 64 20 61 73 20 69 66 20 74 68 65 79 20  pted as if they 
18360 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e  had been.** runn
18370 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65  ing prior to the
18380 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
18390 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77  pt() call.  ^New
183a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
183b0 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
183c0 74 65 64 20 61 66 74 65 72 20 74 68 65 20 72 75  ted after the ru
183d0 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  nning statement 
183e0 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65  count reaches ze
183f0 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66  ro are.** not ef
18400 66 65 63 74 65 64 20 62 79 20 74 68 65 20 73 71  fected by the sq
18410 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
18420 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f  )..** ^A call to
18430 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
18440 70 74 28 44 29 20 74 68 61 74 20 6f 63 63 75 72  pt(D) that occur
18450 73 20 77 68 65 6e 20 74 68 65 72 65 20 61 72 65  s when there are
18460 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53   no running.** S
18470 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73  QL statements is
18480 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73   a no-op and has
18490 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51   no effect on SQ
184a0 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
184b0 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
184c0 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74   after the sqlit
184d0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63  e3_interrupt() c
184e0 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  all returns..**.
184f0 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 61  ** If the databa
18500 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c  se connection cl
18510 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69  oses while [sqli
18520 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d  te3_interrupt()]
18530 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  .** is running t
18540 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77  hen bad things w
18550 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65  ill likely happe
18560 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  n..*/.void sqlit
18570 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c  e3_interrupt(sql
18580 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
18590 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
185a0 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61  ne If An SQL Sta
185b0 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65  tement Is Comple
185c0 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  te.**.** These r
185d0 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66  outines are usef
185e0 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e  ul during comman
185f0 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20  d-line input to 
18600 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65  determine if the
18610 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e  .** currently en
18620 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73  tered text seems
18630 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c   to form a compl
18640 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
18650 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74  t or.** if addit
18660 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e  ional input is n
18670 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e  eeded before sen
18680 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e  ding the text in
18690 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72  to.** SQLite for
186a0 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73   parsing.  ^Thes
186b0 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
186c0 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 74  n 1 if the input
186d0 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61   string.** appea
186e0 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c  rs to be a compl
186f0 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
18700 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74  t.  ^A statement
18710 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65   is judged to be
18720 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20  .** complete if 
18730 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73  it ends with a s
18740 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61  emicolon token a
18750 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66  nd is not a pref
18760 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d  ix of a.** well-
18770 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54 52  formed CREATE TR
18780 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e  IGGER statement.
18790 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68    ^Semicolons th
187a0 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20  at are embedded 
187b0 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67  within.** string
187c0 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f   literals or quo
187d0 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e  ted identifier n
187e0 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73  ames or comments
187f0 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65   are not.** inde
18800 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28  pendent tokens (
18810 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66  they are part of
18820 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68   the token in wh
18830 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20  ich they are.** 
18840 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68  embedded) and th
18850 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20  us do not count 
18860 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74  as a statement t
18870 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69  erminator.  ^Whi
18880 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63  tespace.** and c
18890 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c  omments that fol
188a0 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65  low the final se
188b0 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f  micolon are igno
188c0 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  red..**.** ^Thes
188d0 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
188e0 6e 20 30 20 69 66 20 74 68 65 20 73 74 61 74 65  n 0 if the state
188f0 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65  ment is incomple
18900 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65  te.  ^If a.** me
18910 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
18920 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49  fails, then SQLI
18930 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75  TE_NOMEM is retu
18940 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rned..**.** ^The
18950 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e  se routines do n
18960 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c  ot parse the SQL
18970 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73   statements thus
18980 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74  .** will not det
18990 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c  ect syntacticall
189a0 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e  y incorrect SQL.
189b0 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69  .**.** ^(If SQLi
189c0 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20  te has not been 
189d0 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e  initialized usin
189e0 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  g [sqlite3_initi
189f0 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a  alize()] prior .
18a00 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73  ** to invoking s
18a10 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
18a20 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33  6() then sqlite3
18a30 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
18a40 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f   invoked.** auto
18a50 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
18a60 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
18a70 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69 74  ).  If that init
18a80 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73  ialization fails
18a90 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65  ,.** then the re
18aa0 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
18ab0 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
18ac0 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e  16() will be non
18ad0 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c  -zero.** regardl
18ae0 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
18af0 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20  r not the input 
18b00 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e  SQL is complete.
18b10 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70  )^.**.** The inp
18b20 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ut to [sqlite3_c
18b30 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20  omplete()] must 
18b40 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  be a zero-termin
18b50 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74  ated.** UTF-8 st
18b60 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ring..**.** The 
18b70 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
18b80 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20  3_complete16()] 
18b90 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74  must be a zero-t
18ba0 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
18bb0 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61  -16 string in na
18bc0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
18bd0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
18be0 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63  complete(const c
18bf0 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73  har *sql);.int s
18c00 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
18c10 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  6(const void *sq
18c20 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
18c30 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20  REF: Register A 
18c40 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64  Callback To Hand
18c50 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45  le SQLITE_BUSY E
18c60 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  rrors.**.** ^Thi
18c70 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61  s routine sets a
18c80 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
18c90 6f 6e 20 74 68 61 74 20 6d 69 67 68 74 20 62 65  on that might be
18ca0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
18cb0 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20  r.** an attempt 
18cc0 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20  is made to open 
18cd0 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  a database table
18ce0 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68   that another th
18cf0 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65  read.** or proce
18d00 73 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a  ss has locked..*
18d10 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73  *.** ^If the bus
18d20 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  y callback is NU
18d30 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45  LL, then [SQLITE
18d40 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54  _BUSY] or [SQLIT
18d50 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
18d60 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
18d70 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e  immediately upon
18d80 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68   encountering th
18d90 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65  e lock.  ^If the
18da0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a   busy callback.*
18db0 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74  * is not NULL, t
18dc0 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
18dd0 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65   might be invoke
18de0 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d  d with two argum
18df0 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ents..**.** ^The
18e00 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
18e10 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  to the busy hand
18e20 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ler is a copy of
18e30 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74   the void* point
18e40 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74  er which.** is t
18e50 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
18e60 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73  t to sqlite3_bus
18e70 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54  y_handler().  ^T
18e80 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
18e90 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73  nt to.** the bus
18ea0 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y handler callba
18eb0 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ck is the number
18ec0 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74   of times that t
18ed0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
18ee0 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f  has.** been invo
18ef0 6b 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63  ked for this loc
18f00 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66  king event.  ^If
18f10 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c   the.** busy cal
18f20 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c  lback returns 0,
18f30 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f   then no additio
18f40 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65  nal attempts are
18f50 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65   made to.** acce
18f60 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ss the database 
18f70 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  and [SQLITE_BUSY
18f80 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  ] or [SQLITE_IOE
18f90 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72  RR_BLOCKED] is r
18fa0 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20  eturned..** ^If 
18fb0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
18fc0 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
18fd0 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65  hen another atte
18fe0 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74  mpt.** is made t
18ff0 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
19000 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ase for reading 
19010 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65  and the cycle re
19020 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  peats..**.** The
19030 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62   presence of a b
19040 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73  usy handler does
19050 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74   not guarantee t
19060 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69  hat it will be i
19070 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74  nvoked.** when t
19080 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e  here is lock con
19090 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c  tention. ^If SQL
190a0 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74  ite determines t
190b0 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65  hat invoking the
190c0 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72   busy.** handler
190d0 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e   could result in
190e0 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20   a deadlock, it 
190f0 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e  will go ahead an
19100 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  d return [SQLITE
19110 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51  _BUSY].** or [SQ
19120 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
19130 45 44 5d 20 69 6e 73 74 65 61 64 20 6f 66 20 69  ED] instead of i
19140 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79  nvoking the busy
19150 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e   handler..** Con
19160 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f  sider a scenario
19170 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65   where one proce
19180 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  ss is holding a 
19190 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a  read lock that.*
191a0 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74  * it is trying t
191b0 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72  o promote to a r
191c0 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64  eserved lock and
191d0 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f  .** a second pro
191e0 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20  cess is holding 
191f0 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20  a reserved lock 
19200 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e  that it is tryin
19210 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20  g.** to promote 
19220 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20  to an exclusive 
19230 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74  lock.  The first
19240 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20   process cannot 
19250 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75  proceed.** becau
19260 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64  se it is blocked
19270 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61   by the second a
19280 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72  nd the second pr
19290 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20  ocess cannot.** 
192a0 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20  proceed because 
192b0 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79  it is blocked by
192c0 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20   the first.  If 
192d0 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a  both processes.*
192e0 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73  * invoke the bus
192f0 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74  y handlers, neit
19300 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e  her will make an
19310 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65  y progress.  The
19320 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74  refore,.** SQLit
19330 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  e returns [SQLIT
19340 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20  E_BUSY] for the 
19350 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68  first process, h
19360 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a  oping that this.
19370 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74  ** will induce t
19380 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
19390 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20   to release its 
193a0 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c  read lock and al
193b0 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e  low.** the secon
193c0 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f  d process to pro
193d0 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ceed..**.** ^The
193e0 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61   default busy ca
193f0 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a  llback is NULL..
19400 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  **.** ^The [SQLI
19410 54 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69  TE_BUSY] error i
19420 73 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b  s converted to [
19430 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
19440 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51  CKED].** when SQ
19450 4c 69 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d  Lite is in the m
19460 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65  iddle of a large
19470 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65   transaction whe
19480 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68  re all the.** ch
19490 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66  anges will not f
194a0 69 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d  it into the in-m
194b0 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51  emory cache.  SQ
194c0 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72  Lite will.** alr
194d0 65 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45  eady hold a RESE
194e0 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65  RVED lock on the
194f0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20   database file, 
19500 62 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20  but it needs.** 
19510 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20  to promote this 
19520 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56  lock to EXCLUSIV
19530 45 20 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e  E so that it can
19540 20 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20   spill cache.** 
19550 70 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64  pages into the d
19560 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 74  atabase file wit
19570 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e  hout harm to con
19580 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65  current.** reade
19590 72 73 2e 20 20 5e 49 66 20 69 74 20 69 73 20 75  rs.  ^If it is u
195a0 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65  nable to promote
195b0 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20   the lock, then 
195c0 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a  the in-memory.**
195d0 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c   cache will be l
195e0 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73  eft in an incons
195f0 69 73 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64  istent state and
19600 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a   so the error.**
19610 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65   code is promote
19620 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74  d from the relat
19630 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51  ively benign [SQ
19640 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a  LITE_BUSY] to.**
19650 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65   the more severe
19660 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
19670 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54 68 69 73 20  LOCKED].  ^This 
19680 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f  error code promo
19690 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61  tion.** forces a
196a0 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c  n automatic roll
196b0 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e  back of the chan
196c0 67 65 73 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a  ges.  See the.**
196d0 20 3c 61 20 68 72 65 66 3d 22 2f 63 76 73 74 72   <a href="/cvstr
196e0 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70  ac/wiki?p=Corrup
196f0 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73  tionFollowingBus
19700 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72  yError">.** Corr
19710 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42  uptionFollowingB
19720 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b  usyError</a> wik
19730 69 20 70 61 67 65 20 66 6f 72 20 61 20 64 69 73  i page for a dis
19740 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a  cussion of why.*
19750 2a 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74  * this is import
19760 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ant..**.** ^(The
19770 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
19780 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
19790 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72  dler defined for
197a0 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61   each.** [databa
197b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
197c0 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62   Setting a new b
197d0 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61  usy handler clea
197e0 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f  rs any.** previo
197f0 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72  usly set handler
19800 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20  .)^  ^Note that 
19810 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
19820 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
19830 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65  .** will also se
19840 74 20 6f 72 20 63 6c 65 61 72 20 74 68 65 20 62  t or clear the b
19850 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a  usy handler..**.
19860 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c  ** The busy call
19870 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20  back should not 
19880 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73  take any actions
19890 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68   which modify th
198a0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
198b0 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
198c0 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68  voked the busy h
198d0 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20 73 75 63  andler.  Any suc
198e0 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73  h actions.** res
198f0 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  ult in undefined
19900 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a   behavior..** .*
19910 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72  * A busy handler
19920 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20   must not close 
19930 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
19940 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70  nection.** or [p
19950 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
19960 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  t] that invoked 
19970 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
19980 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
19990 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71  _busy_handler(sq
199a0 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76  lite3*, int(*)(v
199b0 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a  oid*,int), void*
199c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
199d0 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 20 54  EF: Set A Busy T
199e0 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  imeout.**.** ^Th
199f0 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20  is routine sets 
19a00 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  a [sqlite3_busy_
19a10 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68  handler | busy h
19a20 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65  andler] that sle
19a30 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65  eps.** for a spe
19a40 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66  cified amount of
19a50 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62   time when a tab
19a60 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e  le is locked.  ^
19a70 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77  The handler.** w
19a80 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70  ill sleep multip
19a90 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61  le times until a
19aa0 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c  t least "ms" mil
19ab0 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
19ac0 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63  eping.** have ac
19ad0 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74  cumulated.  ^Aft
19ae0 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22  er at least "ms"
19af0 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
19b00 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68   sleeping,.** th
19b10 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e  e handler return
19b20 73 20 30 20 77 68 69 63 68 20 63 61 75 73 65 73  s 0 which causes
19b30 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
19b40 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b  ] to return.** [
19b50 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20  SQLITE_BUSY] or 
19b60 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
19b70 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43  OCKED]..**.** ^C
19b80 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74  alling this rout
19b90 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75  ine with an argu
19ba0 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f  ment less than o
19bb0 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a  r equal to zero.
19bc0 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c  ** turns off all
19bd0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a   busy handlers..
19be0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61  **.** ^(There ca
19bf0 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67  n only be a sing
19c00 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
19c10 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
19c20 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
19c30 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e  nnection] any an
19c40 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20  y given moment. 
19c50 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79   If another busy
19c60 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20   handler.** was 
19c70 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20  defined  (using 
19c80 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
19c90 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20  ndler()]) prior 
19ca0 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68  to calling.** th
19cb0 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74  is routine, that
19cc0 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64   other busy hand
19cd0 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29  ler is cleared.)
19ce0 5e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ^.*/.int sqlite3
19cf0 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71  _busy_timeout(sq
19d00 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b  lite3*, int ms);
19d10 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
19d20 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f  : Convenience Ro
19d30 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69  utines For Runni
19d40 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a  ng Queries.**.**
19d50 20 54 68 69 73 20 69 73 20 61 20 6c 65 67 61 63   This is a legac
19d60 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  y interface that
19d70 20 69 73 20 70 72 65 73 65 72 76 65 64 20 66 6f   is preserved fo
19d80 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  r backwards comp
19d90 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73  atibility..** Us
19da0 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66  e of this interf
19db0 61 63 65 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d  ace is not recom
19dc0 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65  mended..**.** De
19dd0 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72  finition: A <b>r
19de0 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20  esult table</b> 
19df0 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73  is memory data s
19e00 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65 64  tructure created
19e10 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   by the.** [sqli
19e20 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
19e30 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72   interface.  A r
19e40 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f  esult table reco
19e50 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c  rds the.** compl
19e60 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c 74  ete query result
19e70 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f  s from one or mo
19e80 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a  re queries..**.*
19e90 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63  * The table conc
19ea0 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e  eptually has a n
19eb0 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e  umber of rows an
19ec0 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a  d columns.  But.
19ed0 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73  ** these numbers
19ee0 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66   are not part of
19ef0 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
19f00 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65  e itself.  These
19f10 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20  .** numbers are 
19f20 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 74  obtained separat
19f30 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74  ely.  Let N be t
19f40 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
19f50 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68  s.** and M be th
19f60 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
19f70 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73  mns..**.** A res
19f80 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20  ult table is an 
19f90 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
19fa0 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  s to zero-termin
19fb0 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
19fc0 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  gs..** There are
19fd0 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74   (N+1)*M element
19fe0 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20  s in the array. 
19ff0 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69   The first M poi
1a000 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74  nters point.** t
1a010 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  o zero-terminate
1a020 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 20  d strings that  
1a030 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65  contain the name
1a040 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73  s of the columns
1a050 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69  ..** The remaini
1a060 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70  ng entries all p
1a070 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65  oint to query re
1a080 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c  sults.  NULL val
1a090 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e  ues result.** in
1a0a0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20   NULL pointers. 
1a0b0 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65   All other value
1a0c0 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20 55  s are in their U
1a0d0 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  TF-8 zero-termin
1a0e0 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72  ated.** string r
1a0f0 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73  epresentation as
1a100 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
1a110 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
1a120 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65  t()]..**.** A re
1a130 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74  sult table might
1a140 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20   consist of one 
1a150 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61  or more memory a
1a160 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49  llocations..** I
1a170 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
1a180 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 74   pass a result t
1a190 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f  able directly to
1a1a0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1a1b0 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  ]..** A result t
1a1c0 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64  able should be d
1a1d0 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67  eallocated using
1a1e0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74   [sqlite3_free_t
1a1f0 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  able()]..**.** ^
1a200 28 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f  (As an example o
1a210 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  f the result tab
1a220 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f  le format, suppo
1a230 73 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c  se a query resul
1a240 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f  t.** is as follo
1a250 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1a260 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1a270 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20        Name      
1a280 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20    | Age.**      
1a290 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d    --------------
1a2a0 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20  ---------.**    
1a2b0 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20      Alice       
1a2c0 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42  | 43.**        B
1a2d0 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a  ob         | 28.
1a2e0 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20  **        Cindy 
1a2f0 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f        | 21.** </
1a300 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1a310 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72  >.**.** There ar
1a320 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d  e two column (M=
1a330 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f  =2) and three ro
1a340 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73  ws (N==3).  Thus
1a350 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74   the.** result t
1a360 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69  able has 8 entri
1a370 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65  es.  Suppose the
1a380 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73   result table is
1a390 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e   stored.** in an
1a3a0 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52   array names azR
1a3b0 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52  esult.  Then azR
1a3c0 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73  esult holds this
1a3d0 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20   content:.**.** 
1a3e0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1a3f0 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  >.**        azRe
1a400 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e  sult&#91;0] = "N
1a410 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ame";.**        
1a420 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20  azResult&#91;1] 
1a430 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20  = "Age";.**     
1a440 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1a450 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a  2] = "Alice";.**
1a460 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1a470 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a  &#91;3] = "43";.
1a480 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1a490 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62  lt&#91;4] = "Bob
1a4a0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1a4b0 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22  esult&#91;5] = "
1a4c0 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  28";.**        a
1a4d0 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d  zResult&#91;6] =
1a4e0 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20   "Cindy";.**    
1a4f0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1a500 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c  ;7] = "21";.** <
1a510 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1a520 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1a530 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1a540 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61  e() function eva
1a550 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f  luates one or mo
1a560 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d  re.** semicolon-
1a570 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74  separated SQL st
1a580 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20  atements in the 
1a590 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1a5a0 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20  UTF-8.** string 
1a5b0 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d  of its 2nd param
1a5c0 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73  eter and returns
1a5d0 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   a result table 
1a5e0 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65  to the.** pointe
1a5f0 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33  r given in its 3
1a600 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  rd parameter..**
1a610 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61 70  .** After the ap
1a620 70 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69  plication has fi
1a630 6e 69 73 68 65 64 20 77 69 74 68 20 74 68 65 20  nished with the 
1a640 72 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69  result from sqli
1a650 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c  te3_get_table(),
1a660 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70 61 73 73  .** it must pass
1a670 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
1a680 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c  e pointer to sql
1a690 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
1a6a0 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a  ) in order to.**
1a6b0 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d   release the mem
1a6c0 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c  ory that was mal
1a6d0 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65 20  loced.  Because 
1a6e0 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a  of the way the.*
1a6f0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
1a700 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74  c()] happens wit
1a710 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  hin sqlite3_get_
1a720 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c  table(), the cal
1a730 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ling.** function
1a740 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f   must not try to
1a750 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66   call [sqlite3_f
1a760 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e  ree()] directly.
1a770 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74    Only.** [sqlit
1a780 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d  e3_free_table()]
1a790 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65   is able to rele
1a7a0 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70  ase the memory p
1a7b0 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65  roperly and safe
1a7c0 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ly..**.** The sq
1a7d0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1a7e0 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69  ) interface is i
1a7f0 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20  mplemented as a 
1a800 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a  wrapper around.*
1a810 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  * [sqlite3_exec(
1a820 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  )].  The sqlite3
1a830 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75  _get_table() rou
1a840 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61  tine does not ha
1a850 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20  ve access.** to 
1a860 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  any internal dat
1a870 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66 20  a structures of 
1a880 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73  SQLite.  It uses
1a890 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63   only the public
1a8a0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65  .** interface de
1a8b0 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20  fined here.  As 
1a8c0 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65  a consequence, e
1a8d0 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72  rrors that occur
1a8e0 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70   in the.** wrapp
1a8f0 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65  er layer outside
1a900 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   of the internal
1a910 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
1a920 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a  ] call are not.*
1a930 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73  * reflected in s
1a940 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
1a950 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
1a960 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  ode()] or.** [sq
1a970 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
1a980 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1a990 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c  get_table(.  sql
1a9a0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
1a9b0 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
1a9c0 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
1a9d0 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
1a9e0 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65    /* SQL to be e
1a9f0 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68  valuated */.  ch
1aa00 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c  ar ***pazResult,
1aa10 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f      /* Results o
1aa20 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20  f the query */. 
1aa30 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20   int *pnRow,    
1aa40 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
1aa50 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20   of result rows 
1aa60 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
1aa70 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c    int *pnColumn,
1aa80 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
1aa90 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75  r of result colu
1aaa0 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65  mns written here
1aab0 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45   */.  char **pzE
1aac0 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45  rrmsg       /* E
1aad0 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e  rror msg written
1aae0 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64   here */.);.void
1aaf0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
1ab00 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c  ble(char **resul
1ab10 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
1ab20 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53  REF: Formatted S
1ab30 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46  tring Printing F
1ab40 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  unctions.**.** T
1ab50 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
1ab60 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66  e work-alikes of
1ab70 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20   the "printf()" 
1ab80 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69  family of functi
1ab90 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ons.** from the 
1aba0 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
1abb0 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ry..**.** ^The s
1abc0 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
1abd0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70   and sqlite3_vmp
1abe0 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73  rintf() routines
1abf0 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20   write their.** 
1ac00 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d  results into mem
1ac10 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
1ac20 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
1ac30 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72  c()]..** The str
1ac40 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
1ac50 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69   these two routi
1ac60 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  nes should be.**
1ac70 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71   released by [sq
1ac80 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20  lite3_free()].  
1ac90 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72  ^Both routines r
1aca0 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20  eturn a.** NULL 
1acb0 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69  pointer if [sqli
1acc0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73  te3_malloc()] is
1acd0 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
1ace0 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65  ate enough.** me
1acf0 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
1ad00 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e   resulting strin
1ad10 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73  g..**.** ^(The s
1ad20 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1ad30 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d  ) routine is sim
1ad40 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74  ilar to "snprint
1ad50 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65  f()" from.** the
1ad60 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
1ad70 61 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74  ary.  The result
1ad80 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   is written into
1ad90 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73   the.** buffer s
1ada0 75 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73  upplied as the s
1adb0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1adc0 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69  whose size is gi
1add0 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69  ven by.** the fi
1ade0 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e  rst parameter. N
1adf0 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64  ote that the ord
1ae00 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72  er of the.** fir
1ae10 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72  st two parameter
1ae20 73 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72  s is reversed fr
1ae30 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e  om snprintf().)^
1ae40 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20    This is an.** 
1ae50 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64  historical accid
1ae60 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20  ent that cannot 
1ae70 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74  be fixed without
1ae80 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63   breaking.** bac
1ae90 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
1aea0 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c  lity.  ^(Note al
1aeb0 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f  so that sqlite3_
1aec0 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65  snprintf().** re
1aed0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
1aee0 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 6e  to its buffer in
1aef0 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d  stead of the num
1af00 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63  ber of.** charac
1af10 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72  ters actually wr
1af20 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62  itten into the b
1af30 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d  uffer.)^  We adm
1af40 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e  it that.** the n
1af50 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
1af60 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c  ers written woul
1af70 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66  d be a more usef
1af80 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c  ul return.** val
1af90 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74  ue but we cannot
1afa0 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c   change the impl
1afb0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71  ementation of sq
1afc0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1afd0 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20  .** now without 
1afe0 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69  breaking compati
1aff0 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41  bility..**.** ^A
1b000 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75  s long as the bu
1b010 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65  ffer size is gre
1b020 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20  ater than zero, 
1b030 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1b040 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73  ().** guarantees
1b050 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72   that the buffer
1b060 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d   is always zero-
1b070 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68  terminated.  ^Th
1b080 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d  e first.** param
1b090 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20  eter "n" is the 
1b0a0 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68  total size of th
1b0b0 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64  e buffer, includ
1b0c0 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a  ing space for.**
1b0d0 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
1b0e0 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f  ator.  So the lo
1b0f0 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61  ngest string tha
1b100 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74  t can be complet
1b110 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77  ely.** written w
1b120 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61  ill be n-1 chara
1b130 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  cters..**.** ^Th
1b140 65 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69  e sqlite3_vsnpri
1b150 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ntf() routine is
1b160 20 61 20 76 61 72 61 72 67 73 20 76 65 72 73 69   a varargs versi
1b170 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e  on of sqlite3_sn
1b180 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20  printf()..**.** 
1b190 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
1b1a0 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d  ll implement som
1b1b0 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72  e additional for
1b1c0 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f  matting.** optio
1b1d0 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 65 66  ns that are usef
1b1e0 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74  ul for construct
1b1f0 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ing SQL statemen
1b200 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68  ts..** All of th
1b210 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29  e usual printf()
1b220 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
1b230 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61  ons apply.  In a
1b240 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a  ddition, there.*
1b250 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c 20 22  * is are "%q", "
1b260 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70  %Q", and "%z" op
1b270 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  tions..**.** ^(T
1b280 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72  he %q option wor
1b290 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68  ks like %s in th
1b2a0 61 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65  at it substitute
1b2b0 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74  s a nul-terminat
1b2c0 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f  ed.** string fro
1b2d0 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c  m the argument l
1b2e0 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73  ist.  But %q als
1b2f0 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20  o doubles every 
1b300 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a  '\'' character..
1b310 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65  ** %q is designe
1b320 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65  d for use inside
1b330 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
1b340 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e  l.)^  By doublin
1b350 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63  g each '\''.** c
1b360 68 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61  haracter it esca
1b370 70 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74  pes that charact
1b380 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74  er and allows it
1b390 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20   to be inserted 
1b3a0 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69  into.** the stri
1b3b0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78  ng..**.** For ex
1b3c0 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68  ample, assume th
1b3d0 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c  e string variabl
1b3e0 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73  e zText contains
1b3f0 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73   text as follows
1b400 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1b410 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
1b420 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27  ar *zText = "It'
1b430 73 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b  s a happy day!";
1b440 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1b450 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e  kquote>.**.** On
1b460 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74  e can use this t
1b470 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74  ext in an SQL st
1b480 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f  atement as follo
1b490 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1b4a0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1b4b0 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c  char *zSQL = sql
1b4c0 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e  ite3_mprintf("IN
1b4d0 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20  SERT INTO table 
1b4e0 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a  VALUES('%q')", z
1b4f0 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
1b500 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
1b510 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
1b520 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
1b530 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
1b540 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1b550 20 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20   Because the %q 
1b560 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73  format string is
1b570 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20   used, the '\'' 
1b580 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65  character in zTe
1b590 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64  xt.** is escaped
1b5a0 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e   and the SQL gen
1b5b0 65 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c  erated is as fol
1b5c0 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
1b5d0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1b5e0 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61    INSERT INTO ta
1b5f0 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27  ble1 VALUES('It'
1b600 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
1b610 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ).** </pre></blo
1b620 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
1b630 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20  his is correct. 
1b640 20 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20   Had we used %s 
1b650 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74  instead of %q, t
1b660 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c  he generated SQL
1b670 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c  .** would have l
1b680 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a  ooked like this:
1b690 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1b6a0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
1b6b0 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
1b6c0 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68  VALUES('It's a h
1b6d0 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20  appy day!');.** 
1b6e0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1b6f0 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73  te>.**.** This s
1b700 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73  econd example is
1b710 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65   an SQL syntax e
1b720 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65  rror.  As a gene
1b730 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f  ral rule you sho
1b740 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73  uld.** always us
1b750 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20  e %q instead of 
1b760 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  %s when insertin
1b770 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74  g text into a st
1b780 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a  ring literal..**
1b790 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74  .** ^(The %Q opt
1b7a0 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25  ion works like %
1b7b0 71 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f  q except it also
1b7c0 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f   adds single quo
1b7d0 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68  tes around.** th
1b7e0 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65  e outside of the
1b7f0 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20   total string.  
1b800 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66  Additionally, if
1b810 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
1b820 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e  n the.** argumen
1b830 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c  t list is a NULL
1b840 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62   pointer, %Q sub
1b850 73 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78  stitutes the tex
1b860 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75  t "NULL" (withou
1b870 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74  t.** single quot
1b880 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20  es).)^  So, for 
1b890 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75  example, one cou
1b8a0 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ld say:.**.** <b
1b8b0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1b8c0 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d  **  char *zSQL =
1b8d0 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
1b8e0 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61  ("INSERT INTO ta
1b8f0 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c  ble VALUES(%Q)",
1b900 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c   zText);.**  sql
1b910 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53  ite3_exec(db, zS
1b920 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a  QL, 0, 0, 0);.**
1b930 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a    sqlite3_free(z
1b940 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  SQL);.** </pre><
1b950 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1b960 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76  ** The code abov
1b970 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20  e will render a 
1b980 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74  correct SQL stat
1b990 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51  ement in the zSQ
1b9a0 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76  L.** variable ev
1b9b0 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20  en if the zText 
1b9c0 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55  variable is a NU
1b9d0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
1b9e0 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72  * ^(The "%z" for
1b9f0 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77  matting option w
1ba00 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62  orks like "%s" b
1ba10 75 74 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61  ut with the.** a
1ba20 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74  ddition that aft
1ba30 65 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61  er the string ha
1ba40 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20  s been read and 
1ba50 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74  copied into.** t
1ba60 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69  he result, [sqli
1ba70 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63  te3_free()] is c
1ba80 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70  alled on the inp
1ba90 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a  ut string.)^.*/.
1baa0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70  char *sqlite3_mp
1bab0 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72  rintf(const char
1bac0 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71  *,...);.char *sq
1bad0 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63  lite3_vmprintf(c
1bae0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c  onst char*, va_l
1baf0 69 73 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69  ist);.char *sqli
1bb00 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74  te3_snprintf(int
1bb10 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61  ,char*,const cha
1bb20 72 2a 2c 20 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a  r*, ...);.char *
1bb30 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74  sqlite3_vsnprint
1bb40 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73  f(int,char*,cons
1bb50 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74  t char*, va_list
1bb60 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1bb70 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
1bb80 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a  ation Subsystem.
1bb90 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  **.** The SQLite
1bba0 20 63 6f 72 65 20 75 73 65 73 20 74 68 65 73 65   core uses these
1bbb0 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20   three routines 
1bbc0 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f  for all of its o
1bbd0 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d  wn.** internal m
1bbe0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1bbf0 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69   needs. "Core" i
1bc00 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73  n the previous s
1bc10 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20  entence.** does 
1bc20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72  not include oper
1bc30 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65  ating-system spe
1bc40 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d  cific VFS implem
1bc50 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a  entation.  The.*
1bc60 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73  * Windows VFS us
1bc70 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63  es native malloc
1bc80 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f  () and free() fo
1bc90 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e  r some operation
1bca0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
1bcb0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72  lite3_malloc() r
1bcc0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
1bcd0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c   pointer to a bl
1bce0 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79  ock.** of memory
1bcf0 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
1bd00 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65  s in length, whe
1bd10 72 65 20 4e 20 69 73 20 74 68 65 20 70 61 72 61  re N is the para
1bd20 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71  meter..** ^If sq
1bd30 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69  lite3_malloc() i
1bd40 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61  s unable to obta
1bd50 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66 72  in sufficient fr
1bd60 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74  ee.** memory, it
1bd70 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
1bd80 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68  pointer.  ^If th
1bd90 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f  e parameter N to
1bda0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
1bdb0 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20  oc() is zero or 
1bdc0 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 73 71  negative then sq
1bdd0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72  lite3_malloc() r
1bde0 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c  eturns.** a NULL
1bdf0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
1be00 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33  ^Calling sqlite3
1be10 5f 66 72 65 65 28 29 20 77 69 74 68 20 61 20 70  _free() with a p
1be20 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c  ointer previousl
1be30 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  y returned.** by
1be40 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1be50 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61  ) or sqlite3_rea
1be60 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20  lloc() releases 
1be70 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a  that memory so.*
1be80 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 20  * that it might 
1be90 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54 68 65  be reused.  ^The
1bea0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
1beb0 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20  routine is.** a 
1bec0 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c  no-op if is call
1bed0 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70  ed with a NULL p
1bee0 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67  ointer.  Passing
1bef0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
1bf00 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72  ** to sqlite3_fr
1bf10 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73  ee() is harmless
1bf20 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67 20 66  .  After being f
1bf30 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20  reed, memory.** 
1bf40 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62  should neither b
1bf50 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74  e read nor writt
1bf60 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e  en.  Even readin
1bf70 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65  g previously fre
1bf80 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67  ed.** memory mig
1bf90 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73  ht result in a s
1bfa0 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c  egmentation faul
1bfb0 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72  t or other sever
1bfc0 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f  e error..** Memo
1bfd0 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61  ry corruption, a
1bfe0 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61   segmentation fa
1bff0 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65  ult, or other se
1c000 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69  vere error.** mi
1c010 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 73 71  ght result if sq
1c020 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20  lite3_free() is 
1c030 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f  called with a no
1c040 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  n-NULL pointer t
1c050 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f  hat.** was not o
1c060 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c  btained from sql
1c070 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72  ite3_malloc() or
1c080 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1c090 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ()..**.** ^(The 
1c0a0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1c0b0 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ) interface atte
1c0c0 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61  mpts to resize a
1c0d0 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79  .** prior memory
1c0e0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62   allocation to b
1c0f0 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  e at least N byt
1c100 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  es, where N is t
1c110 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
1c120 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6d 65 6d  ameter.  The mem
1c130 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
1c140 6f 20 62 65 20 72 65 73 69 7a 65 64 20 69 73 20  o be resized is 
1c150 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72  the first.** par
1c160 61 6d 65 74 65 72 2e 29 5e 20 5e 20 49 66 20 74  ameter.)^ ^ If t
1c170 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
1c180 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
1c190 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20  alloc().** is a 
1c1a0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
1c1b0 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72 20 69  n its behavior i
1c1c0 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63  s identical to c
1c1d0 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  alling.** sqlite
1c1e0 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72  3_malloc(N) wher
1c1f0 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e  e N is the secon
1c200 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
1c210 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1c220 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 65 63  ..** ^If the sec
1c230 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
1c240 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1c250 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a  () is zero or.**
1c260 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 74   negative then t
1c270 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 65  he behavior is e
1c280 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20  xactly the same 
1c290 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71  as calling.** sq
1c2a0 6c 69 74 65 33 5f 66 72 65 65 28 50 29 20 77 68  lite3_free(P) wh
1c2b0 65 72 65 20 50 20 69 73 20 74 68 65 20 66 69 72  ere P is the fir
1c2c0 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
1c2d0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1c2e0 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72  )..** ^sqlite3_r
1c2f0 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73  ealloc() returns
1c300 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
1c310 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1c320 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74  n.** of at least
1c330 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65   N bytes in size
1c340 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 66   or NULL if suff
1c350 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73  icient memory is
1c360 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a   unavailable..**
1c370 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73 69   ^If M is the si
1c380 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20  ze of the prior 
1c390 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e  allocation, then
1c3a0 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a   min(N,M) bytes.
1c3b0 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20  ** of the prior 
1c3c0 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63  allocation are c
1c3d0 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62  opied into the b
1c3e0 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66  eginning of buff
1c3f0 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  er returned.** b
1c400 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  y sqlite3_reallo
1c410 63 28 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f  c() and the prio
1c420 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20  r allocation is 
1c430 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71  freed..** ^If sq
1c440 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
1c450 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68  returns NULL, th
1c460 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  en the prior all
1c470 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f  ocation.** is no
1c480 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  t freed..**.** ^
1c490 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72  The memory retur
1c4a0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  ned by sqlite3_m
1c4b0 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69  alloc() and sqli
1c4c0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a  te3_realloc().**
1c4d0 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e   is always align
1c4e0 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61  ed to at least a
1c4f0 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72  n 8 byte boundar
1c500 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20  y, or to a.** 4 
1c510 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66  byte boundary if
1c520 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42   the [SQLITE_4_B
1c530 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c  YTE_ALIGNED_MALL
1c540 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  OC] compile-time
1c550 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  .** option is us
1c560 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c  ed..**.** In SQL
1c570 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
1c580 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20  0 and 3.5.1, it 
1c590 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  was possible to 
1c5a0 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51  define.** the SQ
1c5b0 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59  LITE_OMIT_MEMORY
1c5c0 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63  _ALLOCATION whic
1c5d0 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68  h would cause th
1c5e0 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d  e built-in.** im
1c5f0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
1c600 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74  these routines t
1c610 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54  o be omitted.  T
1c620 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a  hat capability.*
1c630 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70  * is no longer p
1c640 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62  rovided.  Only b
1c650 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
1c660 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65  llocators can be
1c670 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69   used..**.** Pri
1c680 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72  or to SQLite ver
1c690 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65  sion 3.7.10, the
1c6a0 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65   Windows OS inte
1c6b0 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c  rface layer call
1c6c0 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d  ed.** the system
1c6d0 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72   malloc() and fr
1c6e0 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68  ee() directly wh
1c6f0 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a  en converting.**
1c700 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65   filenames betwe
1c710 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63  en the UTF-8 enc
1c720 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51  oding used by SQ
1c730 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74  Lite.** and what
1c740 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e  ever filename en
1c750 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62  coding is used b
1c760 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  y the particular
1c770 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74   Windows.** inst
1c780 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72  allation.  Memor
1c790 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
1c7a0 6f 72 73 20 77 65 72 65 20 64 65 74 65 63 74 65  ors were detecte
1c7b0 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 77  d, but.** they w
1c7c0 65 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 63  ere reported bac
1c7d0 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e  k as [SQLITE_CAN
1c7e0 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51  TOPEN] or.** [SQ
1c7f0 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68  LITE_IOERR] rath
1c800 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
1c810 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  NOMEM]..**.** Th
1c820 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65  e pointer argume
1c830 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  nts to [sqlite3_
1c840 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  free()] and [sql
1c850 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a  ite3_realloc()].
1c860 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65  ** must be eithe
1c870 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70  r NULL or else p
1c880 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64  ointers obtained
1c890 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a   from a prior.**
1c8a0 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
1c8b0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1c8c0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
1c8d0 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61  alloc()] that ha
1c8e0 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65  ve.** not yet be
1c8f0 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a  en released..**.
1c900 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
1c910 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64  on must not read
1c920 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61   or write any pa
1c930 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b  rt of.** a block
1c940 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72   of memory after
1c950 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c   it has been rel
1c960 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b  eased using.** [
1c970 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
1c980 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
1c990 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20  loc()]..*/.void 
1c9a0 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  *sqlite3_malloc(
1c9b0 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69  int);.void *sqli
1c9c0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64  te3_realloc(void
1c9d0 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
1c9e0 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a  lite3_free(void*
1c9f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1ca00 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
1ca10 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a  ator Statistics.
1ca20 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f  **.** SQLite pro
1ca30 76 69 64 65 73 20 74 68 65 73 65 20 74 77 6f 20  vides these two 
1ca40 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20 72  interfaces for r
1ca50 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20  eporting on the 
1ca60 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65  status.** of the
1ca70 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1ca80 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72  ()], [sqlite3_fr
1ca90 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ee()], and [sqli
1caa0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a  te3_realloc()].*
1cab0 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63  * routines, whic
1cac0 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74  h form the built
1cad0 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  -in memory alloc
1cae0 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e  ation subsystem.
1caf0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  .**.** ^The [sql
1cb00 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
1cb10 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ()] routine retu
1cb20 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
1cb30 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65  f bytes.** of me
1cb40 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f  mory currently o
1cb50 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c  utstanding (mall
1cb60 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65  oced but not fre
1cb70 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ed)..** ^The [sq
1cb80 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
1cb90 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e  hwater()] routin
1cba0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61  e returns the ma
1cbb0 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f  ximum.** value o
1cbc0 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  f [sqlite3_memor
1cbd0 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20  y_used()] since 
1cbe0 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d  the high-water m
1cbf0 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20  ark.** was last 
1cc00 72 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c  reset.  ^The val
1cc10 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ues returned by 
1cc20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1cc30 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b  used()] and.** [
1cc40 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
1cc50 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c  ighwater()] incl
1cc60 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64  ude any overhead
1cc70 0a 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c  .** added by SQL
1cc80 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65  ite in its imple
1cc90 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71  mentation of [sq
1cca0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c  lite3_malloc()],
1ccb0 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72  .** but not over
1ccc0 68 65 61 64 20 61 64 64 65 64 20 62 79 20 74 68  head added by th
1ccd0 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67  e any underlying
1cce0 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a   system library.
1ccf0 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  ** routines that
1cd00 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1cd10 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a  ()] may call..**
1cd20 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  .** ^The memory 
1cd30 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20  high-water mark 
1cd40 69 73 20 72 65 73 65 74 20 74 6f 20 74 68 65 20  is reset to the 
1cd50 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66  current value of
1cd60 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  .** [sqlite3_mem
1cd70 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61  ory_used()] if a
1cd80 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70  nd only if the p
1cd90 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b  arameter to.** [
1cda0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
1cdb0 69 67 68 77 61 74 65 72 28 29 5d 20 69 73 20 74  ighwater()] is t
1cdc0 72 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65  rue.  ^The value
1cdd0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
1cde0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1cdf0 68 69 67 68 77 61 74 65 72 28 31 29 5d 20 69 73  highwater(1)] is
1ce00 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20   the high-water 
1ce10 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f  mark.** prior to
1ce20 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73   the reset..*/.s
1ce30 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
1ce40 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
1ce50 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f  (void);.sqlite3_
1ce60 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65  int64 sqlite3_me
1ce70 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69  mory_highwater(i
1ce80 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a  nt resetFlag);..
1ce90 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1cea0 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75  Pseudo-Random Nu
1ceb0 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a  mber Generator.*
1cec0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74  *.** SQLite cont
1ced0 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c  ains a high-qual
1cee0 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f  ity pseudo-rando
1cef0 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74  m number generat
1cf00 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 74  or (PRNG) used t
1cf10 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64  o.** select rand
1cf20 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49  om [ROWID | ROWI
1cf30 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69  Ds] when inserti
1cf40 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69  ng new records i
1cf50 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74  nto a table that
1cf60 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73  .** already uses
1cf70 20 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73   the largest pos
1cf80 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20  sible [ROWID].  
1cf90 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f  The PRNG is also
1cfa0 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65   used for.** the
1cfb0 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d   build-in random
1cfc0 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f  () and randomblo
1cfd0 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  b() SQL function
1cfe0 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 61  s.  This interfa
1cff0 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70  ce allows.** app
1d000 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63  lications to acc
1d010 65 73 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e  ess the same PRN
1d020 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70  G for other purp
1d030 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63  oses..**.** ^A c
1d040 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74  all to this rout
1d050 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74  ine stores N byt
1d060 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73  es of randomness
1d070 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a   into buffer P..
1d080 2a 2a 20 5e 49 66 20 4e 20 69 73 20 6c 65 73 73  ** ^If N is less
1d090 20 74 68 61 6e 20 6f 6e 65 2c 20 74 68 65 6e 20   than one, then 
1d0a0 50 20 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20  P can be a NULL 
1d0b0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
1d0c0 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  If this routine 
1d0d0 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 70 72 65  has not been pre
1d0e0 76 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f  viously called o
1d0f0 72 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75  r if the previou
1d100 73 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20  s.** call had N 
1d110 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 2c 20 74  less than one, t
1d120 68 65 6e 20 74 68 65 20 50 52 4e 47 20 69 73 20  hen the PRNG is 
1d130 73 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e  seeded using ran
1d140 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6f 62 74 61 69  domness.** obtai
1d150 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 78 52 61  ned from the xRa
1d160 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20  ndomness method 
1d170 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  of the default [
1d180 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
1d190 65 63 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ect..** ^If the 
1d1a0 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
1d1b0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61   this routine ha
1d1c0 64 20 61 6e 20 4e 20 6f 66 20 31 20 6f 72 20 6d  d an N of 1 or m
1d1d0 6f 72 65 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ore then.** the 
1d1e0 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73  pseudo-randomnes
1d1f0 73 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a  s is generated.*
1d200 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64  * internally and
1d210 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73   without recours
1d220 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  e to the [sqlite
1d230 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65  3_vfs] xRandomne
1d240 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f  ss.** method..*/
1d250 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61  .void sqlite3_ra
1d260 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20  ndomness(int N, 
1d270 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a  void *P);../*.**
1d280 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
1d290 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a  le-Time Authoriz
1d2a0 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a  ation Callbacks.
1d2b0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
1d2c0 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 6e  ine registers an
1d2d0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1d2e0 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74  back with a part
1d2f0 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62  icular.** [datab
1d300 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c  ase connection],
1d310 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65   supplied in the
1d320 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
1d330 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69  .** ^The authori
1d340 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1d350 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73  invoked as SQL s
1d360 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65  tatements are be
1d370 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  ing compiled.** 
1d380 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  by [sqlite3_prep
1d390 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61  are()] or its va
1d3a0 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f  riants [sqlite3_
1d3b0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a  prepare_v2()],.*
1d3c0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
1d3d0 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c  re16()] and [sql
1d3e0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1d3f0 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f  2()].  ^At vario
1d400 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72  us.** points dur
1d410 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74  ing the compilat
1d420 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20  ion process, as 
1d430 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63  logic is being c
1d440 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72  reated.** to per
1d450 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74  form various act
1d460 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72  ions, the author
1d470 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
1d480 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73   invoked to.** s
1d490 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69  ee if those acti
1d4a0 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e  ons are allowed.
1d4b0 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65    ^The authorize
1d4c0 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c  r callback shoul
1d4d0 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  d.** return [SQL
1d4e0 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77  ITE_OK] to allow
1d4f0 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51   the action, [SQ
1d500 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20  LITE_IGNORE] to 
1d510 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20  disallow the.** 
1d520 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20  specific action 
1d530 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51  but allow the SQ
1d540 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63  L statement to c
1d550 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a  ontinue to be.**
1d560 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53   compiled, or [S
1d570 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63  QLITE_DENY] to c
1d580 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20  ause the entire 
1d590 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  SQL statement to
1d5a0 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20   be.** rejected 
1d5b0 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20  with an error.  
1d5c0 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ^If the authoriz
1d5d0 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  er callback retu
1d5e0 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65  rns.** any value
1d5f0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
1d600 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51  ITE_IGNORE], [SQ
1d610 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51  LITE_OK], or [SQ
1d620 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68  LITE_DENY].** th
1d630 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  en the [sqlite3_
1d640 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
1d650 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c   equivalent call
1d660 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a   that triggered.
1d670 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ** the authorize
1d680 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68  r will fail with
1d690 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
1d6a0 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  e..**.** When th
1d6b0 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
1d6c0 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ns [SQLITE_OK], 
1d6d0 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f  that means the o
1d6e0 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75  peration.** requ
1d6f0 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57  ested is ok.  ^W
1d700 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
1d710 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
1d720 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b  _DENY], the.** [
1d730 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1d740 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
1d750 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ent call that tr
1d760 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61  iggered the.** a
1d770 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66  uthorizer will f
1d780 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ail with an erro
1d790 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69  r message explai
1d7a0 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63  ning that.** acc
1d7b0 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a  ess is denied. .
1d7c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
1d7d0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1d7e0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1d7f0 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20  lback is a copy 
1d800 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  of the third.** 
1d810 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1d820 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
1d830 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66  horizer() interf
1d840 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ace. ^The second
1d850 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f   parameter.** to
1d860 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
1d870 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c   an integer [SQL
1d880 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f  ITE_COPY | actio
1d890 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65  n code] that spe
1d8a0 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61  cifies.** the pa
1d8b0 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20  rticular action 
1d8c0 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
1d8d0 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74 68 72  . ^The third thr
1d8e0 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d  ough sixth param
1d8f0 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20  eters.** to the 
1d900 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72  callback are zer
1d910 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
1d920 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69  ings that contai
1d930 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  n additional.** 
1d940 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68  details about th
1d950 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  e action to be a
1d960 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a  uthorized..**.**
1d970 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20   ^If the action 
1d980 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
1d990 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65  READ].** and the
1d9a0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1d9b0 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  s [SQLITE_IGNORE
1d9c0 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70  ] then the.** [p
1d9d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1d9e0 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  t] statement is 
1d9f0 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73  constructed to s
1da00 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e  ubstitute.** a N
1da10 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61  ULL value in pla
1da20 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  ce of the table 
1da30 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c  column that woul
1da40 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72  d have.** been r
1da50 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f  ead if [SQLITE_O
1da60 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75  K] had been retu
1da70 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49  rned.  The [SQLI
1da80 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65  TE_IGNORE].** re
1da90 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64  turn can be used
1daa0 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72   to deny an untr
1dab0 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73  usted user acces
1dac0 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a  s to individual.
1dad0 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20  ** columns of a 
1dae0 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68  table..** ^If th
1daf0 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73  e action code is
1db00 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d   [SQLITE_DELETE]
1db10 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63   and the callbac
1db20 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51  k returns.** [SQ
1db30 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65  LITE_IGNORE] the
1db40 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f  n the [DELETE] o
1db50 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64  peration proceed
1db60 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72  s but the.** [tr
1db70 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74  uncate optimizat
1db80 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64  ion] is disabled
1db90 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72   and all rows ar
1dba0 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69  e deleted indivi
1dbb0 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e  dually..**.** An
1dbc0 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75   authorizer is u
1dbd0 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  sed when [sqlite
1dbe0 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
1dbf0 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74  aring].** SQL st
1dc00 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e  atements from an
1dc10 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63   untrusted sourc
1dc20 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61  e, to ensure tha
1dc30 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
1dc40 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74  ents.** do not t
1dc50 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74  ry to access dat
1dc60 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61  a they are not a
1dc70 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f  llowed to see, o
1dc80 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  r that they do n
1dc90 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65  ot.** try to exe
1dca0 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73  cute malicious s
1dcb0 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64  tatements that d
1dcc0 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61  amage the databa
1dcd0 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d  se.  For.** exam
1dce0 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  ple, an applicat
1dcf0 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20  ion may allow a 
1dd00 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72  user to enter ar
1dd10 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71  bitrary.** SQL q
1dd20 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75  ueries for evalu
1dd30 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62  ation by a datab
1dd40 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70  ase.  But the ap
1dd50 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a  plication does.*
1dd60 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75  * not want the u
1dd70 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74  ser to be able t
1dd80 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79  o make arbitrary
1dd90 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a   changes to the.
1dda0 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e  ** database.  An
1ddb0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c   authorizer coul
1ddc0 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e  d then be put in
1ddd0 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65   place while the
1dde0 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64  .** user-entered
1ddf0 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73   SQL is being [s
1de00 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
1de10 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a   prepared] that.
1de20 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65  ** disallows eve
1de30 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b  rything except [
1de40 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
1de50 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63  ts..**.** Applic
1de60 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64  ations that need
1de70 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20   to process SQL 
1de80 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73  from untrusted s
1de90 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20  ources.** might 
1dea0 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f  also consider lo
1deb0 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20  wering resource 
1dec0 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71  limits using [sq
1ded0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a  lite3_limit()].*
1dee0 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64  * and limiting d
1def0 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69  atabase size usi
1df00 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65  ng the [max_page
1df10 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d  _count] [PRAGMA]
1df20 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20  .** in addition 
1df30 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68  to using an auth
1df40 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  orizer..**.** ^(
1df50 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75  Only a single au
1df60 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20  thorizer can be 
1df70 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61  in place on a da
1df80 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1df90 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20  n.** at a time. 
1dfa0 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71   Each call to sq
1dfb0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1dfc0 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74  izer overrides t
1dfd0 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63  he.** previous c
1dfe0 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65  all.)^  ^Disable
1dff0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1e000 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20  by installing a 
1e010 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  NULL callback..*
1e020 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
1e030 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
1e040 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54  default..**.** T
1e050 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1e060 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20  llback must not 
1e070 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
1e080 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
1e090 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1e0a0 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
1e0b0 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69  oked the authori
1e0c0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  zer callback..**
1e0d0 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
1e0e0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1e0f0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
1e100 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
1e110 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
1e120 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
1e130 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
1e140 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
1e150 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
1e160 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c  **.** ^When [sql
1e170 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1e180 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72  )] is used to pr
1e190 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e  epare a statemen
1e1a0 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d  t, the.** statem
1e1b0 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d  ent might be re-
1e1c0 70 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20  prepared during 
1e1d0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1e1e0 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63   due to a .** sc
1e1f0 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65  hema change.  He
1e200 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61  nce, the applica
1e210 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75  tion should ensu
1e220 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63  re that the.** c
1e230 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65  orrect authorize
1e240 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69  r callback remai
1e250 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69  ns in place duri
1e260 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ng the [sqlite3_
1e270 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  step()]..**.** ^
1e280 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75  Note that the au
1e290 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1e2a0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c  k is invoked onl
1e2b0 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c  y during.** [sql
1e2c0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
1e2d0 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e  or its variants.
1e2e0 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20    Authorization 
1e2f0 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72  is not.** perfor
1e300 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65  med during state
1e310 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  ment evaluation 
1e320 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  in [sqlite3_step
1e330 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61  ()], unless.** a
1e340 73 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20  s stated in the 
1e350 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61  previous paragra
1e360 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ph, sqlite3_step
1e370 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71  () invokes.** sq
1e380 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1e390 28 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20  () to reprepare 
1e3a0 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  a statement afte
1e3b0 72 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67  r a schema chang
1e3c0 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
1e3d0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1e3e0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20  (.  sqlite3*,.  
1e3f0 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69  int (*xAuth)(voi
1e400 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  d*,int,const cha
1e410 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
1e420 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
1e430 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20   char*),.  void 
1e440 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f  *pUserData.);../
1e450 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
1e460 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e  uthorizer Return
1e470 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65   Codes.**.** The
1e480 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
1e490 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
1e4a0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66  rizer callback f
1e4b0 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a  unction] must.**
1e4c0 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b   return either [
1e4d0 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e  SQLITE_OK] or on
1e4e0 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63  e of these two c
1e4f0 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65  onstants in orde
1e500 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53  r.** to signal S
1e510 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72  QLite whether or
1e520 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20   not the action 
1e530 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53  is permitted.  S
1e540 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ee the.** [sqlit
1e550 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1e560 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64  r | authorizer d
1e570 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f  ocumentation] fo
1e580 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
1e590 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
1e5a0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c  ** Note that SQL
1e5b0 49 54 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c  ITE_IGNORE is al
1e5c0 73 6f 20 75 73 65 64 20 61 73 20 61 20 5b 53 51  so used as a [SQ
1e5d0 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20  LITE_ROLLBACK | 
1e5e0 72 65 74 75 72 6e 20 63 6f 64 65 5d 0a 2a 2a 20  return code].** 
1e5f0 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65  from the [sqlite
1e600 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69  3_vtab_on_confli
1e610 63 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ct()] interface.
1e620 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
1e630 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a  TE_DENY   1   /*
1e640 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73   Abort the SQL s
1e650 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e  tatement with an
1e660 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
1e670 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20  e SQLITE_IGNORE 
1e680 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c  2   /* Don't all
1e690 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64  ow access, but d
1e6a0 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e  on't generate an
1e6b0 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a   error */../*.**
1e6c0 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f   CAPI3REF: Autho
1e6d0 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64  rizer Action Cod
1e6e0 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  es.**.** The [sq
1e6f0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1e700 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  izer()] interfac
1e710 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  e registers a ca
1e720 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a  llback function.
1e730 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b  ** that is invok
1e740 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20  ed to authorize 
1e750 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74  certain SQL stat
1e760 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20  ement actions.  
1e770 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  The.** second pa
1e780 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
1e790 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
1e7a0 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20  teger code that 
1e7b0 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61  specifies.** wha
1e7c0 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e  t action is bein
1e7d0 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  g authorized.  T
1e7e0 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74  hese are the int
1e7f0 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65  eger action code
1e800 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75  s that.** the au
1e810 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1e820 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e  k may be passed.
1e830 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74  .**.** These act
1e840 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20  ion code values 
1e850 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e  signify what kin
1e860 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69  d of operation i
1e870 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f  s to be.** autho
1e880 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20  rized.  The 3rd 
1e890 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65  and 4th paramete
1e8a0 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  rs to the author
1e8b0 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62  ization.** callb
1e8c0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c  ack function wil
1e8d0 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20  l be parameters 
1e8e0 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e  or NULL dependin
1e8f0 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68  g on which of th
1e900 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20  ese.** codes is 
1e910 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  used as the seco
1e920 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e  nd parameter.  ^
1e930 28 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74  (The 5th paramet
1e940 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74  er to the.** aut
1e950 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1e960 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
1e970 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d  the database ("m
1e980 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a  ain", "temp",.**
1e990 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63   etc.) if applic
1e9a0 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74  able.)^  ^The 6t
1e9b0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
1e9c0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1e9d0 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65  llback.** is the
1e9e0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e   name of the inn
1e9f0 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20  er-most trigger 
1ea00 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20  or view that is 
1ea10 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a  responsible for.
1ea20 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74  ** the access at
1ea30 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66  tempt or NULL if
1ea40 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74   this access att
1ea50 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79  empt is directly
1ea60 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76   from.** top-lev
1ea70 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a  el SQL code..*/.
1ea80 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /***************
1ea90 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1eaa0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64  ************ 3rd
1eab0 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74   ************ 4t
1eac0 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23  h ***********/.#
1ead0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1eae0 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20  EATE_INDEX      
1eaf0 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78      1   /* Index
1eb00 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
1eb10 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1eb20 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1eb30 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20  ATE_TABLE       
1eb40 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20     2   /* Table 
1eb50 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1eb60 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1eb70 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1eb80 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20  TE_TEMP_INDEX   
1eb90 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e    3   /* Index N
1eba0 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
1ebb0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1ebc0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1ebd0 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20  E_TEMP_TABLE    
1ebe0 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   4   /* Table Na
1ebf0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1ec00 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1ec10 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1ec20 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20  _TEMP_TRIGGER   
1ec30 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  5   /* Trigger N
1ec40 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
1ec50 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1ec60 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1ec70 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36  TEMP_VIEW      6
1ec80 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
1ec90 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1eca0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1ecb0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1ecc0 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20  RIGGER        7 
1ecd0 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
1ece0 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
1ecf0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1ed00 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49  SQLITE_CREATE_VI
1ed10 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20  EW           8  
1ed20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
1ed30 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1ed40 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1ed50 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20  QLITE_DELETE    
1ed60 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20              9   
1ed70 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1ed80 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1ed90 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1eda0 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20  LITE_DROP_INDEX 
1edb0 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f            10   /
1edc0 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
1edd0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1ede0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1edf0 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20  ITE_DROP_TABLE  
1ee00 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a           11   /*
1ee10 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1ee20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1ee30 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1ee40 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44  TE_DROP_TEMP_IND
1ee50 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20  EX      12   /* 
1ee60 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
1ee70 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1ee80 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1ee90 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c  E_DROP_TEMP_TABL
1eea0 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54  E      13   /* T
1eeb0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1eec0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1eed0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1eee0 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47  _DROP_TEMP_TRIGG
1eef0 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72  ER    14   /* Tr
1ef00 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
1ef10 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1ef20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1ef30 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20  DROP_TEMP_VIEW  
1ef40 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65       15   /* Vie
1ef50 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
1ef60 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1ef70 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1ef80 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20  ROP_TRIGGER     
1ef90 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67      16   /* Trig
1efa0 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
1efb0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1efc0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1efd0 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20  OP_VIEW         
1efe0 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20     17   /* View 
1eff0 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
1f000 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1f010 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53  efine SQLITE_INS
1f020 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20  ERT             
1f030 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20    18   /* Table 
1f040 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1f050 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1f060 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47  fine SQLITE_PRAG
1f070 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MA              
1f080 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20   19   /* Pragma 
1f090 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67  Name     1st arg
1f0a0 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66   or NULL */.#def
1f0b0 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20  ine SQLITE_READ 
1f0c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1f0d0 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  20   /* Table Na
1f0e0 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e  me      Column N
1f0f0 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
1f100 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54  ne SQLITE_SELECT
1f110 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
1f120 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  1   /* NULL     
1f130 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1f140 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1f150 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43  e SQLITE_TRANSAC
1f160 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32  TION          22
1f170 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20     /* Operation 
1f180 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1f190 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1f1a0 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20   SQLITE_UPDATE  
1f1b0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20               23 
1f1c0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1f1d0 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65       Column Name
1f1e0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1f1f0 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20  SQLITE_ATTACH   
1f200 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20              24  
1f210 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20   /* Filename    
1f220 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1f230 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1f240 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20  QLITE_DETACH    
1f250 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20             25   
1f260 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
1f270 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1f280 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1f290 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45  LITE_ALTER_TABLE
1f2a0 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f            26   /
1f2b0 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20  * Database Name 
1f2c0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1f2d0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1f2e0 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20  ITE_REINDEX     
1f2f0 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a           27   /*
1f300 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
1f310 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1f320 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f330 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20  TE_ANALYZE      
1f340 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20          28   /* 
1f350 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1f360 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1f370 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f380 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20  E_CREATE_VTABLE 
1f390 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54         29   /* T
1f3a0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
1f3b0 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
1f3c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f3d0 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20  _DROP_VTABLE    
1f3e0 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61        30   /* Ta
1f3f0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f  ble Name      Mo
1f400 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f  dule Name     */
1f410 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f420 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20  FUNCTION        
1f430 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c       31   /* NUL
1f440 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 75 6e  L            Fun
1f450 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a  ction Name   */.
1f460 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
1f470 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20  AVEPOINT        
1f480 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72      32   /* Oper
1f490 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65  ation       Save
1f4a0 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23  point Name  */.#
1f4b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
1f4c0 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20  PY              
1f4d0 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f      0   /* No lo
1f4e0 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 23 64 65  nger used */.#de
1f4f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 43 55  fine SQLITE_RECU
1f500 52 53 49 56 45 20 20 20 20 20 20 20 20 20 20 20  RSIVE           
1f510 20 33 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   33   /* NULL   
1f520 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20           NULL   
1f530 20 20 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a           */../*.
1f540 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61  ** CAPI3REF: Tra
1f550 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69  cing And Profili
1f560 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a  ng Functions.**.
1f570 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1f580 73 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62  s register callb
1f590 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68  ack functions th
1f5a0 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 66  at can be used f
1f5b0 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e  or.** tracing an
1f5c0 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20  d profiling the 
1f5d0 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c  execution of SQL
1f5e0 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
1f5f0 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b  ** ^The callback
1f600 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74   function regist
1f610 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ered by sqlite3_
1f620 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b  trace() is invok
1f630 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73  ed at.** various
1f640 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53   times when an S
1f650 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  QL statement is 
1f660 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71  being run by [sq
1f670 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
1f680 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74  * ^The sqlite3_t
1f690 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20  race() callback 
1f6a0 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  is invoked with 
1f6b0 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e  a UTF-8 renderin
1f6c0 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20  g of the.** SQL 
1f6d0 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61  statement text a
1f6e0 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
1f6f0 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 65  first begins exe
1f700 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64  cuting..** ^(Add
1f710 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f  itional sqlite3_
1f720 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b  trace() callback
1f730 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a  s might occur.**
1f740 20 61 73 20 65 61 63 68 20 74 72 69 67 67 65 72   as each trigger
1f750 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73  ed subprogram is
1f760 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63   entered.  The c
1f770 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69  allbacks for tri
1f780 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e  ggers.** contain
1f790 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d   a UTF-8 SQL com
1f7a0 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69  ment that identi
1f7b0 66 69 65 73 20 74 68 65 20 74 72 69 67 67 65 72  fies the trigger
1f7c0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  .)^.**.** The [S
1f7d0 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 49 5a 45  QLITE_TRACE_SIZE
1f7e0 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d  _LIMIT] compile-
1f7f0 74 69 6d 65 20 6f 70 74 69 6f 6e 20 63 61 6e 20  time option can 
1f800 62 65 20 75 73 65 64 20 74 6f 20 6c 69 6d 69 74  be used to limit
1f810 0a 2a 2a 20 74 68 65 20 6c 65 6e 67 74 68 20 6f  .** the length o
1f820 66 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74  f [bound paramet
1f830 65 72 5d 20 65 78 70 61 6e 73 69 6f 6e 20 69 6e  er] expansion in
1f840 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66 20 73   the output of s
1f850 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 2e 0a  qlite3_trace()..
1f860 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62  **.** ^The callb
1f870 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
1f880 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74  istered by sqlit
1f890 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20  e3_profile() is 
1f8a0 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61  invoked.** as ea
1f8b0 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ch SQL statement
1f8c0 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65   finishes.  ^The
1f8d0 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63   profile callbac
1f8e0 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68  k contains.** th
1f8f0 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65  e original state
1f900 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e  ment text and an
1f910 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c   estimate of wal
1f920 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20  l-clock time.** 
1f930 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74  of how long that
1f940 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20   statement took 
1f950 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72  to run.  ^The pr
1f960 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  ofile callback.*
1f970 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69  * time is in uni
1f980 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64  ts of nanosecond
1f990 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20 63  s, however the c
1f9a0 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74  urrent implement
1f9b0 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79  ation.** is only
1f9c0 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c   capable of mill
1f9d0 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69  isecond resoluti
1f9e0 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65  on so the six le
1f9f0 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a  ast significant.
1fa00 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68 65  ** digits in the
1fa10 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e   time are meanin
1fa20 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20 76  gless.  Future v
1fa30 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
1fa40 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69  e.** might provi
1fa50 64 65 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c  de greater resol
1fa60 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f  ution on the pro
1fa70 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20  filer callback. 
1fa80 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   The.** sqlite3_
1fa90 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 69  profile() functi
1faa0 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  on is considered
1fab0 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e   experimental an
1fac0 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20  d is.** subject 
1fad0 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74  to change in fut
1fae0 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
1faf0 53 51 4c 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20  SQLite..*/.void 
1fb00 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73  *sqlite3_trace(s
1fb10 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78  qlite3*, void(*x
1fb20 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e  Trace)(void*,con
1fb30 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a  st char*), void*
1fb40 29 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49  );.SQLITE_EXPERI
1fb50 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c  MENTAL void *sql
1fb60 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c  ite3_profile(sql
1fb70 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a  ite3*,.   void(*
1fb80 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c  xProfile)(void*,
1fb90 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69  const char*,sqli
1fba0 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69  te3_uint64), voi
1fbb0 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
1fbc0 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67  3REF: Query Prog
1fbd0 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  ress Callbacks.*
1fbe0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1fbf0 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c  3_progress_handl
1fc00 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65  er(D,N,X,P) inte
1fc10 72 66 61 63 65 20 63 61 75 73 65 73 20 74 68 65  rface causes the
1fc20 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
1fc30 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e  ction X to be in
1fc40 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c  voked periodical
1fc50 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72  ly during long r
1fc60 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a  unning calls to.
1fc70 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ** [sqlite3_exec
1fc80 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
1fc90 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ep()] and [sqlit
1fca0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20  e3_get_table()] 
1fcb0 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  for.** database 
1fcc0 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41  connection D.  A
1fcd0 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f  n example use fo
1fce0 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66  r this.** interf
1fcf0 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61  ace is to keep a
1fd00 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75 72   GUI updated dur
1fd10 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65 72  ing a large quer
1fd20 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61  y..**.** ^The pa
1fd30 72 61 6d 65 74 65 72 20 50 20 69 73 20 70 61 73  rameter P is pas
1fd40 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74  sed through as t
1fd50 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65  he only paramete
1fd60 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c  r to the .** cal
1fd70 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58  lback function X
1fd80 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65  .  ^The paramete
1fd90 72 20 4e 20 69 73 20 74 68 65 20 61 70 70 72 6f  r N is the appro
1fda0 78 69 6d 61 74 65 20 6e 75 6d 62 65 72 20 6f 66  ximate number of
1fdb0 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61   .** [virtual ma
1fdc0 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74 69 6f  chine instructio
1fdd0 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65 76 61  ns] that are eva
1fde0 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e 20 73  luated between s
1fdf0 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76  uccessive.** inv
1fe00 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
1fe10 63 61 6c 6c 62 61 63 6b 20 58 2e 20 20 5e 49 66  callback X.  ^If
1fe20 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20   N is less than 
1fe30 6f 6e 65 20 74 68 65 6e 20 74 68 65 20 70 72 6f  one then the pro
1fe40 67 72 65 73 73 0a 2a 2a 20 68 61 6e 64 6c 65 72  gress.** handler
1fe50 20 69 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a   is disabled..**
1fe60 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67  .** ^Only a sing
1fe70 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  le progress hand
1fe80 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66 69 6e  ler may be defin
1fe90 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 70  ed at one time p
1fea0 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  er.** [database 
1feb0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74  connection]; set
1fec0 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 72  ting a new progr
1fed0 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6e 63  ess handler canc
1fee0 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f  els the.** old o
1fef0 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 61  ne.  ^Setting pa
1ff00 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 4c  rameter X to NUL
1ff10 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 70  L disables the p
1ff20 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e  rogress handler.
1ff30 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 73  .** ^The progres
1ff40 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61 6c 73  s handler is als
1ff50 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20 73 65  o disabled by se
1ff60 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c  tting N to a val
1ff70 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20  ue less.** than 
1ff80 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  1..**.** ^If the
1ff90 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
1ffa0 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
1ffb0 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69  ero, the operati
1ffc0 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75  on is.** interru
1ffd0 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 61 74  pted.  This feat
1ffe0 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ure can be used 
1fff0 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a  to implement a.*
20000 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f  * "Cancel" butto
20010 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72  n on a GUI progr
20020 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a  ess dialog box..
20030 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65  **.** The progre
20040 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  ss handler callb
20050 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20  ack must not do 
20060 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69  anything that wi
20070 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65  ll modify.** the
20080 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
20090 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
200a0 64 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68  d the progress h
200b0 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20  andler..** Note 
200c0 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72  that [sqlite3_pr
200d0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
200e0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
200f0 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65   both modify the
20100 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  ir.** database c
20110 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74  onnections for t
20120 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d  he meaning of "m
20130 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70  odify" in this p
20140 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a  aragraph..**.*/.
20150 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f  void sqlite3_pro
20160 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71  gress_handler(sq
20170 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74  lite3*, int, int
20180 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64  (*)(void*), void
20190 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
201a0 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e  REF: Opening A N
201b0 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  ew Database Conn
201c0 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ection.**.** ^Th
201d0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65  ese routines ope
201e0 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61  n an SQLite data
201f0 62 61 73 65 20 66 69 6c 65 20 61 73 20 73 70 65  base file as spe
20200 63 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a  cified by the .*
20210 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  * filename argum
20220 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61  ent. ^The filena
20230 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69  me argument is i
20240 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54  nterpreted as UT
20250 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  F-8 for.** sqlit
20260 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
20270 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
20280 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  and as UTF-16 in
20290 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
202a0 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71  .** order for sq
202b0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20  lite3_open16(). 
202c0 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ^(A [database co
202d0 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
202e0 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72   is usually.** r
202f0 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62  eturned in *ppDb
20300 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72  , even if an err
20310 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20  or occurs.  The 
20320 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69  only exception i
20330 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c  s that.** if SQL
20340 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ite is unable to
20350 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
20360 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71   to hold the [sq
20370 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a  lite3] object,.*
20380 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65  * a NULL will be
20390 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70   written into *p
203a0 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61  pDb instead of a
203b0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
203c0 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a  [sqlite3].** obj
203d0 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20  ect.)^ ^(If the 
203e0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
203f0 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74  ed (and/or creat
20400 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79  ed) successfully
20410 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54  , then.** [SQLIT
20420 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65  E_OK] is returne
20430 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e  d.  Otherwise an
20440 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
20450 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68   returned.)^ ^Th
20460 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72  e.** [sqlite3_er
20470 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69  rmsg()] or [sqli
20480 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20  te3_errmsg16()] 
20490 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20  routines can be 
204a0 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a  used to obtain.*
204b0 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e  * an English lan
204c0 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f  guage descriptio
204d0 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66  n of the error f
204e0 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75  ollowing a failu
204f0 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20  re of any.** of 
20500 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  the sqlite3_open
20510 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  () routines..**.
20520 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
20530 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65  encoding for the
20540 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
20550 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71  e UTF-8 if.** sq
20560 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
20570 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
20580 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a  ) is called and.
20590 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65  ** UTF-16 in the
205a0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
205b0 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f 6f 70  er if sqlite3_op
205c0 65 6e 31 36 28 29 20 69 73 20 75 73 65 64 2e 0a  en16() is used..
205d0 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72  **.** Whether or
205e0 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63   not an error oc
205f0 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20  curs when it is 
20600 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65  opened, resource
20610 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  s.** associated 
20620 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
20630 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
20640 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20  andle should be 
20650 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70  released by.** p
20660 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71  assing it to [sq
20670 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77  lite3_close()] w
20680 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e  hen it is no lon
20690 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a  ger required..**
206a0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
206b0 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66  open_v2() interf
206c0 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73  ace works like s
206d0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a  qlite3_open().**
206e0 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20   except that it 
206f0 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69  accepts two addi
20700 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72  tional parameter
20710 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  s for additional
20720 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72   control.** over
20730 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73   the new databas
20740 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e  e connection.  ^
20750 28 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d  (The flags param
20760 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  eter to.** sqlit
20770 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e  e3_open_v2() can
20780 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20   take one of.** 
20790 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  the following th
207a0 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69  ree values, opti
207b0 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20  onally combined 
207c0 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51  with the .** [SQ
207d0 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
207e0 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  X], [SQLITE_OPEN
207f0 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51  _FULLMUTEX], [SQ
20800 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
20810 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  CACHE],.** [SQLI
20820 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
20830 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53  ACHE], and/or [S
20840 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
20850 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c  flags:)^.**.** <
20860 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  dl>.** ^(<dt>[SQ
20870 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
20880 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LY]</dt>.** <dd>
20890 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
208a0 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f  opened in read-o
208b0 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68  nly mode.  If th
208c0 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20  e database does 
208d0 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65  not.** already e
208e0 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69  xist, an error i
208f0 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e  s returned.</dd>
20900 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b  )^.**.** ^(<dt>[
20910 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
20920 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  WRITE]</dt>.** <
20930 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
20940 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
20950 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e  ading and writin
20960 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f  g if possible, o
20970 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c  r reading.** onl
20980 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73  y if the file is
20990 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64   write protected
209a0 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e   by the operatin
209b0 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69  g system.  In ei
209c0 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65  ther.** case the
209d0 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61   database must a
209e0 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74  lready exist, ot
209f0 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72  herwise an error
20a00 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64   is returned.</d
20a10 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74  d>)^.**.** ^(<dt
20a20 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
20a30 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49  ADWRITE] | [SQLI
20a40 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c  TE_OPEN_CREATE]<
20a50 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
20a60 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
20a70 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  ed for reading a
20a80 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20  nd writing, and 
20a90 69 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a  is created if.**
20aa0 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72   it does not alr
20ab0 65 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73  eady exist. This
20ac0 20 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72   is the behavior
20ad0 20 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20   that is always 
20ae0 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  used for.** sqli
20af0 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
20b00 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e  qlite3_open16().
20b10 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e  </dd>)^.** </dl>
20b20 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72  .**.** If the 3r
20b30 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
20b40 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
20b50 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74   is not one of t
20b60 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f  he.** combinatio
20b70 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f  ns shown above o
20b80 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e  ptionally combin
20b90 65 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a  ed with other.**
20ba0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
20bb0 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f  ADONLY | SQLITE_
20bc0 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20  OPEN_* bits].** 
20bd0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
20be0 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
20bf0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53  **.** ^If the [S
20c00 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
20c10 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c  EX] flag is set,
20c20 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
20c30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
20c40 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75   opens in the mu
20c50 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65  lti-thread [thre
20c60 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c  ading mode] as l
20c70 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c  ong as the singl
20c80 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65  e-thread.** mode
20c90 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65   has not been se
20ca0 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  t at compile-tim
20cb0 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e  e or start-time.
20cc0 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51    ^If the.** [SQ
20cd0 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
20ce0 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74  TEX] flag is set
20cf0 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
20d00 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70  se connection op
20d10 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65  ens.** in the se
20d20 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
20d30 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73  ing mode] unless
20d40 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77   single-thread w
20d50 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  as.** previously
20d60 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d   selected at com
20d70 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61  pile-time or sta
20d80 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65  rt-time..** ^The
20d90 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48   [SQLITE_OPEN_SH
20da0 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20  AREDCACHE] flag 
20db0 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62  causes the datab
20dc0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
20dd0 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65  o be.** eligible
20de0 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20   to use [shared 
20df0 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67  cache mode], reg
20e00 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
20e10 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64  er or not shared
20e20 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61  .** cache is ena
20e30 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  bled using [sqli
20e40 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65  te3_enable_share
20e50 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68  d_cache()].  ^Th
20e60 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  e.** [SQLITE_OPE
20e70 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20  N_PRIVATECACHE] 
20e80 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20  flag causes the 
20e90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
20ea0 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61  ion to not.** pa
20eb0 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68  rticipate in [sh
20ec0 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d  ared cache mode]
20ed0 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 65   even if it is e
20ee0 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  nabled..**.** ^T
20ef0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
20f00 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
20f10 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20  pen_v2() is the 
20f20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  name of the.** [
20f30 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
20f40 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73  ect that defines
20f50 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
20f60 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20  ystem interface 
20f70 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20  that.** the new 
20f80 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
20f90 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20  ion should use. 
20fa0 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20   ^If the fourth 
20fb0 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
20fc0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
20fd0 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20  hen the default 
20fe0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
20ff0 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a  ject is used..**
21000 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65  .** ^If the file
21010 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79  name is ":memory
21020 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61  :", then a priva
21030 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e  te, temporary in
21040 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
21050 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 66  .** is created f
21060 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  or the connectio
21070 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d  n.  ^This in-mem
21080 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c  ory database wil
21090 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a  l vanish when.**
210a0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
210b0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
210c0 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  ed.  Future vers
210d0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
210e0 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65  ight.** make use
210f0 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73   of additional s
21100 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73  pecial filenames
21110 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68   that begin with
21120 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74   the ":" charact
21130 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63  er..** It is rec
21140 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68  ommended that wh
21150 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69  en a database fi
21160 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20  lename actually 
21170 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a  does begin with.
21180 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74  ** a ":" charact
21190 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72  er you should pr
211a0 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d  efix the filenam
211b0 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d  e with a pathnam
211c0 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f  e such as.** "./
211d0 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67  " to avoid ambig
211e0 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  uity..**.** ^If 
211f0 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
21200 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c  an empty string,
21210 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c   then a private,
21220 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e   temporary.** on
21230 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77  -disk database w
21240 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20  ill be created. 
21250 20 5e 54 68 69 73 20 70 72 69 76 61 74 65 20 64   ^This private d
21260 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a  atabase will be.
21270 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
21280 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e   deleted as soon
21290 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65   as the database
212a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
212b0 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55  losed..**.** [[U
212c0 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20  RI filenames in 
212d0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d  sqlite3_open()]]
212e0 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d   <h3>URI Filenam
212f0 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49  es</h3>.**.** ^I
21300 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d  f [URI filename]
21310 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
21320 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20  is enabled, and 
21330 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  the filename arg
21340 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20  ument.** begins 
21350 77 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68  with "file:", th
21360 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  en the filename 
21370 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
21380 73 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a  s a URI. ^URI.**
21390 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70   filename interp
213a0 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62  retation is enab
213b0 6c 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49  led if the [SQLI
213c0 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61  TE_OPEN_URI] fla
213d0 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74  g is.** set in t
213e0 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
213f0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  nt to sqlite3_op
21400 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69  en_v2(), or if i
21410 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e  t has.** been en
21420 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75  abled globally u
21430 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
21440 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74  _CONFIG_URI] opt
21450 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  ion with the.** 
21460 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
21470 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20  )] method or by 
21480 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f  the [SQLITE_USE_
21490 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  URI] compile-tim
214a0 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20  e option..** As 
214b0 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  of SQLite versio
214c0 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c  n 3.7.7, URI fil
214d0 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61  ename interpreta
214e0 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f  tion is turned o
214f0 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74  ff.** by default
21500 2c 20 62 75 74 20 66 75 74 75 72 65 20 72 65 6c  , but future rel
21510 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20  eases of SQLite 
21520 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49  might enable URI
21530 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74   filename.** int
21540 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64  erpretation by d
21550 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55  efault.  See "[U
21560 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66  RI filenames]" f
21570 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  or additional.**
21580 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
21590 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  .** URI filename
215a0 73 20 61 72 65 20 70 61 72 73 65 64 20 61 63 63  s are parsed acc
215b0 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39  ording to RFC 39
215c0 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20  86. ^If the URI 
215d0 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61  contains an.** a
215e0 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69  uthority, then i
215f0 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  t must be either
21600 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
21610 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a   or the string .
21620 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20  ** "localhost". 
21630 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 74  ^If the authorit
21640 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74  y is not an empt
21650 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63  y string or "loc
21660 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20  alhost", an .** 
21670 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
21680 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e  d to the caller.
21690 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63   ^The fragment c
216a0 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52  omponent of a UR
216b0 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e  I, if .** presen
216c0 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a  t, is ignored..*
216d0 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65  *.** ^SQLite use
216e0 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f  s the path compo
216f0 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20  nent of the URI 
21700 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  as the name of t
21710 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20  he disk file.** 
21720 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74  which contains t
21730 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66  he database. ^If
21740 20 74 68 65 20 70 61 74 68 20 62 65 67 69 6e 73   the path begins
21750 20 77 69 74 68 20 61 20 27 2f 27 20 63 68 61 72   with a '/' char
21760 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20  acter, .** then 
21770 69 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  it is interprete
21780 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65  d as an absolute
21790 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70   path. ^If the p
217a0 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67  ath does not beg
217b0 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f  in .** with a '/
217c0 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20  ' (meaning that 
217d0 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 73 65  the authority se
217e0 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64  ction is omitted
217f0 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a   from the URI).*
21800 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74 68 20  * then the path 
21810 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
21820 73 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74  s a relative pat
21830 68 2e 20 0a 2a 2a 20 5e 4f 6e 20 77 69 6e 64 6f  h. .** ^On windo
21840 77 73 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f  ws, the first co
21850 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62  mponent of an ab
21860 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20  solute path .** 
21870 69 73 20 61 20 64 72 69 76 65 20 73 70 65 63 69  is a drive speci
21880 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22  fication (e.g. "
21890 43 3a 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f  C:")..**.** [[co
218a0 72 65 20 55 52 49 20 71 75 65 72 79 20 70 61 72  re URI query par
218b0 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65  ameters]].** The
218c0 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74   query component
218d0 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f   of a URI may co
218e0 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73  ntain parameters
218f0 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 70   that are interp
21900 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20  reted.** either 
21910 62 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66  by SQLite itself
21920 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c  , or by a [VFS |
21930 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c   custom VFS impl
21940 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20  ementation]..** 
21950 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74  SQLite interpret
21960 73 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  s the following 
21970 74 68 72 65 65 20 71 75 65 72 79 20 70 61 72 61  three query para
21980 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  meters:.**.** <u
21990 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e  l>.**   <li> <b>
219a0 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76  vfs</b>: ^The "v
219b0 66 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61  fs" parameter ma
219c0 79 20 62 65 20 75 73 65 64 20 74 6f 20 73 70 65  y be used to spe
219d0 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66  cify the name of
219e0 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62  .**     a VFS ob
219f0 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76 69 64  ject that provid
21a00 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  es the operating
21a10 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63   system interfac
21a20 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a  e that should.**
21a30 20 20 20 20 20 62 65 20 75 73 65 64 20 74 6f 20       be used to 
21a40 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62  access the datab
21a50 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b  ase file on disk
21a60 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f  . ^If this optio
21a70 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20  n is set to.**  
21a80 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69     an empty stri
21a90 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74 20 56  ng the default V
21aa0 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  FS object is use
21ab0 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61  d. ^Specifying a
21ac0 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20  n unknown.**    
21ad0 20 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72   VFS is an error
21ae0 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70  . ^If sqlite3_op
21af0 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20  en_v2() is used 
21b00 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74 69  and the vfs opti
21b10 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65  on is.**     pre
21b20 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56  sent, then the V
21b30 46 53 20 73 70 65 63 69 66 69 65 64 20 62 79 20  FS specified by 
21b40 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  the option takes
21b50 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72   precedence over
21b60 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75  .**     the valu
21b70 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
21b80 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
21b90 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
21ba0 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c  _v2()..**.**   <
21bb0 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a  li> <b>mode</b>:
21bc0 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61   ^(The mode para
21bd0 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74  meter may be set
21be0 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c   to either "ro",
21bf0 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72   "rw",.**     "r
21c00 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22  wc", or "memory"
21c10 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20  . Attempting to 
21c20 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74  set it to any ot
21c30 68 65 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20  her value is.** 
21c40 20 20 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20      an error)^. 
21c50 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22  .**     ^If "ro"
21c60 20 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 74   is specified, t
21c70 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
21c80 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
21c90 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20  ead-only .**    
21ca0 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73   access, just as
21cb0 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   if the [SQLITE_
21cc0 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66  OPEN_READONLY] f
21cd0 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73 65 74  lag had been set
21ce0 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20   in the .**     
21cf0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74  third argument t
21d00 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
21d10 32 28 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64  2(). ^If the mod
21d20 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20  e option is set 
21d30 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c  to .**     "rw",
21d40 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
21d50 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
21d60 20 72 65 61 64 2d 77 72 69 74 65 20 28 62 75 74   read-write (but
21d70 20 6e 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a   not create) .**
21d80 20 20 20 20 20 61 63 63 65 73 73 2c 20 61 73 20       access, as 
21d90 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  if SQLITE_OPEN_R
21da0 45 41 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f  EADWRITE (but no
21db0 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  t SQLITE_OPEN_CR
21dc0 45 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20  EATE) had .**   
21dd0 20 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c    been set. ^Val
21de0 75 65 20 22 72 77 63 22 20 69 73 20 65 71 75 69  ue "rwc" is equi
21df0 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e  valent to settin
21e00 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53  g both .**     S
21e10 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
21e20 52 49 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f  RITE and SQLITE_
21e30 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49  OPEN_CREATE.  ^I
21e40 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f  f the mode optio
21e50 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20  n is.**     set 
21e60 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e  to "memory" then
21e70 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f   a pure [in-memo
21e80 72 79 20 64 61 74 61 62 61 73 65 5d 20 74 68 61  ry database] tha
21e90 74 20 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a  t never reads.**
21ea0 20 20 20 20 20 6f 72 20 77 72 69 74 65 73 20 66       or writes f
21eb0 72 6f 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64  rom disk is used
21ec0 2e 20 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f  . ^It is an erro
21ed0 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 20 76  r to specify a v
21ee0 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20  alue for.**     
21ef0 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74  the mode paramet
21f00 65 72 20 74 68 61 74 20 69 73 20 6c 65 73 73 20  er that is less 
21f10 72 65 73 74 72 69 63 74 69 76 65 20 74 68 61 6e  restrictive than
21f20 20 74 68 61 74 20 73 70 65 63 69 66 69 65 64 20   that specified 
21f30 62 79 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c  by.**     the fl
21f40 61 67 73 20 70 61 73 73 65 64 20 69 6e 20 74 68  ags passed in th
21f50 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
21f60 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
21f70 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20  n_v2()..**.**   
21f80 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62  <li> <b>cache</b
21f90 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70 61  >: ^The cache pa
21fa0 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73  rameter may be s
21fb0 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 73 68  et to either "sh
21fc0 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20  ared" or.**     
21fd0 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74  "private". ^Sett
21fe0 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72 65  ing it to "share
21ff0 64 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74  d" is equivalent
22000 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a   to setting the.
22010 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50  **     SQLITE_OP
22020 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 62  EN_SHAREDCACHE b
22030 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20  it in the flags 
22040 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
22050 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65  to.**     sqlite
22060 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65  3_open_v2(). ^Se
22070 74 74 69 6e 67 20 74 68 65 20 63 61 63 68 65 20  tting the cache 
22080 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72  parameter to "pr
22090 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20  ivate" is .**   
220a0 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20    equivalent to 
220b0 73 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49  setting the SQLI
220c0 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
220d0 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20  ACHE bit..**    
220e0 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65   ^If sqlite3_ope
220f0 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61  n_v2() is used a
22100 6e 64 20 74 68 65 20 22 63 61 63 68 65 22 20 70  nd the "cache" p
22110 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 65 73  arameter is pres
22120 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20  ent in.**     a 
22130 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74  URI filename, it
22140 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65  s value override
22150 73 20 61 6e 79 20 62 65 68 61 76 69 6f 72 20 72  s any behavior r
22160 65 71 75 65 73 74 65 64 20 62 79 20 73 65 74 74  equested by sett
22170 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  ing.**     SQLIT
22180 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
22190 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50  CHE or SQLITE_OP
221a0 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 66  EN_SHAREDCACHE f
221b0 6c 61 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  lag..** </ul>.**
221c0 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20  .** ^Specifying 
221d0 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d  an unknown param
221e0 65 74 65 72 20 69 6e 20 74 68 65 20 71 75 65 72  eter in the quer
221f0 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  y component of a
22200 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a   URI is not an.*
22210 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65  * error.  Future
22220 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
22230 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73  ite might unders
22240 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20  tand additional 
22250 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74  query.** paramet
22260 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72  ers.  See "[quer
22270 79 20 70 61 72 61 6d 65 74 65 72 73 20 77 69 74  y parameters wit
22280 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e  h special meanin
22290 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f  g to SQLite]" fo
222a0 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20  r.** additional 
222b0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
222c0 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ** [[URI filenam
222d0 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33  e examples]] <h3
222e0 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78  >URI filename ex
222f0 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a  amples</h3>.**.*
22300 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d  * <table border=
22310 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72  "1" align=center
22320 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a   cellpadding=5>.
22330 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20  ** <tr><th> URI 
22340 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52  filenames <th> R
22350 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74  esults.** <tr><t
22360 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20  d> file:data.db 
22370 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
22380 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20    Open the file 
22390 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65  "data.db" in the
223a0 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f   current directo
223b0 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ry..** <tr><td> 
223c0 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f  file:/home/fred/
223d0 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20  data.db<br>.**  
223e0 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f          file:///
223f0 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
22400 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20  b <br> .**      
22410 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c      file://local
22420 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  host/home/fred/d
22430 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e  ata.db <br> <td>
22440 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70   .**          Op
22450 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
22460 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64  file "/home/fred
22470 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74  /data.db"..** <t
22480 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61  r><td> file://da
22490 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64  rkstar/home/fred
224a0 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a  /data.db <td> .*
224b0 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72  *          An er
224c0 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20  ror. "darkstar" 
224d0 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69  is not a recogni
224e0 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a  zed authority..*
224f0 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d  * <tr><td style=
22500 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77  "white-space:now
22510 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20  rap"> .**       
22520 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f     file:///C:/Do
22530 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30  cuments%20and%20
22540 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65  Settings/fred/De
22550 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a  sktop/data.db.**
22560 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77       <td> Window
22570 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65  s only: Open the
22580 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20   file "data.db" 
22590 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f  on fred's deskto
225a0 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20  p on drive.**   
225b0 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20         C:. Note 
225c0 74 68 61 74 20 74 68 65 20 25 32 30 20 65 73 63  that the %20 esc
225d0 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78  aping in this ex
225e0 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72  ample is not str
225f0 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20  ictly .**       
22600 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73     necessary - s
22610 70 61 63 65 20 63 68 61 72 61 63 74 65 72 73 20  pace characters 
22620 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65  can be used lite
22630 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20  rally.**        
22640 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d    in URI filenam
22650 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  es..** <tr><td> 
22660 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64  file:data.db?mod
22670 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61  e=ro&cache=priva
22680 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  te <td> .**     
22690 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22       Open file "
226a0 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20  data.db" in the 
226b0 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72  current director
226c0 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20  y for read-only 
226d0 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20  access..**      
226e0 20 20 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f      Regardless o
226f0 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
22700 20 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f   shared-cache mo
22710 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79  de is enabled by
22720 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 66  .**          def
22730 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76  ault, use a priv
22740 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74  ate cache..** <t
22750 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d  r><td> file:/hom
22760 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76  e/fred/data.db?v
22770 66 73 3d 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 20 3c  fs=unix-nolock <
22780 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  td>.**          
22790 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65  Open file "/home
227a0 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20  /fred/data.db". 
227b0 55 73 65 20 74 68 65 20 73 70 65 63 69 61 6c 20  Use the special 
227c0 56 46 53 20 22 75 6e 69 78 2d 6e 6f 6c 6f 63 6b  VFS "unix-nolock
227d0 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  "..** <tr><td> f
227e0 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65  ile:data.db?mode
227f0 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a  =readonly <td> .
22800 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65  **          An e
22810 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22  rror. "readonly"
22820 20 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20   is not a valid 
22830 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22  option for the "
22840 6d 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e  mode" parameter.
22850 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a  .** </table>.**.
22860 2a 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63 69  ** ^URI hexadeci
22870 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65  mal escape seque
22880 6e 63 65 73 20 28 25 48 48 29 20 61 72 65 20 73  nces (%HH) are s
22890 75 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20  upported within 
228a0 74 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20  the path and.** 
228b0 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73  query components
228c0 20 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65 78   of a URI. A hex
228d0 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20  adecimal escape 
228e0 73 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74  sequence consist
228f0 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e  s of a.** percen
22900 74 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66  t sign - "%" - f
22910 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74  ollowed by exact
22920 6c 79 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d  ly two hexadecim
22930 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70  al digits .** sp
22940 65 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65  ecifying an octe
22950 74 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65  t value. ^Before
22960 20 74 68 65 20 70 61 74 68 20 6f 72 20 71 75 65   the path or que
22970 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66  ry components of
22980 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61   a.** URI filena
22990 6d 65 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  me are interpret
229a0 65 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63  ed, they are enc
229b0 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38  oded using UTF-8
229c0 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78   and all .** hex
229d0 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20  adecimal escape 
229e0 73 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63  sequences replac
229f0 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62  ed by a single b
22a00 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  yte containing t
22a10 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64  he.** correspond
22a20 69 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68  ing octet. If th
22a30 69 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72  is process gener
22a40 61 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20  ates an invalid 
22a50 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a  UTF-8 encoding,.
22a60 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  ** the results a
22a70 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
22a80 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57  .** <b>Note to W
22a90 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62  indows users:</b
22aa0 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20  >  The encoding 
22ab0 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c  used for the fil
22ac0 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ename argument.*
22ad0 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65  * of sqlite3_ope
22ae0 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
22af0 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62  open_v2() must b
22b00 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61  e UTF-8, not wha
22b10 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67  tever.** codepag
22b20 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64  e is currently d
22b30 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d  efined.  Filenam
22b40 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e  es containing in
22b50 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63  ternational.** c
22b60 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62  haracters must b
22b70 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55  e converted to U
22b80 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61  TF-8 prior to pa
22b90 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a  ssing them into.
22ba0 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
22bb0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
22bc0 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62  n_v2()..**.** <b
22bd0 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73  >Note to Windows
22be0 20 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c   Runtime users:<
22bf0 2f 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61  /b>  The tempora
22c00 72 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73  ry directory mus
22c10 74 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f  t be set.** prio
22c20 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c  r to calling sql
22c30 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
22c40 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
22c50 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61  .  Otherwise, va
22c60 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65  rious.** feature
22c70 73 20 74 68 61 74 20 72 65 71 75 69 72 65 20 74  s that require t
22c80 68 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72  he use of tempor
22c90 61 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61  ary files may fa
22ca0 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  il..**.** See al
22cb0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d  so: [sqlite3_tem
22cc0 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a  p_directory].*/.
22cd0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
22ce0 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
22cf0 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
22d00 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
22d10 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
22d20 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
22d30 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
22d40 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
22d50 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
22d60 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74  _open16(.  const
22d70 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c   void *filename,
22d80 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
22d90 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29  ilename (UTF-16)
22da0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
22db0 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
22dc0 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
22dd0 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74  handle */.);.int
22de0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
22df0 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
22e00 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
22e10 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
22e20 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
22e30 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20  lite3 **ppDb,   
22e40 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
22e50 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
22e60 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20  /.  int flags,  
22e70 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46              /* F
22e80 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  lags */.  const 
22e90 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20  char *zVfs      
22ea0 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53    /* Name of VFS
22eb0 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a   module to use *
22ec0 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
22ed0 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c  3REF: Obtain Val
22ee0 75 65 73 20 46 6f 72 20 55 52 49 20 50 61 72 61  ues For URI Para
22ef0 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65  meters.**.** The
22f00 73 65 20 61 72 65 20 75 74 69 6c 69 74 79 20 72  se are utility r
22f10 6f 75 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20  outines, useful 
22f20 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  to VFS implement
22f30 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65  ations, that che
22f40 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20  ck.** to see if 
22f50 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
22f60 77 61 73 20 61 20 55 52 49 20 74 68 61 74 20 63  was a URI that c
22f70 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63 69  ontained a speci
22f80 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61  fic query .** pa
22f90 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20  rameter, and if 
22fa0 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76  so obtains the v
22fb0 61 6c 75 65 20 6f 66 20 74 68 61 74 20 71 75 65  alue of that que
22fc0 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  ry parameter..**
22fd0 0a 2a 2a 20 49 66 20 46 20 69 73 20 74 68 65 20  .** If F is the 
22fe0 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  database filenam
22ff0 65 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64  e pointer passed
23000 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28   into the xOpen(
23010 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20  ) method of .** 
23020 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  a VFS implementa
23030 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c  tion when the fl
23040 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ags parameter to
23050 20 78 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65   xOpen() has one
23060 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20   or .** more of 
23070 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
23080 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45  _URI] or [SQLITE
23090 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62  _OPEN_MAIN_DB] b
230a0 69 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50  its set and.** P
230b0 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
230c0 74 68 65 20 71 75 65 72 79 20 70 61 72 61 6d 65  the query parame
230d0 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  ter, then.** sql
230e0 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
230f0 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20  er(F,P) returns 
23100 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
23110 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20   P.** parameter 
23120 69 66 20 69 74 20 65 78 69 73 74 73 20 6f 72 20  if it exists or 
23130 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
23140 66 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70  f P does not app
23150 65 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65  ear as a .** que
23160 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20  ry parameter on 
23170 46 2e 20 20 49 66 20 50 20 69 73 20 61 20 71 75  F.  If P is a qu
23180 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66  ery parameter of
23190 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70   F.** has no exp
231a0 6c 69 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65  licit value, the
231b0 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61  n sqlite3_uri_pa
231c0 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74  rameter(F,P) ret
231d0 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  urns.** a pointe
231e0 72 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74  r to an empty st
231f0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ring..**.** The 
23200 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
23210 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69  ean(F,P,B) routi
23220 6e 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  ne assumes that 
23230 50 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a  P is a boolean.*
23240 2a 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20  * parameter and 
23250 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29  returns true (1)
23260 20 6f 72 20 66 61 6c 73 65 20 28 30 29 20 61 63   or false (0) ac
23270 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76  cording to the v
23280 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54  alue.** of P.  T
23290 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  he sqlite3_uri_b
232a0 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
232b0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72  utine returns tr
232c0 75 65 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a  ue (1) if the.**
232d0 20 76 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20   value of query 
232e0 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f  parameter P is o
232f0 6e 65 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72  ne of "yes", "tr
23300 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20  ue", or "on" in 
23310 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69  any.** case or i
23320 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69  f the value begi
23330 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65  ns with a non-ze
23340 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20  ro number.  The 
23350 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  .** sqlite3_uri_
23360 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
23370 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20  outines returns 
23380 66 61 6c 73 65 20 28 30 29 20 69 66 20 74 68 65  false (0) if the
23390 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65   value of.** que
233a0 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  ry parameter P i
233b0 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22  s one of "no", "
233c0 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22  false", or "off"
233d0 20 69 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a   in any case or.
233e0 2a 2a 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  ** if the value 
233f0 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75  begins with a nu
23400 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20  meric zero.  If 
23410 50 20 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79  P is not a query
23420 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e  .** parameter on
23430 20 46 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c   F or if the val
23440 75 65 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20  ue of P is does 
23450 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66  not match any of
23460 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74   the.** above, t
23470 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  hen sqlite3_uri_
23480 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
23490 65 74 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a  eturns (B!=0)..*
234a0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
234b0 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44  _uri_int64(F,P,D
234c0 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72  ) routine conver
234d0 74 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ts the value of 
234e0 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62  P into a.** 64-b
234f0 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
23500 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68  r and returns th
23510 61 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44  at integer, or D
23520 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a   if P does not.*
23530 2a 20 65 78 69 73 74 2e 20 20 49 66 20 74 68 65  * exist.  If the
23540 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73   value of P is s
23550 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74  omething other t
23560 68 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20  han an integer, 
23570 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20  then.** zero is 
23580 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a  returned..** .**
23590 20 49 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20   If F is a NULL 
235a0 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71  pointer, then sq
235b0 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
235c0 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73  ter(F,P) returns
235d0 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c   NULL and.** sql
235e0 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
235f0 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20  (F,P,B) returns 
23600 42 2e 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20  B.  If F is not 
23610 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61  a NULL pointer a
23620 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64  nd.** is not a d
23630 61 74 61 62 61 73 65 20 66 69 6c 65 20 70 61 74  atabase file pat
23640 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68  hname pointer th
23650 61 74 20 53 51 4c 69 74 65 20 70 61 73 73 65 64  at SQLite passed
23660 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a   into the xOpen.
23670 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74  ** VFS method, t
23680 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
23690 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
236a0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
236b0 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e  d probably.** un
236c0 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f  desirable..*/.co
236d0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
236e0 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
236f0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
23700 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61  ename, const cha
23710 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e 74 20  r *zParam);.int 
23720 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
23730 65 61 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ean(const char *
23740 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61  zFile, const cha
23750 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62  r *zParam, int b
23760 44 65 66 61 75 6c 74 29 3b 0a 73 71 6c 69 74 65  Default);.sqlite
23770 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
23780 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20  uri_int64(const 
23790 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61  char*, const cha
237a0 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  r*, sqlite3_int6
237b0 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  4);.../*.** CAPI
237c0 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65  3REF: Error Code
237d0 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a  s And Messages.*
237e0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
237f0 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65  3_errcode() inte
23800 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
23810 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c  e numeric [resul
23820 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65  t code] or.** [e
23830 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
23840 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73  ode] for the mos
23850 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20  t recent failed 
23860 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61  sqlite3_* API ca
23870 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  ll.** associated
23880 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73   with a [databas
23890 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49  e connection]. I
238a0 66 20 61 20 70 72 69 6f 72 20 41 50 49 20 63 61  f a prior API ca
238b0 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74  ll failed.** but
238c0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
238d0 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65   API call succee
238e0 64 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20  ded, the return 
238f0 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71  value from.** sq
23900 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20  lite3_errcode() 
23910 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 5e  is undefined.  ^
23920 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
23930 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a  nded_errcode().*
23940 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  * interface is t
23950 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 74  he same except t
23960 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 65  hat it always re
23970 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65  turns the .** [e
23980 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
23990 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65  ode] even when e
239a0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
239b0 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61  odes are.** disa
239c0 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bled..**.** ^The
239d0 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28   sqlite3_errmsg(
239e0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72  ) and sqlite3_er
239f0 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20  rmsg16() return 
23a00 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65  English-language
23a10 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65  .** text that de
23a20 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
23a30 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46  r, as either UTF
23a40 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73  -8 or UTF-16 res
23a50 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28  pectively..** ^(
23a60 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  Memory to hold t
23a70 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
23a80 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67   string is manag
23a90 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a  ed internally..*
23aa0 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
23ab0 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  n does not need 
23ac0 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66  to worry about f
23ad0 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c  reeing the resul
23ae0 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74  t..** However, t
23af0 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20  he error string 
23b00 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 69  might be overwri
23b10 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61  tten or dealloca
23b20 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71  ted by.** subseq
23b30 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74  uent calls to ot
23b40 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
23b50 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29  face functions.)
23b60 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
23b70 69 74 65 33 5f 65 72 72 73 74 72 28 29 20 69 6e  ite3_errstr() in
23b80 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
23b90 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67  the English-lang
23ba0 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 61  uage text.** tha
23bb0 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  t describes the 
23bc0 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61  [result code], a
23bd0 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65  s UTF-8..** ^(Me
23be0 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
23bf0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
23c00 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64  tring is managed
23c10 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61   internally.** a
23c20 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 66  nd must not be f
23c30 72 65 65 64 20 62 79 20 74 68 65 20 61 70 70 6c  reed by the appl
23c40 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a  ication)^..**.**
23c50 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c   When the serial
23c60 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
23c70 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c  mode] is in use,
23c80 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 65   it might be the
23c90 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61 20  .** case that a 
23ca0 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63  second error occ
23cb0 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74  urs on a separat
23cc0 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74 77  e thread in betw
23cd0 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20  een.** the time 
23ce0 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72 72  of the first err
23cf0 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20  or and the call 
23d00 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  to these interfa
23d10 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61  ces..** When tha
23d20 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73  t happens, the s
23d30 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c  econd error will
23d40 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e   be reported sin
23d50 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65  ce these.** inte
23d60 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72 65  rfaces always re
23d70 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65  port the most re
23d80 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f  cent result.  To
23d90 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20   avoid.** this, 
23da0 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e 20  each thread can 
23db0 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65  obtain exclusive
23dc0 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74   use of the [dat
23dd0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
23de0 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69  ] D.** by invoki
23df0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
23e00 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65  x_enter]([sqlite
23e10 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20  3_db_mutex](D)) 
23e20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67  before beginning
23e30 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64  .** to use D and
23e40 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74   invoking [sqlit
23e50 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28  e3_mutex_leave](
23e60 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65  [sqlite3_db_mute
23e70 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20  x](D)) after.** 
23e80 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  all calls to the
23e90 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74   interfaces list
23ea0 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70  ed here are comp
23eb0 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  leted..**.** If 
23ec0 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 69  an interface fai
23ed0 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d  ls with SQLITE_M
23ee0 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e  ISUSE, that mean
23ef0 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a  s the interface.
23f00 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69  ** was invoked i
23f10 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68  ncorrectly by th
23f20 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  e application.  
23f30 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 68  In that case, th
23f40 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20  e.** error code 
23f50 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20  and message may 
23f60 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65  or may not be se
23f70 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  t..*/.int sqlite
23f80 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65  3_errcode(sqlite
23f90 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69  3 *db);.int sqli
23fa0 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72  te3_extended_err
23fb0 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62  code(sqlite3 *db
23fc0 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
23fd0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71  qlite3_errmsg(sq
23fe0 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76  lite3*);.const v
23ff0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  oid *sqlite3_err
24000 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b  msg16(sqlite3*);
24010 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
24020 69 74 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29  ite3_errstr(int)
24030 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
24040 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  F: SQL Statement
24050 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f   Object.** KEYWO
24060 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73  RDS: {prepared s
24070 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61  tatement} {prepa
24080 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a  red statements}.
24090 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
240a0 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
240b0 20 72 65 70 72 65 73 65 6e 74 73 20 61 20 73 69   represents a si
240c0 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65  ngle SQL stateme
240d0 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65  nt..** This obje
240e0 63 74 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20  ct is variously 
240f0 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70  known as a "prep
24100 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20  ared statement" 
24110 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65  or a.** "compile
24120 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22  d SQL statement"
24130 20 6f 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20   or simply as a 
24140 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a  "statement"..**.
24150 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61  ** The life of a
24160 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63   statement objec
24170 74 20 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67  t goes something
24180 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
24190 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43  * <ol>.** <li> C
241a0 72 65 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74  reate the object
241b0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
241c0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
241d0 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20   a related.**   
241e0 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20     function..** 
241f0 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73  <li> Bind values
24200 20 74 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65   to [host parame
24210 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20  ters] using the 
24220 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
24230 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61  .**      interfa
24240 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e  ces..** <li> Run
24250 20 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c   the SQL by call
24260 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
24270 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  p()] one or more
24280 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20   times..** <li> 
24290 52 65 73 65 74 20 74 68 65 20 73 74 61 74 65 6d  Reset the statem
242a0 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ent using [sqlit
242b0 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e  e3_reset()] then
242c0 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20   go back.**     
242d0 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20   to step 2.  Do 
242e0 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  this zero or mor
242f0 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  e times..** <li>
24300 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a   Destroy the obj
24310 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ect using [sqlit
24320 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a  e3_finalize()]..
24330 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52  ** </ol>.**.** R
24340 65 66 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74  efer to document
24350 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64  ation on individ
24360 75 61 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  ual methods abov
24370 65 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  e for additional
24380 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
24390 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
243a0 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ct sqlite3_stmt 
243b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f  sqlite3_stmt;../
243c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
243d0 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a  un-time Limits.*
243e0 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65  *.** ^(This inte
243f0 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65  rface allows the
24400 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73   size of various
24410 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62   constructs to b
24420 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20  e limited.** on 
24430 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20  a connection by 
24440 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73  connection basis
24450 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72  .  The first par
24460 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
24470 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
24480 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d  ction] whose lim
24490 69 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20  it is to be set 
244a0 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65  or queried.  The
244b0 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
244c0 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74  eter is one of t
244d0 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f  he [limit catego
244e0 72 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e  ries] that defin
244f0 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20  e a.** class of 
24500 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65  constructs to be
24510 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20   size limited.  
24520 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
24530 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65  ter is the.** ne
24540 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74  w limit for that
24550 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a   construct.)^.**
24560 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20  .** ^If the new 
24570 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74  limit is a negat
24580 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20  ive number, the 
24590 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67  limit is unchang
245a0 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63  ed..** ^(For eac
245b0 68 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79  h limit category
245c0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69   SQLITE_LIMIT_<i
245d0 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20  >NAME</i> there 
245e0 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73  is a .** [limits
245f0 20 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f   | hard upper bo
24600 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63  und].** set at c
24610 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61  ompile-time by a
24620 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
24630 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20  macro called.** 
24640 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45  [limits | SQLITE
24650 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e  _MAX_<i>NAME</i>
24660 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d  ]..** (The "_LIM
24670 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65  IT_" in the name
24680 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22   is changed to "
24690 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41  _MAX_".))^.** ^A
246a0 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65  ttempts to incre
246b0 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76  ase a limit abov
246c0 65 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72  e its hard upper
246d0 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69   bound are.** si
246e0 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64  lently truncated
246f0 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70   to the hard upp
24700 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20  er bound..**.** 
24710 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77  ^Regardless of w
24720 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
24730 65 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e  e limit was chan
24740 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71  ged, the .** [sq
24750 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69  lite3_limit()] i
24760 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
24770 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65   the prior value
24780 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a   of the limit..*
24790 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e  * ^Hence, to fin
247a0 64 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61  d the current va
247b0 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77  lue of a limit w
247c0 69 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20  ithout changing 
247d0 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e  it,.** simply in
247e0 76 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66  voke this interf
247f0 61 63 65 20 77 69 74 68 20 74 68 65 20 74 68 69  ace with the thi
24800 72 64 20 70 61 72 61 6d 65 74 65 72 20 73 65 74  rd parameter set
24810 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75   to -1..**.** Ru
24820 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72  n-time limits ar
24830 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75  e intended for u
24840 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f  se in applicatio
24850 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a  ns that manage.*
24860 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e  * both their own
24870 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61   internal databa
24880 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61  se and also data
24890 62 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63  bases that are c
248a0 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20  ontrolled.** by 
248b0 75 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e  untrusted extern
248c0 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20  al sources.  An 
248d0 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74  example applicat
248e0 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a  ion might be a.*
248f0 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68  * web browser th
24900 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64  at has its own d
24910 61 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f  atabases for sto
24920 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64  ring history and
24930 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74  .** separate dat
24940 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65  abases controlle
24950 64 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20  d by JavaScript 
24960 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77  applications dow
24970 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74  nloaded.** off t
24980 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68  he Internet.  Th
24990 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62  e internal datab
249a0 61 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65  ases can be give
249b0 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20  n the.** large, 
249c0 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20  default limits. 
249d0 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67   Databases manag
249e0 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73  ed by external s
249f0 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65  ources can.** be
24a00 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c   given much smal
24a10 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67  ler limits desig
24a20 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61  ned to prevent a
24a30 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69   denial of servi
24a40 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44  ce.** attack.  D
24a50 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20  evelopers might 
24a60 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65  also want to use
24a70 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   the [sqlite3_se
24a80 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a  t_authorizer()].
24a90 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20  ** interface to 
24aa0 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20  further control 
24ab0 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20  untrusted SQL.  
24ac0 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  The size of the 
24ad0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61  database.** crea
24ae0 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73  ted by an untrus
24af0 74 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62  ted script can b
24b00 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e  e contained usin
24b10 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61  g the.** [max_pa
24b20 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d  ge_count] [PRAGM
24b30 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75  A]..**.** New ru
24b40 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74  n-time limit cat
24b50 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61  egories may be a
24b60 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
24b70 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20  eleases..*/.int 
24b80 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71  sqlite3_limit(sq
24b90 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20  lite3*, int id, 
24ba0 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a  int newVal);../*
24bb0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75  .** CAPI3REF: Ru
24bc0 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74  n-Time Limit Cat
24bd0 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f  egories.** KEYWO
24be0 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65  RDS: {limit cate
24bf0 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61  gory} {*limit ca
24c00 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20  tegories}.**.** 
24c10 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
24c20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70  define various p
24c30 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74  erformance limit
24c40 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65  s.** that can be
24c50 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d   lowered at run-
24c60 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69  time using [sqli
24c70 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a  te3_limit()]..**
24c80 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66   The synopsis of
24c90 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66   the meanings of
24ca0 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d   the various lim
24cb0 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c  its is shown bel
24cc0 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61  ow..** Additiona
24cd0 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  l information is
24ce0 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c   available at [l
24cf0 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69  imits | Limits i
24d00 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a  n SQLite]..**.**
24d10 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54   <dl>.** [[SQLIT
24d20 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d  E_LIMIT_LENGTH]]
24d30 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
24d40 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  MIT_LENGTH</dt>.
24d50 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
24d60 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73  um size of any s
24d70 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72  tring or BLOB or
24d80 20 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62   table row, in b
24d90 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a  ytes.<dd>)^.**.*
24da0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
24db0 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28  _SQL_LENGTH]] ^(
24dc0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
24dd0 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  _SQL_LENGTH</dt>
24de0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
24df0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e  mum length of an
24e00 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
24e10 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e  in bytes.</dd>)^
24e20 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
24e30 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e  LIMIT_COLUMN]] ^
24e40 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
24e50 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a  T_COLUMN</dt>.**
24e60 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
24e70 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
24e80 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65  ns in a table de
24e90 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74  finition or in t
24ea0 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74  he.** result set
24eb0 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f   of a [SELECT] o
24ec0 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  r the maximum nu
24ed0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
24ee0 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f  in an index.** o
24ef0 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59  r in an ORDER BY
24f00 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61   or GROUP BY cla
24f10 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  use.</dd>)^.**.*
24f20 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
24f30 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28  _EXPR_DEPTH]] ^(
24f40 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
24f50 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e  _EXPR_DEPTH</dt>
24f60 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
24f70 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65  mum depth of the
24f80 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61   parse tree on a
24f90 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f  ny expression.</
24fa0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
24fb0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
24fc0 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c  UND_SELECT]] ^(<
24fd0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
24fe0 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c  COMPOUND_SELECT<
24ff0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
25000 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
25010 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d  f terms in a com
25020 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61  pound SELECT sta
25030 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a  tement.</dd>)^.*
25040 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
25050 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28  MIT_VDBE_OP]] ^(
25060 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
25070 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a  _VDBE_OP</dt>.**
25080 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
25090 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72   number of instr
250a0 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72  uctions in a vir
250b0 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f  tual machine pro
250c0 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20  gram.** used to 
250d0 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c  implement an SQL
250e0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 69   statement.  Thi
250f0 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63  s limit is not c
25100 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f  urrently.** enfo
25110 72 63 65 64 2c 20 74 68 6f 75 67 68 20 74 68 61  rced, though tha
25120 74 20 6d 69 67 68 74 20 62 65 20 61 64 64 65 64  t might be added
25130 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20   in some future 
25140 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51  release of.** SQ
25150 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  Lite.</dd>)^.**.
25160 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
25170 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d  T_FUNCTION_ARG]]
25180 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
25190 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
251a0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
251b0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
251c0 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20  of arguments on 
251d0 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e  a function.</dd>
251e0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
251f0 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
25200 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
25210 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f  LIMIT_ATTACHED</
25220 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
25230 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
25240 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61 63   [ATTACH | attac
25250 68 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29  hed databases].)
25260 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ^</dd>.**.** [[S
25270 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45  QLITE_LIMIT_LIKE
25280 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d  _PATTERN_LENGTH]
25290 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  ].** ^(<dt>SQLIT
252a0 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54  E_LIMIT_LIKE_PAT
252b0 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  TERN_LENGTH</dt>
252c0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
252d0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  mum length of th
252e0 65 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65  e pattern argume
252f0 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d  nt to the [LIKE]
25300 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70   or.** [GLOB] op
25310 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a  erators.</dd>)^.
25320 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
25330 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
25340 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e  MBER]].** ^(<dt>
25350 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
25360 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74  IABLE_NUMBER</dt
25370 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
25380 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65  imum index numbe
25390 72 20 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65  r of any [parame
253a0 74 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73  ter] in an SQL s
253b0 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a  tatement.)^.**.*
253c0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
253d0 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 5d 5d  _TRIGGER_DEPTH]]
253e0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
253f0 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
25400 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
25410 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20  e maximum depth 
25420 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72  of recursion for
25430 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29   triggers.</dd>)
25440 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  ^.** </dl>.*/.#d
25450 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
25460 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  IT_LENGTH       
25470 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0a 23               0.#
25480 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
25490 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20  MIT_SQL_LENGTH  
254a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a                1.
254b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
254c0 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20  IMIT_COLUMN     
254d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
254e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
254f0 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
25500 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
25510 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
25520 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
25530 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20  SELECT          
25540 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
25550 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20  E_LIMIT_VDBE_OP 
25560 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
25570 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    5.#define SQLI
25580 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
25590 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20 20 20  N_ARG           
255a0 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c     6.#define SQL
255b0 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48  ITE_LIMIT_ATTACH
255c0 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ED              
255d0 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51      7.#define SQ
255e0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f  LITE_LIMIT_LIKE_
255f0 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20  PATTERN_LENGTH  
25600 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53       8.#define S
25610 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
25620 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20  ABLE_NUMBER     
25630 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20        9.#define 
25640 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49  SQLITE_LIMIT_TRI
25650 47 47 45 52 5f 44 45 50 54 48 20 20 20 20 20 20  GGER_DEPTH      
25660 20 20 20 20 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20        10../*.** 
25670 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c  CAPI3REF: Compil
25680 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65  ing An SQL State
25690 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ment.** KEYWORDS
256a0 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  : {SQL statement
256b0 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a   compiler}.**.**
256c0 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53   To execute an S
256d0 51 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73  QL query, it mus
256e0 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69  t first be compi
256f0 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d  led into a byte-
25700 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20  code.** program 
25710 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65  using one of the
25720 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  se routines..**.
25730 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
25740 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20  ument, "db", is 
25750 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
25760 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64  ection] obtained
25770 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72   from a.** prior
25780 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
25790 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
257a0 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
257b0 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20  pen_v2()] or.** 
257c0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
257d0 29 5d 2e 20 20 54 68 65 20 64 61 74 61 62 61 73  )].  The databas
257e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73  e connection mus
257f0 74 20 6e 6f 74 20 68 61 76 65 20 62 65 65 6e 20  t not have been 
25800 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  closed..**.** Th
25810 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
25820 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68  t, "zSql", is th
25830 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62  e statement to b
25840 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f  e compiled, enco
25850 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72  ded.** as either
25860 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
25870 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70  .  The sqlite3_p
25880 72 65 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c  repare() and sql
25890 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
258a0 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  ).** interfaces 
258b0 75 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73  use UTF-8, and s
258c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
258d0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
258e0 72 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a  repare16_v2().**
258f0 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a   use UTF-16..**.
25900 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65  ** ^If the nByte
25910 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 73   argument is les
25920 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65  s than zero, the
25930 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75  n zSql is read u
25940 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73  p to the.** firs
25950 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  t zero terminato
25960 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20  r. ^If nByte is 
25970 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
25980 65 6e 20 69 74 20 69 73 20 74 68 65 20 6d 61 78  en it is the max
25990 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f  imum.** number o
259a0 66 20 20 62 79 74 65 73 20 72 65 61 64 20 66 72  f  bytes read fr
259b0 6f 6d 20 7a 53 71 6c 2e 20 20 5e 57 68 65 6e 20  om zSql.  ^When 
259c0 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67  nByte is non-neg
259d0 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53  ative, the.** zS
259e0 71 6c 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61  ql string ends a
259f0 74 20 65 69 74 68 65 72 20 74 68 65 20 66 69 72  t either the fir
25a00 73 74 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75  st '\000' or '\u
25a10 30 30 30 30 27 20 63 68 61 72 61 63 74 65 72 20  0000' character 
25a20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d  or.** the nByte-
25a30 74 68 20 62 79 74 65 2c 20 77 68 69 63 68 65 76  th byte, whichev
25a40 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20  er comes first. 
25a50 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e  If the caller kn
25a60 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  ows.** that the 
25a70 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20  supplied string 
25a80 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65  is nul-terminate
25a90 64 2c 20 74 68 65 6e 20 74 68 65 72 65 20 69 73  d, then there is
25aa0 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66   a small.** perf
25ab0 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67  ormance advantag
25ac0 65 20 74 6f 20 62 65 20 67 61 69 6e 65 64 20 62  e to be gained b
25ad0 79 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79  y passing an nBy
25ae0 74 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61  te parameter tha
25af0 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f  t.** is equal to
25b00 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
25b10 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75  ytes in the inpu
25b20 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c  t string <i>incl
25b30 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65  uding</i>.** the
25b40 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20   nul-terminator 
25b50 62 79 74 65 73 20 61 73 20 74 68 69 73 20 73 61  bytes as this sa
25b60 76 65 73 20 53 51 4c 69 74 65 20 66 72 6f 6d 20  ves SQLite from 
25b70 68 61 76 69 6e 67 20 74 6f 0a 2a 2a 20 6d 61 6b  having to.** mak
25b80 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  e a copy of the 
25b90 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 0a 2a 2a  input string..**
25ba0 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69  .** ^If pzTail i
25bb0 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20  s not NULL then 
25bc0 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20  *pzTail is made 
25bd0 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20  to point to the 
25be0 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61  first byte.** pa
25bf0 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68  st the end of th
25c00 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74  e first SQL stat
25c10 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20  ement in zSql.  
25c20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  These routines o
25c30 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74  nly.** compile t
25c40 68 65 20 66 69 72 73 74 20 73 74 61 74 65 6d 65  he first stateme
25c50 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a  nt in zSql, so *
25c60 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70  pzTail is left p
25c70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68  ointing to.** wh
25c80 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d  at remains uncom
25c90 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70  piled..**.** ^*p
25ca0 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f  pStmt is left po
25cb0 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70  inting to a comp
25cc0 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73  iled [prepared s
25cd0 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63  tatement] that c
25ce0 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65  an be.** execute
25cf0 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
25d00 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74  _step()].  ^If t
25d10 68 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72  here is an error
25d20 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  , *ppStmt is set
25d30 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49  .** to NULL.  ^I
25d40 66 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74  f the input text
25d50 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c   contains no SQL
25d60 20 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69   (if the input i
25d70 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74  s an empty.** st
25d80 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e  ring or a commen
25d90 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20  t) then *ppStmt 
25da0 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a  is set to NULL..
25db0 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70  ** The calling p
25dc0 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70  rocedure is resp
25dd0 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65  onsible for dele
25de0 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65  ting the compile
25df0 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  d.** SQL stateme
25e00 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  nt using [sqlite
25e10 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66  3_finalize()] af
25e20 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73  ter it has finis
25e30 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20  hed with it..** 
25e40 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62  ppStmt may not b
25e50 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f  e NULL..**.** ^O
25e60 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65 20 73  n success, the s
25e70 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
25e80 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69   family of routi
25e90 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  nes return [SQLI
25ea0 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72  TE_OK];.** other
25eb0 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63  wise an [error c
25ec0 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
25ed0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
25ee0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
25ef0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
25f00 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65  pare16_v2() inte
25f10 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65  rfaces are.** re
25f20 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c  commended for al
25f30 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20  l new programs. 
25f40 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e  The two older in
25f50 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74  terfaces are ret
25f60 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63  ained.** for bac
25f70 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
25f80 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20  lity, but their 
25f90 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67  use is discourag
25fa0 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22  ed..** ^In the "
25fb0 76 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20  v2" interfaces, 
25fc0 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
25fd0 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69  tement.** that i
25fe0 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20  s returned (the 
25ff0 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f  [sqlite3_stmt] o
26000 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20  bject) contains 
26010 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
26020 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65   original SQL te
26030 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20  xt. This causes 
26040 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
26050 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74  p()] interface t
26060 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66  o.** behave diff
26070 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65  erently in three
26080 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   ways:.**.** <ol
26090 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66  >.** <li>.** ^If
260a0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63   the database sc
260b0 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e  hema changes, in
260c0 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69  stead of returni
260d0 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  ng [SQLITE_SCHEM
260e0 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61  A] as it.** alwa
260f0 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b  ys used to do, [
26100 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
26110 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c  will automatical
26120 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65  ly recompile the
26130 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   SQL.** statemen
26140 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e  t and try to run
26150 20 69 74 20 61 67 61 69 6e 2e 20 41 73 20 6d 61   it again. As ma
26160 6e 79 20 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41  ny as [SQLITE_MA
26170 58 5f 53 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a  X_SCHEMA_RETRY].
26180 2a 2a 20 72 65 74 72 69 65 73 20 77 69 6c 6c 20  ** retries will 
26190 6f 63 63 75 72 20 62 65 66 6f 72 65 20 73 71 6c  occur before sql
261a0 69 74 65 33 5f 73 74 65 70 28 29 20 67 69 76 65  ite3_step() give
261b0 73 20 75 70 20 61 6e 64 20 72 65 74 75 72 6e 73  s up and returns
261c0 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f   an error..** </
261d0 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a  li>.**.** <li>.*
261e0 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72  * ^When an error
261f0 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65   occurs, [sqlite
26200 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72  3_step()] will r
26210 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65  eturn one of the
26220 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72   detailed.** [er
26230 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65  ror codes] or [e
26240 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
26250 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61  des].  ^The lega
26260 63 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20  cy behavior was 
26270 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  that.** [sqlite3
26280 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f  _step()] would o
26290 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e  nly return a gen
262a0 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52  eric [SQLITE_ERR
262b0 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a  OR] result code.
262c0 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69  ** and the appli
262d0 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76  cation would hav
262e0 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f  e to make a seco
262f0 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nd call to [sqli
26300 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20  te3_reset()].** 
26310 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64  in order to find
26320 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
26330 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f  cause of the pro
26340 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22  blem. With the "
26350 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69  v2" prepare.** i
26360 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75  nterfaces, the u
26370 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e  nderlying reason
26380 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69   for the error i
26390 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64  s returned immed
263a0 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e  iately..** </li>
263b0 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e  .**.** <li>.** ^
263c0 49 66 20 74 68 65 20 73 70 65 63 69 66 69 63 20  If the specific 
263d0 76 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b  value bound to [
263e0 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74  parameter | host
263f0 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74   parameter] in t
26400 68 65 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61  he .** WHERE cla
26410 75 73 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65  use might influe
26420 6e 63 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f  nce the choice o
26430 66 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72  f query plan for
26440 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a   a statement,.**
26450 20 74 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d   then the statem
26460 65 6e 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f  ent will be auto
26470 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70  matically recomp
26480 69 6c 65 64 2c 20 61 73 20 69 66 20 74 68 65 72  iled, as if ther
26490 65 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61  e had been .** a
264a0 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20   schema change, 
264b0 6f 6e 20 74 68 65 20 66 69 72 73 74 20 20 5b 73  on the first  [s
264c0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63  qlite3_step()] c
264d0 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e  all following an
264e0 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74  y change.** to t
264f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
26500 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73  _text | bindings
26510 5d 20 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d  ] of that [param
26520 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20  eter]. .** ^The 
26530 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f  specific value o
26540 66 20 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b  f WHERE-clause [
26550 70 61 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74  parameter] might
26560 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a   influence the .
26570 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65  ** choice of que
26580 72 79 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70  ry plan if the p
26590 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
265a0 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f  left-hand side o
265b0 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72  f a [LIKE].** or
265c0 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72   [GLOB] operator
265d0 20 6f 72 20 69 66 20 74 68 65 20 70 61 72 61 6d   or if the param
265e0 65 74 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64  eter is compared
265f0 20 74 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63   to an indexed c
26600 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65  olumn.** and the
26610 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
26620 53 54 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74  STAT3] compile-t
26630 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e  ime option is en
26640 61 62 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  abled..** </li>.
26650 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20  ** </ol>.*/.int 
26660 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
26670 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
26680 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
26690 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
266a0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
266b0 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
266c0 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
266d0 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
266e0 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
266f0 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
26700 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
26710 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
26720 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
26730 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
26740 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
26750 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
26760 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
26770 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
26780 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
26790 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
267a0 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
267b0 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  re_v2(.  sqlite3
267c0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
267d0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
267e0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
267f0 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  har *zSql,      
26800 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
26810 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  t, UTF-8 encoded
26820 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
26830 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
26840 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
26850 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
26860 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
26870 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
26880 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
26890 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
268a0 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
268b0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
268c0 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
268d0 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
268e0 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
268f0 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71  _prepare16(.  sq
26900 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
26910 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
26920 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
26930 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
26940 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
26950 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
26960 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
26970 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
26980 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
26990 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
269a0 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
269b0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
269c0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
269d0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
269e0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
269f0 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
26a00 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
26a10 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
26a20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
26a30 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
26a40 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
26a50 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
26a60 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
26a70 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
26a80 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
26a90 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
26aa0 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
26ab0 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
26ac0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
26ad0 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
26ae0 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
26af0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
26b00 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
26b10 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
26b20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
26b30 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
26b40 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
26b50 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
26b60 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
26b70 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
26b80 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20  REF: Retrieving 
26b90 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a  Statement SQL.**
26ba0 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66  .** ^This interf
26bb0 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ace can be used 
26bc0 74 6f 20 72 65 74 72 69 65 76 65 20 61 20 73 61  to retrieve a sa
26bd0 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ved copy of the 
26be0 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20  original.** SQL 
26bf0 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 72 65  text used to cre
26c00 61 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20  ate a [prepared 
26c10 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68  statement] if th
26c20 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73  at statement was
26c30 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69  .** compiled usi
26c40 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  ng either [sqlit
26c50 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
26c60 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
26c70 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f  pare16_v2()]..*/
26c80 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
26c90 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33  ite3_sql(sqlite3
26ca0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
26cb0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
26cc0 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20  Determine If An 
26cd0 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72  SQL Statement Wr
26ce0 69 74 65 73 20 54 68 65 20 44 61 74 61 62 61 73  ites The Databas
26cf0 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  e.**.** ^The sql
26d00 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
26d10 6c 79 28 58 29 20 69 6e 74 65 72 66 61 63 65 20  ly(X) interface 
26d20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f  returns true (no
26d30 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e  n-zero) if.** an
26d40 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70  d only if the [p
26d50 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
26d60 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69  t] X makes no di
26d70 72 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a  rect changes to.
26d80 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  ** the content o
26d90 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  f the database f
26da0 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ile..**.** Note 
26db0 74 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f  that [applicatio
26dc0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
26dd0 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b  nctions] or.** [
26de0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20  virtual tables] 
26df0 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74 68 65  might change the
26e00 20 64 61 74 61 62 61 73 65 20 69 6e 64 69 72 65   database indire
26e10 63 74 6c 79 20 61 73 20 61 20 73 69 64 65 20 65  ctly as a side e
26e20 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f  ffect.  .** ^(Fo
26e30 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e  r example, if an
26e40 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
26e50 69 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20  ines a function 
26e60 22 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a  "eval()" that .*
26e70 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33  * calls [sqlite3
26e80 5f 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74  _exec()], then t
26e90 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c  he following SQL
26ea0 20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64   statement would
26eb0 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64  .** change the d
26ec0 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 72  atabase file thr
26ed0 6f 75 67 68 20 73 69 64 65 2d 65 66 66 65 63 74  ough side-effect
26ee0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
26ef0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
26f00 20 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45   SELECT eval('DE
26f10 4c 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46  LETE FROM t1') F
26f20 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65  ROM t2;.** </pre
26f30 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
26f40 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65  *.** But because
26f50 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74   the [SELECT] st
26f60 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74  atement does not
26f70 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
26f80 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72  base file.** dir
26f90 65 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73  ectly, sqlite3_s
26fa0 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77  tmt_readonly() w
26fb0 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72  ould still retur
26fc0 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  n true.)^.**.** 
26fd0 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e  ^Transaction con
26fe0 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20  trol statements 
26ff0 73 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c  such as [BEGIN],
27000 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c   [COMMIT], [ROLL
27010 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50  BACK],.** [SAVEP
27020 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45  OINT], and [RELE
27030 41 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74  ASE] cause sqlit
27040 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
27050 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75  () to return tru
27060 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20  e,.** since the 
27070 73 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73  statements thems
27080 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74  elves do not act
27090 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65  ually modify the
270a0 20 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a   database but.**
270b0 20 72 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e   rather they con
270c0 74 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20  trol the timing 
270d0 6f 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74  of when other st
270e0 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20  atements modify 
270f0 74 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65  the .** database
27100 2e 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d  .  ^The [ATTACH]
27110 20 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74   and [DETACH] st
27120 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61  atements also ca
27130 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  use.** sqlite3_s
27140 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74  tmt_readonly() t
27150 6f 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 69  o return true si
27160 6e 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65  nce, while those
27170 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63   statements.** c
27180 68 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67  hange the config
27190 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74  uration of a dat
271a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
271b0 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61  , they do not ma
271c0 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ke .** changes t
271d0 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  o the content of
271e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
271f0 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a  les on disk..*/.
27200 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  int sqlite3_stmt
27210 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65  _readonly(sqlite
27220 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
27230 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
27240 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20   Determine If A 
27250 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
27260 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65 73 65  nt Has Been Rese
27270 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
27280 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53  ite3_stmt_busy(S
27290 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
272a0 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65  rns true (non-ze
272b0 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70  ro) if the.** [p
272c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
272d0 74 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73 74  t] S has been st
272e0 65 70 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f  epped at least o
272f0 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73  nce using .** [s
27300 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
27310 62 75 74 20 68 61 73 20 6e 6f 74 20 72 75 6e 20  but has not run 
27320 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e  to completion an
27330 64 2f 6f 72 20 68 61 73 20 6e 6f 74 20 0a 2a 2a  d/or has not .**
27340 20 62 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e   been reset usin
27350 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
27360 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69  (S)].  ^The sqli
27370 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29  te3_stmt_busy(S)
27380 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65  .** interface re
27390 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53  turns false if S
273a0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
273b0 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74  er.  If S is not
273c0 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e   a .** NULL poin
273d0 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ter and is not a
273e0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61   pointer to a va
273f0 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  lid [prepared st
27400 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65  atement].** obje
27410 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  ct, then the beh
27420 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
27430 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20  ed and probably 
27440 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a  undesirable..**.
27450 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
27460 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e  e can be used in
27470 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71   combination [sq
27480 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
27490 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20  )].** to locate 
274a0 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74 61  all prepared sta
274b0 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74  tements associat
274c0 65 64 20 77 69 74 68 20 61 20 64 61 74 61 62 61  ed with a databa
274d0 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  se .** connectio
274e0 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65  n that are in ne
274f0 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65  ed of being rese
27500 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65 20  t.  This can be 
27510 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61  used,.** for exa
27520 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73  mple, in diagnos
27530 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  tic routines to 
27540 73 65 61 72 63 68 20 66 6f 72 20 70 72 65 70 61  search for prepa
27550 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  red .** statemen
27560 74 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64  ts that are hold
27570 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ing a transactio
27580 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73  n open..*/.int s
27590 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79  qlite3_stmt_busy
275a0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
275b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
275c0 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79  : Dynamically Ty
275d0 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74  ped Value Object
275e0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70  .** KEYWORDS: {p
275f0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
27600 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65  _value} {unprote
27610 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
27620 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ue}.**.** SQLite
27630 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65   uses the sqlite
27640 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74  3_value object t
27650 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20  o represent all 
27660 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63  values.** that c
27670 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20  an be stored in 
27680 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  a database table
27690 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79  . SQLite uses dy
276a0 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20  namic typing.** 
276b0 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69  for the values i
276c0 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75  t stores.  ^Valu
276d0 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c  es stored in sql
276e0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
276f0 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74  ts.** can be int
27700 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20  egers, floating 
27710 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74  point values, st
27720 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72  rings, BLOBs, or
27730 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20   NULL..**.** An 
27740 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
27750 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68  ject may be eith
27760 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f  er "protected" o
27770 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e  r "unprotected".
27780 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61  .** Some interfa
27790 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72  ces require a pr
277a0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
277b0 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e  value.  Other in
277c0 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c  terfaces.** will
277d0 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61   accept either a
277e0 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e   protected or an
277f0 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
27800 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45  ite3_value..** E
27810 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74  very interface t
27820 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69  hat accepts sqli
27830 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65  te3_value argume
27840 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  nts specifies.**
27850 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
27860 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72  it requires a pr
27870 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
27880 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  value..**.** The
27890 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65   terms "protecte
278a0 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63  d" and "unprotec
278b0 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68  ted" refer to wh
278c0 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20  ether or not.** 
278d0 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e  a mutex is held.
278e0 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75    An internal mu
278f0 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20  tex is held for 
27900 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  a protected.** s
27910 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
27920 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78  ect but no mutex
27930 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20   is held for an 
27940 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
27950 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
27960 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20  ect.  If SQLite 
27970 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62  is compiled to b
27980 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65  e single-threade
27990 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49  d.** (with [SQLI
279a0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
279b0 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74   and with [sqlit
279c0 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d  e3_threadsafe()]
279d0 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a   returning 0).**
279e0 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73   or if SQLite is
279f0 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72   run in one of r
27a00 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64  educed mutex mod
27a10 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  es .** [SQLITE_C
27a20 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
27a30 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  AD] or [SQLITE_C
27a40 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
27a50 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65  D].** then there
27a60 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69   is no distincti
27a70 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65  on between prote
27a80 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65  cted and unprote
27a90 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
27aa0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e  value objects an
27ab0 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73  d they can be us
27ac0 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62  ed interchangeab
27ad0 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  ly.  However,.**
27ae0 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64   for maximum cod
27af0 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74  e portability it
27b00 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
27b10 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
27b20 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20  s.** still make 
27b30 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20  the distinction 
27b40 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65  between protecte
27b50 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65  d and unprotecte
27b60 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
27b70 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20  ue objects even 
27b80 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c  when not strictl
27b90 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  y required..**.*
27ba0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
27bb0 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61  alue objects tha
27bc0 74 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20  t are passed as 
27bd0 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20  parameters into 
27be0 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
27bf0 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63  ation of [applic
27c00 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
27c10 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65  L functions] are
27c20 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e   protected..** ^
27c30 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
27c40 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  e object returne
27c50 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
27c60 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
27c70 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e   is unprotected.
27c80 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20  .** Unprotected 
27c90 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
27ca0 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62  jects may only b
27cb0 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b  e used with.** [
27cc0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
27cd0 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  alue()] and [sql
27ce0 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
27cf0 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  )]..** The [sqli
27d00 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c  te3_value_blob |
27d10 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
27d20 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66  ype()] family of
27d30 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72  .** interfaces r
27d40 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64  equire protected
27d50 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
27d60 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64  bjects..*/.typed
27d70 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71  ef struct Mem sq
27d80 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a  lite3_value;../*
27d90 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51  .** CAPI3REF: SQ
27da0 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  L Function Conte
27db0 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  xt Object.**.** 
27dc0 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77  The context in w
27dd0 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63  hich an SQL func
27de0 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73  tion executes is
27df0 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a   stored in an.**
27e00 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
27e10 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69   object.  ^A poi
27e20 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74  nter to an sqlit
27e30 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
27e40 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66  t.** is always f
27e50 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
27e60 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  o [application-d
27e70 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
27e80 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70  ions]..** The ap
27e90 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
27ea0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  d SQL function i
27eb0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
27ec0 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20  ll pass this.** 
27ed0 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20  pointer through 
27ee0 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73  into calls to [s
27ef0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
27f00 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75  t | sqlite3_resu
27f10 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  lt()],.** [sqlit
27f20 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
27f30 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65  text()], [sqlite
27f40 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a  3_user_data()],.
27f50 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ** [sqlite3_cont
27f60 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d  ext_db_handle()]
27f70 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  , [sqlite3_get_a
27f80 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e  uxdata()],.** an
27f90 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65  d/or [sqlite3_se
27fa0 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f  t_auxdata()]..*/
27fb0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
27fc0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
27fd0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b  sqlite3_context;
27fe0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
27ff0 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73  : Binding Values
28000 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61   To Prepared Sta
28010 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f  tements.** KEYWO
28020 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d  RDS: {host param
28030 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61  eter} {host para
28040 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61  meters} {host pa
28050 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a  rameter name}.**
28060 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20   KEYWORDS: {SQL 
28070 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20  parameter} {SQL 
28080 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72  parameters} {par
28090 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a  ameter binding}.
280a0 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53  **.** ^(In the S
280b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  QL statement tex
280c0 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  t input to [sqli
280d0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
280e0 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e  ] and its varian
280f0 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20  ts,.** literals 
28100 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20  may be replaced 
28110 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d  by a [parameter]
28120 20 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e   that matches on
28130 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a  e of following.*
28140 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a  * templates:.**.
28150 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
28160 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e   ?.** <li>  ?NNN
28170 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a  .** <li>  :VVV.*
28180 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20  * <li>  @VVV.** 
28190 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f  <li>  $VVV.** </
281a0 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65  ul>.**.** In the
281b0 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65   templates above
281c0 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73  , NNN represents
281d0 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65   an integer lite
281e0 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20  ral,.** and VVV 
281f0 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c  represents an al
28200 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74  phanumeric ident
28210 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76  ifier.)^  ^The v
28220 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a  alues of these.*
28230 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c  * parameters (al
28240 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20  so called "host 
28250 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22  parameter names"
28260 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74   or "SQL paramet
28270 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20  ers").** can be 
28280 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71  set using the sq
28290 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
282a0 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20  outines defined 
282b0 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  here..**.** ^The
282c0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
282d0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  to the sqlite3_b
282e0 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
282f0 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20   is always.** a 
28300 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
28310 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
28320 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72  ject returned fr
28330 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  om.** [sqlite3_p
28340 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
28350 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a  its variants..**
28360 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  .** ^The second 
28370 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
28380 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c  index of the SQL
28390 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65   parameter to be
283a0 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65   set..** ^The le
283b0 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d  ftmost SQL param
283c0 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65  eter has an inde
283d0 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74  x of 1.  ^When t
283e0 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a  he same named.**
283f0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69   SQL parameter i
28400 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e  s used more than
28410 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e   once, second an
28420 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20  d subsequent.** 
28430 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65  occurrences have
28440 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20   the same index 
28450 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63  as the first occ
28460 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65  urrence..** ^The
28470 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64   index for named
28480 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20   parameters can 
28490 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69  be looked up usi
284a0 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
284b0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
284c0 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69  r_index()] API i
284d0 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65  f desired.  ^The
284e0 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f   index.** for "?
284f0 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20  NNN" parameters 
28500 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
28510 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e  NNN..** ^The NNN
28520 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62   value must be b
28530 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65  etween 1 and the
28540 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
28550 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  )].** parameter 
28560 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  [SQLITE_LIMIT_VA
28570 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28  RIABLE_NUMBER] (
28580 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39  default value: 9
28590 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  99)..**.** ^The 
285a0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
285b0 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62  s the value to b
285c0 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d  ind to the param
285d0 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  eter..** ^If the
285e0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
285f0 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
28600 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74  _text() or sqlit
28610 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29  e3_bind_text16()
28620 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  .** or sqlite3_b
28630 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 61 20  ind_blob() is a 
28640 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
28650 6e 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  n the fourth par
28660 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69 67 6e  ameter.** is ign
28670 6f 72 65 64 20 61 6e 64 20 74 68 65 20 65 6e 64  ored and the end
28680 20 72 65 73 75 6c 74 20 69 73 20 74 68 65 20 73   result is the s
28690 61 6d 65 20 61 73 20 73 71 6c 69 74 65 33 5f 62  ame as sqlite3_b
286a0 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a  ind_null()..**.*
286b0 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75  * ^(In those rou
286c0 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 20  tines that have 
286d0 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  a fourth argumen
286e0 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 20  t, its value is 
286f0 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
28700 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 70 61   bytes in the pa
28710 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20  rameter.  To be 
28720 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65  clear: the value
28730 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   is the.** numbe
28740 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75  r of <u>bytes</u
28750 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20  > in the value, 
28760 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  not the number o
28770 66 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a  f characters.)^.
28780 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74  ** ^If the fourt
28790 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
287a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
287b0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  () or sqlite3_bi
287c0 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 69  nd_text16().** i
287d0 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
287e0 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74   the length of t
287f0 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20  he string is.** 
28800 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
28810 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69  tes up to the fi
28820 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  rst zero termina
28830 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66  tor..** If the f
28840 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
28850 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
28860 62 6c 6f 62 28 29 20 69 73 20 6e 65 67 61 74 69  blob() is negati
28870 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ve, then.** the 
28880 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
28890 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e  fined..** If a n
288a0 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72  on-negative four
288b0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
288c0 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69  provided to sqli
288d0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a  te3_bind_text().
288e0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  ** or sqlite3_bi
288f0 6e 64 5f 74 65 78 74 31 36 28 29 20 74 68 65 6e  nd_text16() then
28900 20 74 68 61 74 20 70 61 72 61 6d 65 74 65 72 20   that parameter 
28910 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74 65  must be the byte
28920 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65   offset.** where
28930 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61   the NUL termina
28940 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20  tor would occur 
28950 61 73 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72  assuming the str
28960 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20  ing were NUL.** 
28970 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20  terminated.  If 
28980 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65  any NUL characte
28990 72 73 20 6f 63 63 75 72 20 61 74 20 62 79 74 65  rs occur at byte
289a0 20 6f 66 66 73 65 74 73 20 6c 65 73 73 20 74 68   offsets less th
289b0 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65  an .** the value
289c0 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   of the fourth p
289d0 61 72 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68  arameter then th
289e0 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69  e resulting stri
289f0 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a  ng value will.**
28a00 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65   contain embedde
28a10 64 20 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73  d NULs.  The res
28a20 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f  ult of expressio
28a30 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72  ns involving str
28a40 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62  ings.** with emb
28a50 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e  edded NULs is un
28a60 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
28a70 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  The fifth argume
28a80 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  nt to sqlite3_bi
28a90 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74  nd_blob(), sqlit
28aa0 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20  e3_bind_text(), 
28ab0 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62  and.** sqlite3_b
28ac0 69 6e 64 5f 74 65 78 74 31 36 28 29 20 69 73 20  ind_text16() is 
28ad0 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 65  a destructor use
28ae0 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20  d to dispose of 
28af0 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73  the BLOB or.** s
28b00 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69  tring after SQLi
28b10 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  te has finished 
28b20 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64  with it.  ^The d
28b30 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c  estructor is cal
28b40 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73  led.** to dispos
28b50 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72  e of the BLOB or
28b60 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20   string even if 
28b70 74 68 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  the call to sqli
28b80 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c  te3_bind_blob(),
28b90 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  .** sqlite3_bind
28ba0 5f 74 65 78 74 28 29 2c 20 6f 72 20 73 71 6c 69  _text(), or sqli
28bb0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
28bc0 29 20 66 61 69 6c 73 2e 20 20 0a 2a 2a 20 5e 49  ) fails.  .** ^I
28bd0 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75  f the fifth argu
28be0 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73  ment is.** the s
28bf0 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51  pecial value [SQ
28c00 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68  LITE_STATIC], th
28c10 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65  en SQLite assume
28c20 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e  s that the.** in
28c30 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20  formation is in 
28c40 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65  static, unmanage
28c50 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73  d space and does
28c60 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
28c70 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68  freed..** ^If th
28c80 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
28c90 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b   has the value [
28ca0 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
28cb0 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74  ], then.** SQLit
28cc0 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20  e makes its own 
28cd0 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
28ce0 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61  the data immedia
28cf0 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20  tely, before.** 
28d00 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
28d10 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  _*() routine ret
28d20 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  urns..**.** ^The
28d30 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
28d40 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65  roblob() routine
28d50 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66   binds a BLOB of
28d60 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a   length N that.*
28d70 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  * is filled with
28d80 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72   zeroes.  ^A zer
28d90 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78  oblob uses a fix
28da0 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d  ed amount of mem
28db0 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20  ory.** (just an 
28dc0 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20  integer to hold 
28dd0 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20  its size) while 
28de0 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63  it is being proc
28df0 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c  essed..** Zerobl
28e00 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  obs are intended
28e10 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61   to serve as pla
28e20 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c  ceholders for BL
28e30 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e  OBs whose.** con
28e40 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72  tent is later wr
28e50 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  itten using.** [
28e60 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
28e70 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20  n | incremental 
28e80 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e  BLOB I/O] routin
28e90 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69  es..** ^A negati
28ea0 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65  ve value for the
28eb0 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74   zeroblob result
28ec0 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67  s in a zero-leng
28ed0 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e  th BLOB..**.** ^
28ee0 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71  If any of the sq
28ef0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
28f00 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
28f10 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70  ed with a NULL p
28f20 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68  ointer.** for th
28f30 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
28f40 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61  ement] or with a
28f50 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
28f60 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a  ent for which.**
28f70 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
28f80 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65  ] has been calle
28f90 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20  d more recently 
28fa0 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  than [sqlite3_re
28fb0 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20  set()],.** then 
28fc0 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65  the call will re
28fd0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  turn [SQLITE_MIS
28fe0 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71  USE].  If any sq
28ff0 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a  lite3_bind_().**
29000 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73   routine is pass
29010 65 64 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  ed a [prepared s
29020 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68  tatement] that h
29030 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  as been finalize
29040 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  d, the.** result
29050 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
29060 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66  d probably harmf
29070 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69  ul..**.** ^Bindi
29080 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61  ngs are not clea
29090 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  red by the [sqli
290a0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75  te3_reset()] rou
290b0 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e  tine..** ^Unboun
290c0 64 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  d parameters are
290d0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
290e0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  NULL..**.** ^The
290f0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20   sqlite3_bind_* 
29100 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
29110 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
29120 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20  uccess or an.** 
29130 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20  [error code] if 
29140 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72  anything goes wr
29150 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ong..** ^[SQLITE
29160 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72  _RANGE] is retur
29170 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d  ned if the param
29180 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73  eter.** index is
29190 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20   out of range.  
291a0 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20  ^[SQLITE_NOMEM] 
291b0 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d  is returned if m
291c0 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a  alloc() fails..*
291d0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
291e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
291f0 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
29200 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
29210 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
29220 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
29230 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
29240 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e  _index()]..*/.in
29250 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  t sqlite3_bind_b
29260 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
29270 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
29280 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64  id*, int n, void
29290 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
292a0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f   sqlite3_bind_do
292b0 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
292c0 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29  t*, int, double)
292d0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
292e0 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  nd_int(sqlite3_s
292f0 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b  tmt*, int, int);
29300 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
29310 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  d_int64(sqlite3_
29320 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69  stmt*, int, sqli
29330 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20  te3_int64);.int 
29340 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c  sqlite3_bind_nul
29350 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  l(sqlite3_stmt*,
29360 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74   int);.int sqlit
29370 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c  e3_bind_text(sql
29380 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
29390 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
293a0 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  t n, void(*)(voi
293b0 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
293c0 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71  3_bind_text16(sq
293d0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
293e0 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
293f0 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
29400 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
29410 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69  _bind_value(sqli
29420 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
29430 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61  const sqlite3_va
29440 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
29450 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
29460 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
29470 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a  int, int n);../*
29480 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
29490 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61  mber Of SQL Para
294a0 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  meters.**.** ^Th
294b0 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62  is routine can b
294c0 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74  e used to find t
294d0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51  he number of [SQ
294e0 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a  L parameters].**
294f0 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   in a [prepared 
29500 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c  statement].  SQL
29510 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
29520 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a  tokens of the.**
29530 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e   form "?", "?NNN
29540 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41  ", ":AAA", "$AAA
29550 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61  ", or "@AAA" tha
29560 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c  t serve as.** pl
29570 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76  aceholders for v
29580 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b  alues that are [
29590 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
295a0 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f  b | bound].** to
295b0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20   the parameters 
295c0 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e  at a later time.
295d0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f  .**.** ^(This ro
295e0 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72  utine actually r
295f0 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78  eturns the index
29600 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20   of the largest 
29610 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70  (rightmost).** p
29620 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c  arameter. For al
29630 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f  l forms except ?
29640 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63  NNN, this will c
29650 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65  orrespond to the
29660 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e  .** number of un
29670 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e  ique parameters.
29680 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20    If parameters 
29690 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d  of the ?NNN form
296a0 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68   are used,.** th
296b0 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20  ere may be gaps 
296c0 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a  in the list.)^.*
296d0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
296e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
296f0 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
29700 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
29710 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
29720 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  me()], and.** [s
29730 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
29740 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
29750 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
29760 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
29770 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
29780 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
29790 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48  REF: Name Of A H
297a0 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a  ost Parameter.**
297b0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
297c0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
297d0 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66  name(P,N) interf
297e0 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  ace returns.** t
297f0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e  he name of the N
29800 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74  -th [SQL paramet
29810 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70  er] in the [prep
29820 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
29830 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61  P..** ^(SQL para
29840 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f  meters of the fo
29850 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41  rm "?NNN" or ":A
29860 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72  AA" or "@AAA" or
29870 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20   "$AAA".** have 
29880 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20  a name which is 
29890 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e  the string "?NNN
298a0 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22  " or ":AAA" or "
298b0 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a  @AAA" or "$AAA".
298c0 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  ** respectively.
298d0 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
298e0 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20  ds, the initial 
298f0 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40  ":" or "$" or "@
29900 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69  " or "?".** is i
29910 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20  ncluded as part 
29920 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a  of the name.)^.*
29930 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66  * ^Parameters of
29940 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69   the form "?" wi
29950 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e  thout a followin
29960 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e  g integer have n
29970 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72  o name.** and ar
29980 65 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73  e referred to as
29990 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22   "nameless" or "
299a0 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65  anonymous parame
299b0 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ters"..**.** ^Th
299c0 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72  e first host par
299d0 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
299e0 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e  dex of 1, not 0.
299f0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76  .**.** ^If the v
29a00 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66  alue N is out of
29a10 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65   range or if the
29a20 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20   N-th parameter 
29a30 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20  is.** nameless, 
29a40 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74  then NULL is ret
29a50 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74  urned.  ^The ret
29a60 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a  urned string is.
29a70 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46  ** always in UTF
29a80 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e  -8 encoding even
29a90 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61   if the named pa
29aa0 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f  rameter was.** o
29ab0 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66  riginally specif
29ac0 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  ied as UTF-16 in
29ad0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
29ae0 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  e16()] or.** [sq
29af0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
29b00 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  v2()]..**.** See
29b10 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
29b20 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
29b30 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
29b40 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
29b50 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20  meter_count()], 
29b60 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
29b70 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
29b80 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73  ndex()]..*/.cons
29b90 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
29ba0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
29bb0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
29bc0 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *, int);../*.** 
29bd0 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20  CAPI3REF: Index 
29be0 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57  Of A Parameter W
29bf0 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65  ith A Given Name
29c00 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74  .**.** ^Return t
29c10 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53  he index of an S
29c20 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76  QL parameter giv
29c30 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54  en its name.  ^T
29c40 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75  he.** index valu
29c50 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75  e returned is su
29c60 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61  itable for use a
29c70 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  s the second.** 
29c80 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
29c90 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
29ca0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e  sqlite3_bind()].
29cb0 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20    ^A zero.** is 
29cc0 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d  returned if no m
29cd0 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65  atching paramete
29ce0 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68  r is found.  ^Th
29cf0 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e  e parameter.** n
29d00 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65  ame must be give
29d10 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20  n in UTF-8 even 
29d20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  if the original 
29d30 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73  statement.** was
29d40 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55   prepared from U
29d50 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67  TF-16 text using
29d60 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
29d70 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
29d80 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
29d90 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
29da0 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
29db0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
29dc0 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
29dd0 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
29de0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
29df0 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
29e00 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
29e10 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
29e20 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
29e30 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
29e40 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  e);../*.** CAPI3
29e50 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42  REF: Reset All B
29e60 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65  indings On A Pre
29e70 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a  pared Statement.
29e80 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20  **.** ^Contrary 
29e90 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e  to the intuition
29ea0 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74   of many, [sqlit
29eb0 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73  e3_reset()] does
29ec0 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68   not reset.** th
29ed0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
29ee0 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d  blob | bindings]
29ef0 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   on a [prepared 
29f00 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
29f10 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  Use this routine
29f20 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f   to reset all ho
29f30 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  st parameters to
29f40 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71   NULL..*/.int sq
29f50 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64  lite3_clear_bind
29f60 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ings(sqlite3_stm
29f70 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
29f80 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20  3REF: Number Of 
29f90 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73  Columns In A Res
29fa0 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52  ult Set.**.** ^R
29fb0 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72  eturn the number
29fc0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
29fd0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65  he result set re
29fe0 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a  turned by the.**
29ff0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2a000 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75  ment]. ^This rou
2a010 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69  tine returns 0 i
2a020 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51  f pStmt is an SQ
2a030 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74  L.** statement t
2a040 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74  hat does not ret
2a050 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78  urn data (for ex
2a060 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45  ample an [UPDATE
2a070 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ])..**.** See al
2a080 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74  so: [sqlite3_dat
2a090 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e  a_count()].*/.in
2a0a0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
2a0b0 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
2a0c0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2a0d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
2a0e0 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20  lumn Names In A 
2a0f0 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a  Result Set.**.**
2a100 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
2a110 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65   return the name
2a120 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70   assigned to a p
2a130 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e  articular column
2a140 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c  .** in the resul
2a150 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45  t set of a [SELE
2a160 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  CT] statement.  
2a170 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ^The sqlite3_col
2a180 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e  umn_name().** in
2a190 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2a1a0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a  a pointer to a z
2a1b0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
2a1c0 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61  TF-8 string.** a
2a1d0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
2a1e0 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72  n_name16() retur
2a1f0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2a200 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
2a210 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69  d.** UTF-16 stri
2a220 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20  ng.  ^The first 
2a230 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2a240 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2a250 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d  ment].** that im
2a260 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45  plements the [SE
2a270 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
2a280 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
2a290 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
2a2a0 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20   column number. 
2a2b0 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63   ^The leftmost c
2a2c0 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20  olumn is number 
2a2d0 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65  0..**.** ^The re
2a2e0 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f  turned string po
2a2f0 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75  inter is valid u
2a300 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20  ntil either the 
2a310 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2a320 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72  ent].** is destr
2a330 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  oyed by [sqlite3
2a340 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
2a350 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d  until the statem
2a360 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ent is automatic
2a370 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72  ally.** reprepar
2a380 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
2a390 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2a3a0 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70  _step()] for a p
2a3b0 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a  articular run.**
2a3c0 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65   or until the ne
2a3d0 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71  xt call to.** sq
2a3e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
2a3f0 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  e() or sqlite3_c
2a400 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f  olumn_name16() o
2a410 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d  n the same colum
2a420 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c  n..**.** ^If sql
2a430 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61  ite3_malloc() fa
2a440 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70  ils during the p
2a450 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74  rocessing of eit
2a460 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28  her routine.** (
2a470 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69  for example duri
2a480 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ng a conversion 
2a490 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54  from UTF-8 to UT
2a4a0 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20  F-16) then a.** 
2a4b0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
2a4c0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
2a4d0 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72  ^The name of a r
2a4e0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20  esult column is 
2a4f0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
2a500 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72   "AS" clause for
2a510 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c  .** that column,
2a520 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20   if there is an 
2a530 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74  AS clause.  If t
2a540 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c  here is no AS cl
2a550 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ause.** then the
2a560 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c   name of the col
2a570 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69  umn is unspecifi
2a580 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67  ed and may chang
2a590 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65  e from.** one re
2a5a0 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20  lease of SQLite 
2a5b0 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a  to the next..*/.
2a5c0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
2a5d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
2a5e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2a5f0 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  nt N);.const voi
2a600 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2a610 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
2a620 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  _stmt*, int N);.
2a630 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2a640 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20   Source Of Data 
2a650 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  In A Query Resul
2a660 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  t.**.** ^These r
2a670 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20  outines provide 
2a680 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72  a means to deter
2a690 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62 61 73  mine the databas
2a6a0 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a  e, table, and.**
2a6b0 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
2a6c0 61 74 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e  at is the origin
2a6d0 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61 72   of a particular
2a6e0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69   result column i
2a6f0 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74  n.** [SELECT] st
2a700 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  atement..** ^The
2a710 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
2a720 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f  abase or table o
2a730 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20  r column can be 
2a740 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65  returned as.** e
2a750 69 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72  ither a UTF-8 or
2a760 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20   UTF-16 string. 
2a770 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f   ^The _database_
2a780 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
2a790 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
2a7a0 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c   name, the _tabl
2a7b0 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  e_ routines retu
2a7c0 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d  rn the table nam
2a7d0 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72  e, and.** the or
2a7e0 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72  igin_ routines r
2a7f0 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e  eturn the column
2a800 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72   name..** ^The r
2a810 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
2a820 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68  s valid until th
2a830 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2a840 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f  ement] is destro
2a850 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71  yed.** using [sq
2a860 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2a870 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  ] or until the s
2a880 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f  tatement is auto
2a890 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70  matically.** rep
2a8a0 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66  repared by the f
2a8b0 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  irst call to [sq
2a8c0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f  lite3_step()] fo
2a8d0 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  r a particular r
2a8e0 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74  un.** or until t
2a8f0 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74  he same informat
2a900 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64  ion is requested
2a910 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64  .** again in a d
2a920 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e  ifferent encodin
2a930 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61  g..**.** ^The na
2a940 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65  mes returned are
2a950 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e   the original un
2a960 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f  -aliased names o
2a970 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  f the.** databas
2a980 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f  e, table, and co
2a990 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lumn..**.** ^The
2a9a0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
2a9b0 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  to these interfa
2a9c0 63 65 73 20 69 73 20 61 20 5b 70 72 65 70 61 72  ces is a [prepar
2a9d0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
2a9e0 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f  * ^These functio
2a9f0 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  ns return inform
2aa00 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20  ation about the 
2aa10 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  Nth result colum
2aa20 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  n returned by.**
2aa30 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20   the statement, 
2aa40 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73  where N is the s
2aa50 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61  econd function a
2aa60 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  rgument..** ^The
2aa70 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d   left-most colum
2aa80 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f  n is column 0 fo
2aa90 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  r these routines
2aaa0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2aab0 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  Nth column retur
2aac0 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65  ned by the state
2aad0 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65  ment is an expre
2aae0 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71  ssion or.** subq
2aaf0 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20  uery and is not 
2ab00 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20  a column value, 
2ab10 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73  then all of thes
2ab20 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
2ab30 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68  rn.** NULL.  ^Th
2ab40 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68  ese routine migh
2ab50 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55  t also return NU
2ab60 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61  LL if a memory a
2ab70 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a  llocation error.
2ab80 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68  ** occurs.  ^Oth
2ab90 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74  erwise, they ret
2aba0 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  urn the name of 
2abb0 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74  the attached dat
2abc0 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a  abase, table,.**
2abd0 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20   or column that 
2abe0 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c  query result col
2abf0 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65  umn was extracte
2ac00 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41  d from..**.** ^A
2ac10 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72  s with all other
2ac20 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68   SQLite APIs, th
2ac30 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20  ose whose names 
2ac40 65 6e 64 20 77 69 74 68 20 22 31 36 22 20 72 65  end with "16" re
2ac50 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65  turn.** UTF-16 e
2ac60 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61  ncoded strings a
2ac70 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e  nd the other fun
2ac80 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54  ctions return UT
2ac90 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  F-8..**.** ^Thes
2aca0 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20  e APIs are only 
2acb0 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65  available if the
2acc0 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d   library was com
2acd0 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
2ace0 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
2acf0 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41  _COLUMN_METADATA
2ad00 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C-preprocessor
2ad10 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49   symbol..**.** I
2ad20 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68  f two or more th
2ad30 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f  reads call one o
2ad40 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20  r more of these 
2ad50 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74  routines against
2ad60 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65   the same.** pre
2ad70 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2ad80 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68  and column at th
2ad90 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e  e same time then
2ada0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
2adb0 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  .** undefined..*
2adc0 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d  *.** If two or m
2add0 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c  ore threads call
2ade0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
2adf0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2ae00 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20  database_name | 
2ae10 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20  column metadata 
2ae20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66  interfaces].** f
2ae30 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65  or the same [pre
2ae40 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2ae50 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75   and result colu
2ae60 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d  mn.** at the sam
2ae70 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20  e time then the 
2ae80 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
2ae90 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  fined..*/.const 
2aea0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2aeb0 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
2aec0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
2aed0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
2aee0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2aef0 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31  n_database_name1
2af00 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2af10 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  int);.const char
2af20 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2af30 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69  _table_name(sqli
2af40 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2af50 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2af60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65  te3_column_table
2af70 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
2af80 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
2af90 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2afa0 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
2afb0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
2afc0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
2afd0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2afe0 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28  n_origin_name16(
2aff0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2b000 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2b010 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61  REF: Declared Da
2b020 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72  tatype Of A Quer
2b030 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e  y Result.**.** ^
2b040 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  (The first param
2b050 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61  eter is a [prepa
2b060 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
2b070 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65  ** If this state
2b080 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43  ment is a [SELEC
2b090 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  T] statement and
2b0a0 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
2b0b0 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e  of the.** return
2b0c0 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  ed result set of
2b0d0 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69   that [SELECT] i
2b0e0 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  s a table column
2b0f0 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72   (not an.** expr
2b100 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65  ession or subque
2b110 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63  ry) then the dec
2b120 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68  lared type of th
2b130 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d  e table.** colum
2b140 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  n is returned.)^
2b150 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f    ^If the Nth co
2b160 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75  lumn of the resu
2b170 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20  lt set is an.** 
2b180 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
2b190 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e  bquery, then a N
2b1a0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
2b1b0 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65  eturned..** ^The
2b1c0 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
2b1d0 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38   is always UTF-8
2b1e0 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20   encoded..**.** 
2b1f0 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67  ^(For example, g
2b200 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  iven the databas
2b210 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20  e schema:.**.** 
2b220 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28  CREATE TABLE t1(
2b230 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a  c1 VARIANT);.**.
2b240 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f  ** and the follo
2b250 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74  wing statement t
2b260 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a  o be compiled:.*
2b270 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b  *.** SELECT c1 +
2b280 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a   1, c1 FROM t1;.
2b290 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69  **.** this routi
2b2a0 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20  ne would return 
2b2b0 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49  the string "VARI
2b2c0 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63  ANT" for the sec
2b2d0 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f  ond result.** co
2b2e0 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64  lumn (i==1), and
2b2f0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
2b300 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65  for the first re
2b310 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d  sult column (i==
2b320 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  0).)^.**.** ^SQL
2b330 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
2b340 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67   run-time typing
2b350 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61  .  ^So just beca
2b360 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  use a column.** 
2b370 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63  is declared to c
2b380 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75  ontain a particu
2b390 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f  lar type does no
2b3a0 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a  t mean that the.
2b3b0 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69  ** data stored i
2b3c0 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73  n that column is
2b3d0 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64   of the declared
2b3e0 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69   type.  SQLite i
2b3f0 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79  s.** strongly ty
2b400 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70  ped, but the typ
2b410 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e  ing is dynamic n
2b420 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70  ot static.  ^Typ
2b430 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74  e.** is associat
2b440 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75  ed with individu
2b450 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77  al values, not w
2b460 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65  ith the containe
2b470 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f  rs.** used to ho
2b480 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e  ld those values.
2b490 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
2b4a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
2b4b0 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ecltype(sqlite3_
2b4c0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
2b4d0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2b4e0 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31  column_decltype1
2b4f0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2b500 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
2b510 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20  I3REF: Evaluate 
2b520 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
2b530 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b  .**.** After a [
2b540 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2b550 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65  nt] has been pre
2b560 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68  pared using eith
2b570 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  er.** [sqlite3_p
2b580 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
2b590 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2b5a0 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20  16_v2()] or one 
2b5b0 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  of the legacy.**
2b5c0 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c   interfaces [sql
2b5d0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
2b5e0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
2b5f0 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66  are16()], this f
2b600 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20  unction.** must 
2b610 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72  be called one or
2b620 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65   more times to e
2b630 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74  valuate the stat
2b640 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ement..**.** The
2b650 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20   details of the 
2b660 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20  behavior of the 
2b670 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
2b680 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a  nterface depend.
2b690 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68  ** on whether th
2b6a0 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20  e statement was 
2b6b0 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74  prepared using t
2b6c0 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e  he newer "v2" in
2b6d0 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69  terface.** [sqli
2b6e0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2b6f0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
2b700 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
2b710 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61  r the older lega
2b720 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  cy.** interface 
2b730 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2b740 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2b750 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20  _prepare16()].  
2b760 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a  The use of the.*
2b770 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72  * new "v2" inter
2b780 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e  face is recommen
2b790 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c  ded for new appl
2b7a0 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65  ications but the
2b7b0 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
2b7c0 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e  face will contin
2b7d0 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ue to be support
2b7e0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68  ed..**.** ^In th
2b7f0 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
2b800 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76  ce, the return v
2b810 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74  alue will be eit
2b820 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  her [SQLITE_BUSY
2b830 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f  ],.** [SQLITE_DO
2b840 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57  NE], [SQLITE_ROW
2b850 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ], [SQLITE_ERROR
2b860 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49  ], or [SQLITE_MI
2b870 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20  SUSE]..** ^With 
2b880 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
2b890 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f  ce, any of the o
2b8a0 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64  ther [result cod
2b8b0 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e  es] or.** [exten
2b8c0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
2b8d0 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72  ] might be retur
2b8e0 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a  ned as well..**.
2b8f0 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59  ** ^[SQLITE_BUSY
2b900 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
2b910 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65   database engine
2b920 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61   was unable to a
2b930 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61  cquire the.** da
2b940 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20  tabase locks it 
2b950 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20  needs to do its 
2b960 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74  job.  ^If the st
2b970 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f  atement is a [CO
2b980 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75  MMIT].** or occu
2b990 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e  rs outside of an
2b9a0 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
2b9b0 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20  ction, then you 
2b9c0 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a  can retry the.**
2b9d0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20   statement.  If 
2b9e0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
2b9f0 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20   not a [COMMIT] 
2ba00 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69  and occurs withi
2ba10 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74  n an.** explicit
2ba20 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65   transaction the
2ba30 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c  n you should rol
2ba40 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61  lback the transa
2ba50 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20  ction before.** 
2ba60 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a  continuing..**.*
2ba70 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  * ^[SQLITE_DONE]
2ba80 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
2ba90 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69  statement has fi
2baa0 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67  nished executing
2bab0 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79  .** successfully
2bac0 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
2bad0 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
2bae0 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20  called again on 
2baf0 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20  this virtual.** 
2bb00 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20  machine without 
2bb10 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73  first calling [s
2bb20 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2bb30 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72  to reset the vir
2bb40 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20  tual.** machine 
2bb50 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
2bb60 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  ial state..**.**
2bb70 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61   ^If the SQL sta
2bb80 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65  tement being exe
2bb90 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e  cuted returns an
2bba0 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51  y data, then [SQ
2bbb0 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20  LITE_ROW].** is 
2bbc0 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69  returned each ti
2bbd0 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20  me a new row of 
2bbe0 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f  data is ready fo
2bbf0 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20  r processing by 
2bc00 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54  the.** caller. T
2bc10 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65  he values may be
2bc20 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20   accessed using 
2bc30 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65  the [column acce
2bc40 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a  ss functions]..*
2bc50 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
2bc60 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   is called again
2bc70 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65   to retrieve the
2bc80 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74   next row of dat
2bc90 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  a..**.** ^[SQLIT
2bca0 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74  E_ERROR] means t
2bcb0 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65  hat a run-time e
2bcc0 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20  rror (such as a 
2bcd0 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69  constraint.** vi
2bce0 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63  olation) has occ
2bcf0 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f  urred.  sqlite3_
2bd00 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
2bd10 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
2bd20 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20  n on.** the VM. 
2bd30 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  More information
2bd40 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79   may be found by
2bd50 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
2bd60 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20  3_errmsg()]..** 
2bd70 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79  ^With the legacy
2bd80 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f   interface, a mo
2bd90 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f  re specific erro
2bda0 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d  r code (for exam
2bdb0 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ple,.** [SQLITE_
2bdc0 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c  INTERRUPT], [SQL
2bdd0 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51  ITE_SCHEMA], [SQ
2bde0 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61  LITE_CORRUPT], a
2bdf0 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20  nd so forth).** 
2be00 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20  can be obtained 
2be10 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
2be20 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20  te3_reset()] on 
2be30 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
2be40 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49   statement].  ^I
2be50 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  n the "v2" inter
2be60 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72  face,.** the mor
2be70 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
2be80 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65   code is returne
2be90 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71  d directly by sq
2bea0 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a  lite3_step()..**
2beb0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  .** [SQLITE_MISU
2bec0 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  SE] means that t
2bed0 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  he this routine 
2bee0 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70  was called inapp
2bef0 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50  ropriately..** P
2bf00 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61  erhaps it was ca
2bf10 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61  lled on a [prepa
2bf20 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
2bf30 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61  hat has.** alrea
2bf40 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33  dy been [sqlite3
2bf50 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61  _finalize | fina
2bf60 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65  lized] or on one
2bf70 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65   that had.** pre
2bf80 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64  viously returned
2bf90 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
2bfa0 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  or [SQLITE_DONE]
2bfb0 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a  .  Or it could.*
2bfc0 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68  * be the case th
2bfd0 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  at the same data
2bfe0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2bff0 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79  is being used by
2c000 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20   two or.** more 
2c010 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73  threads at the s
2c020 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69  ame moment in ti
2c030 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c  me..**.** For al
2c040 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  l versions of SQ
2c050 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69  Lite up to and i
2c060 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e  ncluding 3.6.23.
2c070 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  1, a call to.** 
2c080 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2c090 5d 20 77 61 73 20 72 65 71 75 69 72 65 64 20 61  ] was required a
2c0a0 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65  fter sqlite3_ste
2c0b0 70 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79  p() returned any
2c0c0 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74  thing.** other t
2c0d0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  han [SQLITE_ROW]
2c0e0 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73   before any subs
2c0f0 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f  equent invocatio
2c100 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  n of.** sqlite3_
2c110 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65  step().  Failure
2c120 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 70 72   to reset the pr
2c130 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2c140 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69   using .** [sqli
2c150 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75  te3_reset()] wou
2c160 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20  ld result in an 
2c170 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
2c180 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73  return from.** s
2c190 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
2c1a0 42 75 74 20 61 66 74 65 72 20 76 65 72 73 69 6f  But after versio
2c1b0 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69  n 3.6.23.1, sqli
2c1c0 74 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e  te3_step() began
2c1d0 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  .** calling [sql
2c1e0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75  ite3_reset()] au
2c1f0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74  tomatically in t
2c200 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65  his circumstance
2c210 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20   rather.** than 
2c220 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54  returning [SQLIT
2c230 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73  E_MISUSE].  This
2c240 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72   is not consider
2c250 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69  ed a compatibili
2c260 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61  ty.** break beca
2c270 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74  use any applicat
2c280 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 65  ion that ever re
2c290 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45  ceives an SQLITE
2c2a0 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a  _MISUSE error.**
2c2b0 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65   is broken by de
2c2c0 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b  finition.  The [
2c2d0 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f  SQLITE_OMIT_AUTO
2c2e0 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74  RESET] compile-t
2c2f0 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61  ime option.** ca
2c300 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 73  n be used to res
2c310 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 20  tore the legacy 
2c320 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20  behavior..**.** 
2c330 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61  <b>Goofy Interfa
2c340 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e  ce Alert:</b> In
2c350 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
2c360 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74  rface, the sqlit
2c370 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49  e3_step().** API
2c380 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
2c390 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20  a generic error 
2c3a0 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52  code, [SQLITE_ER
2c3b0 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20  ROR], following 
2c3c0 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68  any.** error oth
2c3d0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
2c3e0 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54  BUSY] and [SQLIT
2c3f0 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20  E_MISUSE].  You 
2c400 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71  must call.** [sq
2c410 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
2c420 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
2c430 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20  ize()] in order 
2c440 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74  to find one of t
2c450 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b  he.** specific [
2c460 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61  error codes] tha
2c470 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62  t better describ
2c480 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a  es the error..**
2c490 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74   We admit that t
2c4a0 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64  his is a goofy d
2c4b0 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62  esign.  The prob
2c4c0 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78  lem has been fix
2c4d0 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22  ed.** with the "
2c4e0 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20  v2" interface.  
2c4f0 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61  If you prepare a
2c500 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73  ll of your SQL s
2c510 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69  tatements.** usi
2c520 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  ng either [sqlit
2c530 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2c540 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
2c550 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73  pare16_v2()] ins
2c560 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c  tead.** of the l
2c570 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70  egacy [sqlite3_p
2c580 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73  repare()] and [s
2c590 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2c5a0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a  ()] interfaces,.
2c5b0 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65  ** then the more
2c5c0 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72   specific [error
2c5d0 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75   codes] are retu
2c5e0 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a  rned directly.**
2c5f0 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70   by sqlite3_step
2c600 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20  ().  The use of 
2c610 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
2c620 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ce is recommende
2c630 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
2c640 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73  3_step(sqlite3_s
2c650 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
2c660 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f  PI3REF: Number o
2c670 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72  f columns in a r
2c680 65 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20  esult set.**.** 
2c690 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
2c6a0 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72  a_count(P) inter
2c6b0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
2c6c0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
2c6d0 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72  ns in the.** cur
2c6e0 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20  rent row of the 
2c6f0 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70  result set of [p
2c700 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2c710 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65  t] P..** ^If pre
2c720 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2c730 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  P does not have 
2c740 72 65 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f  results ready to
2c750 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20   return.** (via 
2c760 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71  calls to the [sq
2c770 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
2c780 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d   | sqlite3_colum
2c790 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74  n_*()] of.** int
2c7a0 65 72 66 61 63 65 73 29 20 74 68 65 6e 20 73 71  erfaces) then sq
2c7b0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2c7c0 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a  (P) returns 0..*
2c7d0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
2c7e0 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75  ata_count(P) rou
2c7f0 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e  tine also return
2c800 73 20 30 20 69 66 20 50 20 69 73 20 61 20 4e 55  s 0 if P is a NU
2c810 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e  LL pointer..** ^
2c820 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
2c830 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e  _count(P) routin
2c840 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 74  e returns 0 if t
2c850 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  he previous call
2c860 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
2c870 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65  step](P) returne
2c880 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  d [SQLITE_DONE].
2c890 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64    ^The sqlite3_d
2c8a0 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20  ata_count(P).** 
2c8b0 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d  will return non-
2c8c0 7a 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73  zero if previous
2c8d0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2c8e0 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72  3_step](P) retur
2c8f0 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52  ned.** [SQLITE_R
2c900 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74  OW], except in t
2c910 68 65 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b  he case of the [
2c920 50 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74  PRAGMA increment
2c930 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68  al_vacuum].** wh
2c940 65 72 65 20 69 74 20 61 6c 77 61 79 73 20 72 65  ere it always re
2c950 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65  turns zero since
2c960 20 65 61 63 68 20 73 74 65 70 20 6f 66 20 74 68   each step of th
2c970 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a  at multi-step.**
2c980 20 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20   pragma returns 
2c990 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74  0 columns of dat
2c9a0 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  a..**.** See als
2c9b0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  o: [sqlite3_colu
2c9c0 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69  mn_count()].*/.i
2c9d0 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  nt sqlite3_data_
2c9e0 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
2c9f0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
2ca00 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e  ** CAPI3REF: Fun
2ca10 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70  damental Datatyp
2ca20 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
2ca30 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a  SQLITE_TEXT.**.*
2ca40 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20  * ^(Every value 
2ca50 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e  in SQLite has on
2ca60 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d  e of five fundam
2ca70 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a  ental datatypes:
2ca80 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
2ca90 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65  li> 64-bit signe
2caa0 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69  d integer.** <li
2cab0 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c  > 64-bit IEEE fl
2cac0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d  oating point num
2cad0 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69  ber.** <li> stri
2cae0 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a  ng.** <li> BLOB.
2caf0 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20  ** <li> NULL.** 
2cb00 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  </ul>)^.**.** Th
2cb10 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
2cb20 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68  e codes for each
2cb30 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e   of those types.
2cb40 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
2cb50 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54   the SQLITE_TEXT
2cb60 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c   constant was al
2cb70 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74  so used in SQLit
2cb80 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66  e version 2.** f
2cb90 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20  or a completely 
2cba0 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e  different meanin
2cbb0 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61  g.  Software tha
2cbc0 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20  t links against 
2cbd0 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76  both.** SQLite v
2cbe0 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c  ersion 2 and SQL
2cbf0 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68  ite version 3 sh
2cc00 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33  ould use SQLITE3
2cc10 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51  _TEXT, not.** SQ
2cc20 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64  LITE_TEXT..*/.#d
2cc30 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
2cc40 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20  EGER  1.#define 
2cc50 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20  SQLITE_FLOAT    
2cc60 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
2cc70 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66  _BLOB     4.#def
2cc80 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20  ine SQLITE_NULL 
2cc90 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c      5.#ifdef SQL
2cca0 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66  ITE_TEXT.# undef
2ccb0 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c   SQLITE_TEXT.#el
2ccc0 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  se.# define SQLI
2ccd0 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65  TE_TEXT     3.#e
2cce0 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c  ndif.#define SQL
2ccf0 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a  ITE3_TEXT     3.
2cd00 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2cd10 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46   Result Values F
2cd20 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b  rom A Query.** K
2cd30 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e  EYWORDS: {column
2cd40 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
2cd50 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  s}.**.** These r
2cd60 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65  outines form the
2cd70 20 22 72 65 73 75 6c 74 20 73 65 74 22 20 69 6e   "result set" in
2cd80 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e  terface..**.** ^
2cd90 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
2cda0 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f  eturn informatio
2cdb0 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65  n about a single
2cdc0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63   column of the c
2cdd0 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74  urrent.** result
2cde0 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e   row of a query.
2cdf0 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65    ^In every case
2ce00 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
2ce10 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
2ce20 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70  .** to the [prep
2ce30 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2ce40 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65 76  that is being ev
2ce50 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 71  aluated (the [sq
2ce60 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20  lite3_stmt*].** 
2ce70 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65  that was returne
2ce80 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
2ce90 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
2cea0 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69   one of its vari
2ceb0 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65  ants).** and the
2cec0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
2ced0 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
2cee0 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20   the column for 
2cef0 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f  which informatio
2cf00 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72  n.** should be r
2cf10 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65  eturned. ^The le
2cf20 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66  ftmost column of
2cf30 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
2cf40 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e  has the index 0.
2cf50 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20  .** ^The number 
2cf60 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
2cf70 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20  e result can be 
2cf80 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67  determined using
2cf90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
2cfa0 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a  umn_count()]..**
2cfb0 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73  .** If the SQL s
2cfc0 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f  tatement does no
2cfd0 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e  t currently poin
2cfe0 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77  t to a valid row
2cff0 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63  , or if the.** c
2d000 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f  olumn index is o
2d010 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65  ut of range, the
2d020 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66   result is undef
2d030 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72  ined..** These r
2d040 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79  outines may only
2d050 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20   be called when 
2d060 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
2d070 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
2d080 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
2d090 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
2d0a0 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65  _ROW] and neithe
2d0b0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  r.** [sqlite3_re
2d0c0 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69  set()] nor [sqli
2d0d0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2d0e0 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  have been called
2d0f0 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a   subsequently..*
2d100 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73  * If any of thes
2d110 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  e routines are c
2d120 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c  alled after [sql
2d130 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
2d140 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
2d150 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65  alize()] or afte
2d160 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  r [sqlite3_step(
2d170 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a  )] has returned.
2d180 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68  ** something oth
2d190 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
2d1a0 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74  ROW], the result
2d1b0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
2d1c0 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f  .** If [sqlite3_
2d1d0 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
2d1e0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
2d1f0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2d200 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c  e()].** are call
2d210 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72  ed from a differ
2d220 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65  ent thread while
2d230 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
2d240 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65  utines.** are pe
2d250 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20  nding, then the 
2d260 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
2d270 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
2d280 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
2d290 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20  _type() routine 
2d2a0 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b  returns the.** [
2d2b0 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c  SQLITE_INTEGER |
2d2c0 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20   datatype code] 
2d2d0 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20  for the initial 
2d2e0 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20  data type.** of 
2d2f0 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  the result colum
2d300 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65  n.  ^The returne
2d310 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f  d value is one o
2d320 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  f [SQLITE_INTEGE
2d330 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  R],.** [SQLITE_F
2d340 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54  LOAT], [SQLITE_T
2d350 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c  EXT], [SQLITE_BL
2d360 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OB], or [SQLITE_
2d370 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75  NULL].  The valu
2d380 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79  e.** returned by
2d390 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2d3a0 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d  type() is only m
2d3b0 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20  eaningful if no 
2d3c0 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69  type.** conversi
2d3d0 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65  ons have occurre
2d3e0 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20 62  d as described b
2d3f0 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74  elow.  After a t
2d400 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a  ype conversion,.
2d410 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ** the value ret
2d420 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
2d430 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69  _column_type() i
2d440 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75  s undefined.  Fu
2d450 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73  ture.** versions
2d460 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63   of SQLite may c
2d470 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69  hange the behavi
2d480 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f  or of sqlite3_co
2d490 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66  lumn_type().** f
2d4a0 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20  ollowing a type 
2d4b0 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a  conversion..**.*
2d4c0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2d4d0 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54   is a BLOB or UT
2d4e0 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20  F-8 string then 
2d4f0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  the sqlite3_colu
2d500 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f  mn_bytes().** ro
2d510 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
2d520 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2d530 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f  s in that BLOB o
2d540 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  r string..** ^If
2d550 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
2d560 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20   UTF-16 string, 
2d570 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2d580 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76  umn_bytes() conv
2d590 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69  erts.** the stri
2d5a0 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20  ng to UTF-8 and 
2d5b0 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65  then returns the
2d5c0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2d5d0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
2d5e0 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63  ult is a numeric
2d5f0 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69   value then sqli
2d600 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2d610 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69  () uses.** [sqli
2d620 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
2d630 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20  to convert that 
2d640 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38  value to a UTF-8
2d650 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
2d660 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  rns.** the numbe
2d670 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
2d680 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  at string..** ^I
2d690 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2d6a0 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74  NULL, then sqlit
2d6b0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2d6c0 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a  ) returns zero..
2d6d0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  **.** ^If the re
2d6e0 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f  sult is a BLOB o
2d6f0 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  r UTF-16 string 
2d700 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
2d710 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2d720 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
2d730 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
2d740 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
2d750 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e   BLOB or string.
2d760 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2d770 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20 73 74  lt is a UTF-8 st
2d780 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74  ring, then sqlit
2d790 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2d7a0 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  6() converts.** 
2d7b0 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54  the string to UT
2d7c0 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65  F-16 and then re
2d7d0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
2d7e0 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49   of bytes..** ^I
2d7f0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2d800 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20  a numeric value 
2d810 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2d820 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73  umn_bytes16() us
2d830 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  es.** [sqlite3_s
2d840 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f  nprintf()] to co
2d850 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65  nvert that value
2d860 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72   to a UTF-16 str
2d870 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a  ing and returns.
2d880 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
2d890 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73   bytes in that s
2d8a0 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
2d8b0 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  e result is NULL
2d8c0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
2d8d0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
2d8e0 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a  returns zero..**
2d8f0 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20  .** ^The values 
2d900 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
2d910 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2d920 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71  s()] and .** [sq
2d930 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2d940 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69  es16()] do not i
2d950 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20  nclude the zero 
2d960 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74  terminators at t
2d970 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65  he end.** of the
2d980 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63   string.  ^For c
2d990 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75  larity: the valu
2d9a0 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  es returned by.*
2d9b0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2d9c0 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b  n_bytes()] and [
2d9d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2d9e0 79 74 65 73 31 36 28 29 5d 20 61 72 65 20 74 68  ytes16()] are th
2d9f0 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62  e number of.** b
2da00 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69  ytes in the stri
2da10 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62  ng, not the numb
2da20 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
2da30 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73  ..**.** ^Strings
2da40 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
2da50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2da60 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  () and sqlite3_c
2da70 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a  olumn_text16(),.
2da80 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74  ** even empty st
2da90 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79  rings, are alway
2daa0 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  s zero-terminate
2dab0 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a  d.  ^The return.
2dac0 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  ** value from sq
2dad0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
2dae0 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c  b() for a zero-l
2daf0 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20  ength BLOB is a 
2db00 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
2db10 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74 20  .** ^The object 
2db20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
2db30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
2db40 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75  e()] is an.** [u
2db50 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2db60 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2db70 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65  .  An unprotecte
2db80 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
2db90 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e  object.** may on
2dba0 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 20  ly be used with 
2dbb0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
2dbc0 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  lue()] and [sqli
2dbd0 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
2dbe0 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b  ()]..** If the [
2dbf0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2dc00 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2dc10 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  t returned by.**
2dc20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2dc30 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65  _value()] is use
2dc40 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77  d in any other w
2dc50 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61  ay, including ca
2dc60 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e  lls.** to routin
2dc70 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33  es like [sqlite3
2dc80 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b  _value_int()], [
2dc90 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2dca0 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71  xt()],.** or [sq
2dcb0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
2dcc0 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62  s()], then the b
2dcd0 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
2dce0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ined..**.** Thes
2dcf0 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d  e routines attem
2dd00 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  pt to convert th
2dd10 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70  e value where ap
2dd20 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72  propriate.  ^For
2dd30 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20  .** example, if 
2dd40 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70  the internal rep
2dd50 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46  resentation is F
2dd60 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20  LOAT and a text 
2dd70 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71  result.** is req
2dd80 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33  uested, [sqlite3
2dd90 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20  _snprintf()] is 
2dda0 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  used internally 
2ddb0 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a  to perform the.*
2ddc0 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74  * conversion aut
2ddd0 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54  omatically.  ^(T
2dde0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62  he following tab
2ddf0 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63  le details the c
2de00 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68  onversions.** th
2de10 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a  at are applied:.
2de20 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
2de30 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72  e>.** <table bor
2de40 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e  der="1">.** <tr>
2de50 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72  <th> Internal<br
2de60 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65  >Type <th> Reque
2de70 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68  sted<br>Type <th
2de80 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a  >  Conversion.**
2de90 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
2dea0 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  LL    <td> INTEG
2deb0 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  ER   <td> Result
2dec0 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64   is 0.** <tr><td
2ded0 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
2dee0 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52   FLOAT    <td> R
2def0 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20  esult is 0.0.** 
2df00 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
2df10 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
2df20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
2df30 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
2df40 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
2df50 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
2df60 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
2df70 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
2df80 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
2df90 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41  EGER  <td>  FLOA
2dfa0 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  T    <td> Conver
2dfb0 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74  t from integer t
2dfc0 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c  o float.** <tr><
2dfd0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
2dfe0 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
2dff0 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67   ASCII rendering
2e000 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a   of the integer.
2e010 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
2e020 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  GER  <td>   BLOB
2e030 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73      <td> Same as
2e040 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a   INTEGER->TEXT.*
2e050 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
2e060 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52  T   <td> INTEGER
2e070 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
2e080 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72  o INTEGER.** <tr
2e090 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
2e0a0 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
2e0b0 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69  d> ASCII renderi
2e0c0 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a  ng of the float.
2e0d0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
2e0e0 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  AT   <td>   BLOB
2e0f0 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20      <td> [CAST] 
2e100 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c  to BLOB.** <tr><
2e110 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
2e120 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
2e130 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47   [CAST] to INTEG
2e140 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ER.** <tr><td>  
2e150 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c  TEXT    <td>  FL
2e160 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53  OAT    <td> [CAS
2e170 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74  T] to REAL.** <t
2e180 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
2e190 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
2e1a0 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a  td> No change.**
2e1b0 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
2e1c0 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
2e1d0 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
2e1e0 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e   INTEGER.** <tr>
2e1f0 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
2e200 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
2e210 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c  > [CAST] to REAL
2e220 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
2e230 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58  OB    <td>   TEX
2e240 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20  T    <td> Add a 
2e250 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20  zero terminator 
2e260 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74  if needed.** </t
2e270 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b  able>.** </block
2e280 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54  quote>)^.**.** T
2e290 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d  he table above m
2e2a0 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20 74  akes reference t
2e2b0 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  o standard C lib
2e2c0 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61  rary functions a
2e2d0 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f  toi().** and ato
2e2e0 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65  f().  SQLite doe
2e2f0 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65  s not really use
2e300 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
2e310 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a  .  It has its.**
2e320 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20   own equivalent 
2e330 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65  internal routine
2e340 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20 61  s.  The atoi() a
2e350 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20  nd atof() names 
2e360 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74  are.** used in t
2e370 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65  he table for bre
2e380 76 69 74 79 20 61 6e 64 20 62 65 63 61 75 73 65  vity and because
2e390 20 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69   they are famili
2e3a0 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20  ar to most.** C 
2e3b0 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a  programmers..**.
2e3c0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65  ** Note that whe
2e3d0 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  n type conversio
2e3e0 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65  ns occur, pointe
2e3f0 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70  rs returned by p
2e400 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f  rior.** calls to
2e410 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2e420 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f  blob(), sqlite3_
2e430 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61  column_text(), a
2e440 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  nd/or.** sqlite3
2e450 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2e460 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61   may be invalida
2e470 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e  ted..** Type con
2e480 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69  versions and poi
2e490 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f  nter invalidatio
2e4a0 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a  ns might occur.*
2e4b0 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69  * in the followi
2e4c0 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20  ng cases:.**.** 
2e4d0 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
2e4e0 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
2e4f0 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73   is a BLOB and s
2e500 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2e510 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  xt() or.**      
2e520 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2e530 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65  ext16() is calle
2e540 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69  d.  A zero-termi
2e550 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20  nator might.**  
2e560 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61      need to be a
2e570 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69  dded to the stri
2e580 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e  ng.</li>.** <li>
2e590 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
2e5a0 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65  tent is UTF-8 te
2e5b0 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  xt and sqlite3_c
2e5c0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
2e5d0 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
2e5e0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2e5f0 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54  () is called.  T
2e600 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20  he content must 
2e610 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20  be converted.** 
2e620 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c       to UTF-16.<
2e630 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  /li>.** <li> The
2e640 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
2e650 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20   is UTF-16 text 
2e660 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
2e670 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a  mn_bytes() or.**
2e680 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
2e690 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63  lumn_text() is c
2e6a0 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74  alled.  The cont
2e6b0 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ent must be conv
2e6c0 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f  erted.**      to
2e6d0 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20   UTF-8.</li>.** 
2e6e0 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e  </ul>.**.** ^Con
2e6f0 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e  versions between
2e700 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54   UTF-16be and UT
2e710 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79  F-16le are alway
2e720 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20  s done in place 
2e730 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e  and do.** not in
2e740 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72  validate a prior
2e750 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68   pointer, though
2e760 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63   of course the c
2e770 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75  ontent of the bu
2e780 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65  ffer.** that the
2e790 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72   prior pointer r
2e7a0 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68  eferences will h
2e7b0 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65  ave been modifie
2e7c0 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a  d.  Other kinds.
2e7d0 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e  ** of conversion
2e7e0 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61   are done in pla
2e7f0 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f  ce when it is po
2e800 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65  ssible, but some
2e810 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72  times they.** ar
2e820 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61  e not possible a
2e830 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65  nd in those case
2e840 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73  s prior pointers
2e850 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64   are invalidated
2e860 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65  ..**.** The safe
2e870 73 74 20 61 6e 64 20 65 61 73 69 65 73 74 20 74  st and easiest t
2e880 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63  o remember polic
2e890 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74  y is to invoke t
2e8a0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  hese routines.**
2e8b0 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66   in one of the f
2e8c0 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a  ollowing ways:.*
2e8d0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c  *.** <ul>.**  <l
2e8e0 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
2e8f0 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64  _text() followed
2e900 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
2e910 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a  mn_bytes()</li>.
2e920 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
2e930 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f  column_blob() fo
2e940 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
2e950 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2e960 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71  </li>.**  <li>sq
2e970 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2e980 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  t16() followed b
2e990 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
2e9a0 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a  _bytes16()</li>.
2e9b0 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </ul>.**.** I
2e9c0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79  n other words, y
2e9d0 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73  ou should call s
2e9e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2e9f0 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  xt(),.** sqlite3
2ea00 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20  _column_blob(), 
2ea10 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
2ea20 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 74  n_text16() first
2ea30 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65   to force the re
2ea40 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65  sult.** into the
2ea50 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c   desired format,
2ea60 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c   then invoke sql
2ea70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2ea80 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  s() or.** sqlite
2ea90 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2eaa0 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73  () to find the s
2eab0 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c  ize of the resul
2eac0 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63  t.  Do not mix c
2ead0 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  alls.** to sqlit
2eae0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2eaf0 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
2eb00 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63  mn_blob() with c
2eb10 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  alls to.** sqlit
2eb20 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2eb30 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20  6(), and do not 
2eb40 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  mix calls to sql
2eb50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2eb60 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c  16().** with cal
2eb70 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
2eb80 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a  lumn_bytes()..**
2eb90 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72  .** ^The pointer
2eba0 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 76  s returned are v
2ebb0 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70  alid until a typ
2ebc0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63  e conversion occ
2ebd0 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69  urs as.** descri
2ebe0 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e  bed above, or un
2ebf0 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  til [sqlite3_ste
2ec00 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  p()] or [sqlite3
2ec10 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20  _reset()] or.** 
2ec20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2ec30 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20  e()] is called. 
2ec40 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61   ^The memory spa
2ec50 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20  ce used to hold 
2ec60 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42  strings.** and B
2ec70 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20 61 75  LOBs is freed au
2ec80 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f  tomatically.  Do
2ec90 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73   <b>not</b> pass
2eca0 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65   the pointers re
2ecb0 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  turned.** from [
2ecc0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2ecd0 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  lob()], [sqlite3
2ece0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c  _column_text()],
2ecf0 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73   etc. into.** [s
2ed00 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
2ed10 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d  **.** ^(If a mem
2ed20 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
2ed30 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69  rror occurs duri
2ed40 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f  ng the evaluatio
2ed50 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74  n of any.** of t
2ed60 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61  hese routines, a
2ed70 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69   default value i
2ed80 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  s returned.  The
2ed90 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a   default value.*
2eda0 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20  * is either the 
2edb0 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20 66  integer 0, the f
2edc0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75  loating point nu
2edd0 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e  mber 0.0, or a N
2ede0 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20  ULL.** pointer. 
2edf0 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   Subsequent call
2ee00 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72  s to [sqlite3_er
2ee10 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65  rcode()] will re
2ee20 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  turn.** [SQLITE_
2ee30 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e  NOMEM].)^.*/.con
2ee40 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2ee50 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c  _column_blob(sql
2ee60 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2ee70 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
2ee80 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2ee90 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2eea0 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
2eeb0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2eec0 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  es16(sqlite3_stm
2eed0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64  t*, int iCol);.d
2eee0 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f  ouble sqlite3_co
2eef0 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69  lumn_double(sqli
2ef00 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2ef10 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
2ef20 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c  3_column_int(sql
2ef30 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2ef40 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69  iCol);.sqlite3_i
2ef50 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c  nt64 sqlite3_col
2ef60 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  umn_int64(sqlite
2ef70 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2ef80 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e  l);.const unsign
2ef90 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  ed char *sqlite3
2efa0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c  _column_text(sql
2efb0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2efc0 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  iCol);.const voi
2efd0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2efe0 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  n_text16(sqlite3
2eff0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2f000 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
2f010 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74  olumn_type(sqlit
2f020 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2f030 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c  ol);.sqlite3_val
2f040 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ue *sqlite3_colu
2f050 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  mn_value(sqlite3
2f060 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2f070 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2f080 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72  EF: Destroy A Pr
2f090 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
2f0a0 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54   Object.**.** ^T
2f0b0 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  he sqlite3_final
2f0c0 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ize() function i
2f0d0 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65  s called to dele
2f0e0 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  te a [prepared s
2f0f0 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49  tatement]..** ^I
2f100 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
2f110 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  t evaluation of 
2f120 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e  the statement en
2f130 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72  countered no err
2f140 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65  ors.** or if the
2f150 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65   statement is ne
2f160 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74  ver been evaluat
2f170 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ed, then sqlite3
2f180 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75  _finalize() retu
2f190 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b  rns.** SQLITE_OK
2f1a0 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  .  ^If the most 
2f1b0 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f  recent evaluatio
2f1c0 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53  n of statement S
2f1d0 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a   failed, then.**
2f1e0 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
2f1f0 65 28 53 29 20 72 65 74 75 72 6e 73 20 74 68 65  e(S) returns the
2f200 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
2f210 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20  ror code] or.** 
2f220 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
2f230 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  code]..**.** ^Th
2f240 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  e sqlite3_finali
2f250 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61  ze(S) routine ca
2f260 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61  n be called at a
2f270 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a  ny point during.
2f280 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c  ** the life cycl
2f290 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73  e of [prepared s
2f2a0 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20  tatement] S:.** 
2f2b0 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74  before statement
2f2c0 20 53 20 69 73 20 65 76 65 72 20 65 76 61 6c 75   S is ever evalu
2f2d0 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f  ated, after.** o
2f2e0 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73  ne or more calls
2f2f0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
2f300 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20  et()], or after 
2f310 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b  any call.** to [
2f320 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2f330 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
2f340 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
2f350 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a   statement has.*
2f360 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63  * completed exec
2f370 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e  ution..**.** ^In
2f380 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66  voking sqlite3_f
2f390 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e  inalize() on a N
2f3a0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61  ULL pointer is a
2f3b0 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e   harmless no-op.
2f3c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  .**.** The appli
2f3d0 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61  cation must fina
2f3e0 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70  lize every [prep
2f3f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2f400 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69  in order to avoi
2f410 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65  d.** resource le
2f420 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67 72  aks.  It is a gr
2f430 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72  ievous error for
2f440 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2f450 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a   to try to use.*
2f460 2a 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  * a prepared sta
2f470 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20  tement after it 
2f480 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  has been finaliz
2f490 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20  ed.  Any use of 
2f4a0 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  a prepared.** st
2f4b0 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74  atement after it
2f4c0 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
2f4d0 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69  zed can result i
2f4e0 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a  n undefined and.
2f4f0 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62  ** undesirable b
2f500 65 68 61 76 69 6f 72 20 73 75 63 68 20 61 73 20  ehavior such as 
2f510 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65  segfaults and he
2f520 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  ap corruption..*
2f530 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69  /.int sqlite3_fi
2f540 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73  nalize(sqlite3_s
2f550 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2f560 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
2f570 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53  set A Prepared S
2f580 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
2f590 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2f5a0 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74 69  3_reset() functi
2f5b0 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  on is called to 
2f5c0 72 65 73 65 74 20 61 20 5b 70 72 65 70 61 72 65  reset a [prepare
2f5d0 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
2f5e0 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69  object back to i
2f5f0 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65  ts initial state
2f600 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 65  , ready to be re
2f610 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41  -executed..** ^A
2f620 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ny SQL statement
2f630 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 74 20   variables that 
2f640 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64  had values bound
2f650 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a   to them using.*
2f660 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  * the [sqlite3_b
2f670 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74  ind_blob | sqlit
2f680 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d  e3_bind_*() API]
2f690 20 72 65 74 61 69 6e 20 74 68 65 69 72 20 76 61   retain their va
2f6a0 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71  lues..** Use [sq
2f6b0 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64  lite3_clear_bind
2f6c0 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74  ings()] to reset
2f6d0 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a   the bindings..*
2f6e0 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
2f6f0 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74  e3_reset(S)] int
2f700 65 72 66 61 63 65 20 72 65 73 65 74 73 20 74 68  erface resets th
2f710 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2f720 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b  ement] S.** back
2f730 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e   to the beginnin
2f740 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d  g of its program
2f750 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2f760 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
2f770 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
2f780 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a  p(S)] for the.**
2f790 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2f7a0 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64  ment] S returned
2f7b0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72   [SQLITE_ROW] or
2f7c0 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a   [SQLITE_DONE],.
2f7d0 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65  ** or if [sqlite
2f7e0 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e  3_step(S)] has n
2f7f0 65 76 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e  ever before been
2f800 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a   called on S,.**
2f810 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72   then [sqlite3_r
2f820 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73  eset(S)] returns
2f830 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
2f840 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
2f850 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
2f860 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
2f870 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72  ] for the.** [pr
2f880 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2f890 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e  ] S indicated an
2f8a0 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20   error, then.** 
2f8b0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
2f8c0 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70  )] returns an ap
2f8d0 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72  propriate [error
2f8e0 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54   code]..**.** ^T
2f8f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
2f900 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
2f910 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
2f920 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66  the values.** of
2f930 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69   any [sqlite3_bi
2f940 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73  nd_blob|bindings
2f950 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72  ] on the [prepar
2f960 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e  ed statement] S.
2f970 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2f980 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74  reset(sqlite3_st
2f990 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
2f9a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 65  ** CAPI3REF: Cre
2f9b0 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20  ate Or Redefine 
2f9c0 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  SQL Functions.**
2f9d0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63   KEYWORDS: {func
2f9e0 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f  tion creation ro
2f9f0 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f  utines}.** KEYWO
2fa00 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f  RDS: {applicatio
2fa10 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
2fa20 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f  nction}.** KEYWO
2fa30 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f  RDS: {applicatio
2fa40 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
2fa50 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e  nctions}.**.** ^
2fa60 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
2fa70 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e  (collectively kn
2fa80 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e  own as "function
2fa90 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
2faa0 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64  es").** are used
2fab0 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63   to add SQL func
2fac0 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61  tions or aggrega
2fad0 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69  tes or to redefi
2fae0 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a  ne the behavior.
2faf0 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53  ** of existing S
2fb00 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  QL functions or 
2fb10 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65  aggregates.  The
2fb20 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65   only difference
2fb30 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65  s between.** the
2fb40 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
2fb50 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  the text encodin
2fb60 67 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a  g expected for.*
2fb70 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * the second par
2fb80 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65  ameter (the name
2fb90 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
2fba0 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a   being created).
2fbb0 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73 65  ** and the prese
2fbc0 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f  nce or absence o
2fbd0 66 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 63  f a destructor c
2fbe0 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74  allback for.** t
2fbf0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
2fc00 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ata pointer..**.
2fc10 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  ** ^The first pa
2fc20 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b  rameter is the [
2fc30 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2fc40 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68  ion] to which th
2fc50 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f  e SQL.** functio
2fc60 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64  n is to be added
2fc70 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63  .  ^If an applic
2fc80 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20  ation uses more 
2fc90 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73  than one databas
2fca0 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
2fcb0 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  then application
2fcc0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
2fcd0 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61  ctions must be a
2fce0 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20  dded.** to each 
2fcf0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2fd00 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a  ion separately..
2fd10 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  **.** ^The secon
2fd20 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
2fd30 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53  he name of the S
2fd40 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  QL function to b
2fd50 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20  e created or.** 
2fd60 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65  redefined.  ^The
2fd70 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e   length of the n
2fd80 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74  ame is limited t
2fd90 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e 20 61  o 255 bytes in a
2fda0 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73   UTF-8.** repres
2fdb0 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73  entation, exclus
2fdc0 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d  ive of the zero-
2fdd0 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f  terminator.  ^No
2fde0 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65  te that the name
2fdf0 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74  .** length limit
2fe00 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74   is in UTF-8 byt
2fe10 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65  es, not characte
2fe20 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79  rs nor UTF-16 by
2fe30 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61  tes.  .** ^Any a
2fe40 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65  ttempt to create
2fe50 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68   a function with
2fe60 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a   a longer name.*
2fe70 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e  * will result in
2fe80 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
2fe90 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e   being returned.
2fea0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72  .**.** ^The thir
2feb0 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72  d parameter (nAr
2fec0 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d  g).** is the num
2fed0 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
2fee0 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 75   that the SQL fu
2fef0 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
2ff00 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49  regate takes. ^I
2ff10 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72  f this parameter
2ff20 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65   is -1, then the
2ff30 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
2ff40 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61  .** aggregate ma
2ff50 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65  y take any numbe
2ff60 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62  r of arguments b
2ff70 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65  etween 0 and the
2ff80 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79   limit.** set by
2ff90 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d   [sqlite3_limit]
2ffa0 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  ([SQLITE_LIMIT_F
2ffb0 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20  UNCTION_ARG]).  
2ffc0 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  If the third.** 
2ffd0 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73  parameter is les
2ffe0 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65  s than -1 or gre
2fff0 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 74 68  ater than 127 th
30000 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
30010 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e  is.** undefined.
30020 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72  .**.** ^The four
30030 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54  th parameter, eT
30040 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65  extRep, specifie
30050 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54  s what.** [SQLIT
30060 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e  E_UTF8 | text en
30070 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c  coding] this SQL
30080 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72   function prefer
30090 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72  s for.** its par
300a0 61 6d 65 74 65 72 73 2e 20 20 54 68 65 20 61 70  ameters.  The ap
300b0 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
300c0 20 73 65 74 20 74 68 69 73 20 70 61 72 61 6d 65   set this parame
300d0 74 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54  ter to.** [SQLIT
300e0 45 5f 55 54 46 31 36 4c 45 5d 20 69 66 20 74 68  E_UTF16LE] if th
300f0 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  e function imple
30100 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65  mentation invoke
30110 73 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  s .** [sqlite3_v
30120 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 5d  alue_text16le()]
30130 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72   on an input, or
30140 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45   [SQLITE_UTF16BE
30150 5d 20 69 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c  ] if the.** impl
30160 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b  ementation invok
30170 65 73 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  es [sqlite3_valu
30180 65 5f 74 65 78 74 31 36 62 65 28 29 5d 20 6f 6e  e_text16be()] on
30190 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a   an input, or.**
301a0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20   [SQLITE_UTF16] 
301b0 69 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  if [sqlite3_valu
301c0 65 5f 74 65 78 74 31 36 28 29 5d 20 69 73 20 75  e_text16()] is u
301d0 73 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  sed, or [SQLITE_
301e0 55 54 46 38 5d 0a 2a 2a 20 6f 74 68 65 72 77 69  UTF8].** otherwi
301f0 73 65 2e 20 20 5e 54 68 65 20 73 61 6d 65 20 53  se.  ^The same S
30200 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20  QL function may 
30210 62 65 20 72 65 67 69 73 74 65 72 65 64 20 6d 75  be registered mu
30220 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 73 69  ltiple times usi
30230 6e 67 0a 2a 2a 20 64 69 66 66 65 72 65 6e 74 20  ng.** different 
30240 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
30250 6e 63 6f 64 69 6e 67 73 2c 20 77 69 74 68 20 64  ncodings, with d
30260 69 66 66 65 72 65 6e 74 20 69 6d 70 6c 65 6d 65  ifferent impleme
30270 6e 74 61 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20  ntations for.** 
30280 65 61 63 68 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a  each encoding..*
30290 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65  * ^When multiple
302a0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
302b0 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e   of the same fun
302c0 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61  ction are availa
302d0 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77  ble, SQLite.** w
302e0 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65  ill pick the one
302f0 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74   that involves t
30300 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20  he least amount 
30310 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69  of data conversi
30320 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  on..**.** ^The f
30330 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
30340 6d 61 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 62  may optionally b
30350 65 20 4f 52 65 64 20 77 69 74 68 20 5b 53 51 4c  e ORed with [SQL
30360 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49  ITE_DETERMINISTI
30370 43 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20  C].** to signal 
30380 74 68 61 74 20 74 68 65 20 66 75 6e 63 74 69 6f  that the functio
30390 6e 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65  n will always re
303a0 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20 72 65  turn the same re
303b0 73 75 6c 74 20 67 69 76 65 6e 0a 2a 2a 20 74 68  sult given.** th
303c0 65 20 73 61 6d 65 20 69 6e 70 75 74 73 20 77 69  e same inputs wi
303d0 74 68 69 6e 20 61 20 73 69 6e 67 6c 65 20 53 51  thin a single SQ
303e0 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 4d 6f  L statement.  Mo
303f0 73 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  st SQL functions
30400 20 61 72 65 0a 2a 2a 20 64 65 74 65 72 6d 69 6e   are.** determin
30410 69 73 74 69 63 2e 20 20 54 68 65 20 62 75 69 6c  istic.  The buil
30420 74 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d 20  t-in [random()] 
30430 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
30440 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 61 0a  an example of a.
30450 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  ** function that
30460 20 69 73 20 6e 6f 74 20 64 65 74 65 72 6d 69 6e   is not determin
30470 69 73 74 69 63 2e 20 20 54 68 65 20 53 51 4c 69  istic.  The SQLi
30480 74 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 72  te query planner
30490 20 69 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20 70   is able to.** p
304a0 65 72 66 6f 72 6d 20 61 64 64 69 74 69 6f 6e 61  erform additiona
304b0 6c 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20  l optimizations 
304c0 6f 6e 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63  on deterministic
304d0 20 66 75 6e 63 74 69 6f 6e 73 2c 20 73 6f 20 75   functions, so u
304e0 73 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51  se.** of the [SQ
304f0 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54  LITE_DETERMINIST
30500 49 43 5d 20 66 6c 61 67 20 69 73 20 72 65 63 6f  IC] flag is reco
30510 6d 6d 65 6e 64 65 64 20 77 68 65 72 65 20 70 6f  mmended where po
30520 73 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ssible..**.** ^(
30530 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65  The fifth parame
30540 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72  ter is an arbitr
30550 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68  ary pointer.  Th
30560 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
30570 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74   of the.** funct
30580 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63  ion can gain acc
30590 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e  ess to this poin
305a0 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ter using [sqlit
305b0 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e  e3_user_data()].
305c0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69  )^.**.** ^The si
305d0 78 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64  xth, seventh and
305e0 20 65 69 67 68 74 68 20 70 61 72 61 6d 65 74 65   eighth paramete
305f0 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70  rs, xFunc, xStep
30600 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65   and xFinal, are
30610 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  .** pointers to 
30620 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74  C-language funct
30630 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d  ions that implem
30640 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  ent the SQL func
30650 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
30660 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20  gate. ^A scalar 
30670 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  SQL function req
30680 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65  uires an impleme
30690 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78  ntation of the x
306a0 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  Func.** callback
306b0 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e   only; NULL poin
306c0 74 65 72 73 20 6d 75 73 74 20 62 65 20 70 61 73  ters must be pas
306d0 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70  sed as the xStep
306e0 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70   and xFinal.** p
306f0 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61  arameters. ^An a
30700 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
30710 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61  ction requires a
30720 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
30730 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64   of xStep.** and
30740 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c   xFinal and NULL
30750 20 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65   pointer must be
30760 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e   passed for xFun
30770 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e  c. ^To delete an
30780 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c   existing.** SQL
30790 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
307a0 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c  regate, pass NUL
307b0 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61  L pointers for a
307c0 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f  ll three functio
307d0 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a  n.** callbacks..
307e0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e  **.** ^(If the n
307f0 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  inth parameter t
30800 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  o sqlite3_create
30810 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69  _function_v2() i
30820 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74  s not NULL,.** t
30830 68 65 6e 20 69 74 20 69 73 20 64 65 73 74 72 75  hen it is destru
30840 63 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70  ctor for the app
30850 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
30860 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64  inter. .** The d
30870 65 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76  estructor is inv
30880 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66 75  oked when the fu
30890 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65  nction is delete
308a0 64 2c 20 65 69 74 68 65 72 20 62 79 20 62 65 69  d, either by bei
308b0 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64  ng.** overloaded
308c0 20 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61 74   or when the dat
308d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
308e0 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54   closes.)^.** ^T
308f0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73  he destructor is
30900 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66   also invoked if
30910 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20   the call to.** 
30920 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
30930 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69  unction_v2() fai
30940 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65  ls..** ^When the
30950 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c   destructor call
30960 62 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74  back of the tent
30970 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69  h parameter is i
30980 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73  nvoked, it.** is
30990 20 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65   passed a single
309a0 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
309b0 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
309c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
309d0 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68  a .** pointer wh
309e0 69 63 68 20 77 61 73 20 74 68 65 20 66 69 66 74  ich was the fift
309f0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
30a00 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
30a10 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  nction_v2()..**.
30a20 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74  ** ^It is permit
30a30 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20  ted to register 
30a40 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65  multiple impleme
30a50 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ntations of the 
30a60 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  same.** function
30a70 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  s with the same 
30a80 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69  name but with ei
30a90 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e  ther differing n
30aa0 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67  umbers of.** arg
30ab0 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72  uments or differ
30ac0 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65  ing preferred te
30ad0 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e  xt encodings.  ^
30ae0 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a  SQLite will use.
30af0 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ** the implement
30b00 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20  ation that most 
30b10 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20  closely matches 
30b20 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68  the way in which
30b30 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63   the.** SQL func
30b40 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e  tion is used.  ^
30b50 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  A function imple
30b60 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61  mentation with a
30b70 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a   non-negative.**
30b80 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 20   nArg parameter 
30b90 69 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 63  is a better matc
30ba0 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
30bb0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
30bc0 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74   with.** a negat
30bd0 69 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75  ive nArg.  ^A fu
30be0 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
30bf0 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
30c00 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63  encoding.** matc
30c10 68 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  hes the database
30c20 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62   encoding is a b
30c30 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74  etter.** match t
30c40 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  han a function w
30c50 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
30c60 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20  g is different. 
30c70 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e   .** ^A function
30c80 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64   where the encod
30c90 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69  ing difference i
30ca0 73 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c  s between UTF16l
30cb0 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a  e and UTF16be.**
30cc0 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74   is a closer mat
30cd0 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
30ce0 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63  on where the enc
30cf0 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65  oding difference
30d00 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55   is.** between U
30d10 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a  TF8 and UTF16..*
30d20 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66  *.** ^Built-in f
30d30 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20  unctions may be 
30d40 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65  overloaded by ne
30d50 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  w application-de
30d60 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e  fined functions.
30d70 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69  .**.** ^An appli
30d80 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
30d90 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69  unction is permi
30da0 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68  tted to call oth
30db0 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  er.** SQLite int
30dc0 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65  erfaces.  Howeve
30dd0 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75  r, such calls mu
30de0 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20  st not.** close 
30df0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
30e00 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61  nection nor fina
30e10 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68  lize or reset th
30e20 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  e prepared.** st
30e30 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68  atement in which
30e40 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73   the function is
30e50 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74   running..*/.int
30e60 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
30e70 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69  function(.  sqli
30e80 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
30e90 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e   char *zFunction
30ea0 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
30eb0 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
30ec0 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
30ed0 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
30ee0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
30ef0 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
30f00 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
30f10 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
30f20 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
30f30 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
30f40 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
30f50 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
30f60 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
30f70 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
30f80 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
30f90 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  ,.  const void *
30fa0 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
30fb0 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
30fc0 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
30fd0 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
30fe0 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
30ff0 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
31000 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
31010 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
31020 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
31030 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
31040 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
31050 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
31060 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74  context*).);.int
31070 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
31080 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73  function_v2(.  s
31090 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
310a0 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74  nst char *zFunct
310b0 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
310c0 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
310d0 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
310e0 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
310f0 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
31100 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
31110 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
31120 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
31130 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
31140 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
31150 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
31160 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
31170 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65  t*),.  void(*xDe
31180 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b  stroy)(void*).);
31190 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
311a0 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73  : Text Encodings
311b0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
311c0 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74  stant define int
311d0 65 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20  eger codes that 
311e0 72 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61  represent the va
311f0 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e  rious.** text en
31200 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65  codings supporte
31210 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  d by SQLite..*/.
31220 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
31230 54 46 38 20 20 20 20 20 20 20 20 20 20 20 31 0a  TF8           1.
31240 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
31250 54 46 31 36 4c 45 20 20 20 20 20 20 20 20 32 0a  TF16LE        2.
31260 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
31270 54 46 31 36 42 45 20 20 20 20 20 20 20 20 33 0a  TF16BE        3.
31280 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
31290 54 46 31 36 20 20 20 20 20 20 20 20 20 20 34 20  TF16          4 
312a0 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65     /* Use native
312b0 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23   byte order */.#
312c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e  define SQLITE_AN
312d0 59 20 20 20 20 20 20 20 20 20 20 20 20 35 20 20  Y            5  
312e0 20 20 2f 2a 20 44 65 70 72 65 63 61 74 65 64 20    /* Deprecated 
312f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
31300 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20  E_UTF16_ALIGNED 
31310 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33   8    /* sqlite3
31320 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
31330 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  n only */../*.**
31340 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74   CAPI3REF: Funct
31350 69 6f 6e 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20  ion Flags.**.** 
31360 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
31370 6d 61 79 20 62 65 20 4f 52 65 64 20 74 6f 67 65  may be ORed toge
31380 74 68 65 72 20 77 69 74 68 20 74 68 65 20 0a 2a  ther with the .*
31390 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c  * [SQLITE_UTF8 |
313a0 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
313b0 65 6e 63 6f 64 69 6e 67 5d 20 61 73 20 74 68 65  encoding] as the
313c0 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
313d0 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
313e0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
313f0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
31400 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
31410 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
31420 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
31430 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66  n_v2()]..*/.#def
31440 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 45 52  ine SQLITE_DETER
31450 4d 49 4e 49 53 54 49 43 20 20 20 20 30 78 38 30  MINISTIC    0x80
31460 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  0../*.** CAPI3RE
31470 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 46 75  F: Deprecated Fu
31480 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45  nctions.** DEPRE
31490 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73  CATED.**.** Thes
314a0 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  e functions are 
314b0 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49  [deprecated].  I
314c0 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74  n order to maint
314d0 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  ain.** backwards
314e0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77   compatibility w
314f0 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20  ith older code, 
31500 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  these functions 
31510 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20  continue .** to 
31520 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48  be supported.  H
31530 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c  owever, new appl
31540 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
31550 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65  avoid.** the use
31560 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69   of these functi
31570 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e  ons.  To help en
31580 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74  courage people t
31590 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67  o avoid.** using
315a0 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
315b0 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69  , we are not goi
315c0 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77  ng to tell you w
315d0 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a  hat they do..*/.
315e0 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f  #ifndef SQLITE_O
315f0 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53  MIT_DEPRECATED.S
31600 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
31610 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67   int sqlite3_agg
31620 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c  regate_count(sql
31630 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
31640 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
31650 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  D int sqlite3_ex
31660 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74  pired(sqlite3_st
31670 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  mt*);.SQLITE_DEP
31680 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
31690 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e  te3_transfer_bin
316a0 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
316b0 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d  mt*, sqlite3_stm
316c0 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  t*);.SQLITE_DEPR
316d0 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
316e0 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65  e3_global_recove
316f0 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  r(void);.SQLITE_
31700 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20  DEPRECATED void 
31710 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63  sqlite3_thread_c
31720 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51  leanup(void);.SQ
31730 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
31740 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  int sqlite3_memo
31750 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29  ry_alarm(void(*)
31760 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69  (void*,sqlite3_i
31770 6e 74 36 34 2c 69 6e 74 29 2c 0a 20 20 20 20 20  nt64,int),.     
31780 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
31790 20 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69   void*,sqlite3_i
317a0 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt64);.#endif../
317b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
317c0 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e  btaining SQL Fun
317d0 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20  ction Parameter 
317e0 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65  Values.**.** The
317f0 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c   C-language impl
31800 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51  ementation of SQ
31810 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
31820 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a  aggregates uses.
31830 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69  ** this set of i
31840 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65  nterface routine
31850 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  s to access the 
31860 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73  parameter values
31870 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74   on.** the funct
31880 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
31890 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e  ..**.** The xFun
318a0 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75  c (for scalar fu
318b0 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65  nctions) or xSte
318c0 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 65  p (for aggregate
318d0 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a  s) parameters.**
318e0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   to [sqlite3_cre
318f0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20  ate_function()] 
31900 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
31910 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
31920 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c  ].** define call
31930 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65  backs that imple
31940 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e  ment the SQL fun
31950 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
31960 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72  gates..** The 3r
31970 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
31980 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69  hese callbacks i
31990 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
319a0 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72  inters to.** [pr
319b0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
319c0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20  value] objects. 
319d0 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73   There is one [s
319e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
319f0 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68  ject for.** each
31a00 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
31a10 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20  e SQL function. 
31a20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
31a30 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65  are used to.** e
31a40 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72  xtract values fr
31a50 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  om the [sqlite3_
31a60 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a  value] objects..
31a70 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
31a80 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77  ines work only w
31a90 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73  ith [protected s
31aa0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
31ab0 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74  jects..** Any at
31ac0 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65  tempt to use the
31ad0 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61  se routines on a
31ae0 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  n [unprotected s
31af0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a  qlite3_value].**
31b00 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20   object results 
31b10 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68  in undefined beh
31b20 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  avior..**.** ^Th
31b30 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72  ese routines wor
31b40 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20  k just like the 
31b50 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63  corresponding [c
31b60 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
31b70 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70  ctions].** excep
31b80 74 20 74 68 61 74 20 20 74 68 65 73 65 20 72 6f  t that  these ro
31b90 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69  utines take a si
31ba0 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20  ngle [protected 
31bb0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
31bc0 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72  bject.** pointer
31bd0 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73   instead of a [s
31be0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f  qlite3_stmt*] po
31bf0 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74  inter and an int
31c00 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62  eger column numb
31c10 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
31c20 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
31c30 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 20  t16() interface 
31c40 65 78 74 72 61 63 74 73 20 61 20 55 54 46 2d 31  extracts a UTF-1
31c50 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74  6 string.** in t
31c60 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f  he native byte-o
31c70 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74  rder of the host
31c80 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a   machine.  ^The.
31c90 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
31ca0 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64 20  _text16be() and 
31cb0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
31cc0 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61  xt16le() interfa
31cd0 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55  ces.** extract U
31ce0 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73  TF-16 strings as
31cf0 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20   big-endian and 
31d00 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65  little-endian re
31d10 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a  spectively..**.*
31d20 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f  * ^(The sqlite3_
31d30 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79  value_numeric_ty
31d40 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 61  pe() interface a
31d50 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79  ttempts to apply
31d60 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69  .** numeric affi
31d70 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75  nity to the valu
31d80 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74  e.  This means t
31d90 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69  hat an attempt i
31da0 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e  s.** made to con
31db0 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 74  vert the value t
31dc0 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20  o an integer or 
31dd0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20  floating point. 
31de0 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f   If.** such a co
31df0 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73  nversion is poss
31e00 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73  ible without los
31e10 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  s of information
31e20 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f   (in other.** wo
31e30 72 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75  rds, if the valu
31e40 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 68  e is a string th
31e50 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20  at looks like a 
31e60 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20  number).** then 
31e70 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  the conversion i
31e80 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74  s performed.  Ot
31e90 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65  herwise no conve
31ea0 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a  rsion occurs..**
31eb0 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54   The [SQLITE_INT
31ec0 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d  EGER | datatype]
31ed0 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f   after conversio
31ee0 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  n is returned.)^
31ef0 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61  .**.** Please pa
31f00 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74 74  y particular att
31f10 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61  ention to the fa
31f20 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e  ct that the poin
31f30 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  ter returned.** 
31f40 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61  from [sqlite3_va
31f50 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71  lue_blob()], [sq
31f60 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
31f70 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
31f80 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
31f90 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c  ()] can be inval
31fa0 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62 73  idated by a subs
31fb0 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a  equent call to.*
31fc0 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
31fd0 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69  _bytes()], [sqli
31fe0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
31ff0 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  6()], [sqlite3_v
32000 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a  alue_text()],.**
32010 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   or [sqlite3_val
32020 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a  ue_text16()]..**
32030 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
32040 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  es must be calle
32050 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
32060 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65  thread as.** the
32070 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68   SQL function th
32080 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65 20  at supplied the 
32090 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d  [sqlite3_value*]
320a0 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a   parameters..*/.
320b0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
320c0 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73  te3_value_blob(s
320d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
320e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
320f0 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f  e_bytes(sqlite3_
32100 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
32110 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
32120 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  16(sqlite3_value
32130 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74  *);.double sqlit
32140 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28  e3_value_double(
32150 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
32160 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
32170 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76  ue_int(sqlite3_v
32180 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f  alue*);.sqlite3_
32190 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61  int64 sqlite3_va
321a0 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  lue_int64(sqlite
321b0 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
321c0 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a   unsigned char *
321d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
321e0 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  xt(sqlite3_value
321f0 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
32200 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
32210 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c  xt16(sqlite3_val
32220 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  ue*);.const void
32230 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
32240 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33  text16le(sqlite3
32250 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
32260 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
32270 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c  lue_text16be(sql
32280 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
32290 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
322a0 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
322b0 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
322c0 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f  3_value_numeric_
322d0 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
322e0 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ue*);../*.** CAP
322f0 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67  I3REF: Obtain Ag
32300 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e  gregate Function
32310 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49   Context.**.** I
32320 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
32330 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  f aggregate SQL 
32340 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68  functions use th
32350 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f  is.** routine to
32360 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
32370 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65   for storing the
32380 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  ir state..**.** 
32390 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20  ^The first time 
323a0 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72  the sqlite3_aggr
323b0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
323c0 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  N) routine is ca
323d0 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70  lled .** for a p
323e0 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 67  articular aggreg
323f0 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51  ate function, SQ
32400 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  Lite.** allocate
32410 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a  s N of memory, z
32420 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d  eroes out that m
32430 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72  emory, and retur
32440 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  ns a pointer.** 
32450 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72  to the new memor
32460 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e  y. ^On second an
32470 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  d subsequent cal
32480 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ls to.** sqlite3
32490 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
324a0 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d  xt() for the sam
324b0 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
324c0 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a  tion instance,.*
324d0 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65  * the same buffe
324e0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  r is returned.  
324f0 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  Sqlite3_aggregat
32500 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e  e_context() is n
32510 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65  ormally.** calle
32520 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20  d once for each 
32530 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68  invocation of th
32540 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b  e xStep callback
32550 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a   and then one.**
32560 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20   last time when 
32570 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62  the xFinal callb
32580 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20  ack is invoked. 
32590 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20   ^(When no rows 
325a0 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72  match.** an aggr
325b0 65 67 61 74 65 20 71 75 65 72 79 2c 20 74 68 65  egate query, the
325c0 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63   xStep() callbac
325d0 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61  k of the aggrega
325e0 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69  te function.** i
325f0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
32600 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e   never called an
32610 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61  d xFinal() is ca
32620 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63  lled exactly onc
32630 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63  e..** In those c
32640 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67  ases, sqlite3_ag
32650 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
32660 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65  ) might be calle
32670 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72  d for the.** fir
32680 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74  st time from wit
32690 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a  hin xFinal().)^.
326a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
326b0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
326c0 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e  text(C,N) routin
326d0 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  e returns a NULL
326e0 20 70 6f 69 6e 74 65 72 20 0a 2a 2a 20 77 68 65   pointer .** whe
326f0 6e 20 66 69 72 73 74 20 63 61 6c 6c 65 64 20 69  n first called i
32700 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e  f N is less than
32710 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72   or equal to zer
32720 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79  o or if a memory
32730 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 65 72 72  .** allocate err
32740 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a  or occurs..**.**
32750 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66   ^(The amount of
32760 20 73 70 61 63 65 20 61 6c 6c 6f 63 61 74 65 64   space allocated
32770 20 62 79 20 73 71 6c 69 74 65 33 5f 61 67 67 72   by sqlite3_aggr
32780 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
32790 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69  N) is.** determi
327a0 6e 65 64 20 62 79 20 74 68 65 20 4e 20 70 61 72  ned by the N par
327b0 61 6d 65 74 65 72 20 6f 6e 20 66 69 72 73 74 20  ameter on first 
327c0 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e  successful call.
327d0 20 20 43 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a    Changing the.*
327e0 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20  * value of N in 
327f0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20  subsequent call 
32800 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  to sqlite3_aggre
32810 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77  gate_context() w
32820 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d  ithin.** the sam
32830 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
32840 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77 69  tion instance wi
32850 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20 74 68  ll not resize th
32860 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
32870 63 61 74 69 6f 6e 2e 29 5e 20 20 57 69 74 68 69  cation.)^  Withi
32880 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c  n the xFinal cal
32890 6c 62 61 63 6b 2c 20 69 74 20 69 73 20 63 75 73  lback, it is cus
328a0 74 6f 6d 61 72 79 20 74 6f 20 73 65 74 0a 2a 2a  tomary to set.**
328b0 20 4e 3d 30 20 69 6e 20 63 61 6c 6c 73 20 74 6f   N=0 in calls to
328c0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
328d0 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20  te_context(C,N) 
328e0 73 6f 20 74 68 61 74 20 6e 6f 20 0a 2a 2a 20 70  so that no .** p
328f0 6f 69 6e 74 6c 65 73 73 20 6d 65 6d 6f 72 79 20  ointless memory 
32900 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 6f 63 63 75  allocations occu
32910 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  r..**.** ^SQLite
32920 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66   automatically f
32930 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20  rees the memory 
32940 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a  allocated by .**
32950 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
32960 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65  te_context() whe
32970 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  n the aggregate 
32980 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e  query concludes.
32990 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
329a0 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20   parameter must 
329b0 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  be a copy of the
329c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
329d0 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74  text | SQL funct
329e0 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61  ion context] tha
329f0 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70  t is the first p
32a00 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74  arameter.** to t
32a10 68 65 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e  he xStep or xFin
32a20 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74  al callback rout
32a30 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  ine that impleme
32a40 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61 74  nts the aggregat
32a50 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  e.** function..*
32a60 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
32a70 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  e must be called
32a80 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
32a90 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a  hread in which.*
32aa0 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  * the aggregate 
32ab0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
32ac0 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64  running..*/.void
32ad0 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   *sqlite3_aggreg
32ae0 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69  ate_context(sqli
32af0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
32b00 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a  t nBytes);../*.*
32b10 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72  * CAPI3REF: User
32b20 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69   Data For Functi
32b30 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ons.**.** ^The s
32b40 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
32b50 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
32b60 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a  urns a copy of.*
32b70 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68  * the pointer th
32b80 61 74 20 77 61 73 20 74 68 65 20 70 55 73 65 72  at was the pUser
32b90 44 61 74 61 20 70 61 72 61 6d 65 74 65 72 20 28  Data parameter (
32ba0 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
32bb0 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  r).** of the [sq
32bc0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
32bd0 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20  ction()].** and 
32be0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
32bf0 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f  function16()] ro
32c00 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67  utines that orig
32c10 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74  inally.** regist
32c20 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61  ered the applica
32c30 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e  tion defined fun
32c40 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  ction..**.** Thi
32c50 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62  s routine must b
32c60 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
32c70 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
32c80 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70   which.** the ap
32c90 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
32ca0 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  d function is ru
32cb0 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  nning..*/.void *
32cc0 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
32cd0 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
32ce0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
32cf0 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
32d00 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75  onnection For Fu
32d10 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54  nctions.**.** ^T
32d20 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  he sqlite3_conte
32d30 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69  xt_db_handle() i
32d40 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
32d50 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
32d60 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  e pointer to the
32d70 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
32d80 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20  ction] (the 1st 
32d90 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66  parameter).** of
32da0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
32db0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
32dc0 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
32dd0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
32de0 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74  16()] routines t
32df0 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a  hat originally.*
32e00 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65  * registered the
32e10 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
32e20 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ined function..*
32e30 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74  /.sqlite3 *sqlit
32e40 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
32e50 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  ndle(sqlite3_con
32e60 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  text*);../*.** C
32e70 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f  API3REF: Functio
32e80 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74 61  n Auxiliary Data
32e90 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e  .**.** These fun
32ea0 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73  ctions may be us
32eb0 65 64 20 62 79 20 28 6e 6f 6e 2d 61 67 67 72 65  ed by (non-aggre
32ec0 67 61 74 65 29 20 53 51 4c 20 66 75 6e 63 74 69  gate) SQL functi
32ed0 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69  ons to.** associ
32ee0 61 74 65 20 6d 65 74 61 64 61 74 61 20 77 69 74  ate metadata wit
32ef0 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65  h argument value
32f00 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 76  s. If the same v
32f10 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 74  alue is passed t
32f20 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e  o.** multiple in
32f30 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
32f40 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69   same SQL functi
32f50 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 20  on during query 
32f60 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72  execution, under
32f70 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73  .** some circums
32f80 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63  tances the assoc
32f90 69 61 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d  iated metadata m
32fa0 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64 2e  ay be preserved.
32fb0 20 20 41 6e 20 65 78 61 6d 70 6c 65 0a 2a 2a 20    An example.** 
32fc0 6f 66 20 77 68 65 72 65 20 74 68 69 73 20 6d 69  of where this mi
32fd0 67 68 74 20 62 65 20 75 73 65 66 75 6c 20 69 73  ght be useful is
32fe0 20 69 6e 20 61 20 72 65 67 75 6c 61 72 2d 65 78   in a regular-ex
32ff0 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e  pression matchin
33000 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54  g.** function. T
33010 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73  he compiled vers
33020 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c  ion of the regul
33030 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61  ar expression ca
33040 6e 20 62 65 20 73 74 6f 72 65 64 20 61 73 0a 2a  n be stored as.*
33050 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63  * metadata assoc
33060 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 70  iated with the p
33070 61 74 74 65 72 6e 20 73 74 72 69 6e 67 2e 20 20  attern string.  
33080 0a 2a 2a 20 54 68 65 6e 20 61 73 20 6c 6f 6e 67  .** Then as long
33090 20 61 73 20 74 68 65 20 70 61 74 74 65 72 6e 20   as the pattern 
330a0 73 74 72 69 6e 67 20 72 65 6d 61 69 6e 73 20 74  string remains t
330b0 68 65 20 73 61 6d 65 2c 0a 2a 2a 20 74 68 65 20  he same,.** the 
330c0 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72  compiled regular
330d0 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20   expression can 
330e0 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c  be reused on mul
330f0 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74  tiple.** invocat
33100 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
33110 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
33120 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65   ^The sqlite3_ge
33130 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65  t_auxdata() inte
33140 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
33150 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d  pointer to the m
33160 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63  etadata.** assoc
33170 69 61 74 65 64 20 62 79 20 74 68 65 20 73 71 6c  iated by the sql
33180 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
33190 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68  () function with
331a0 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e   the Nth argumen
331b0 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68  t.** value to th
331c0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
331d0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20  fined function. 
331e0 5e 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20  ^If there is no 
331f0 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f  metadata.** asso
33200 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
33210 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
33220 74 2c 20 74 68 69 73 20 73 71 6c 69 74 65 33 5f  t, this sqlite3_
33230 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  get_auxdata() in
33240 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72  terface.** retur
33250 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
33260 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
33270 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
33280 61 28 43 2c 4e 2c 50 2c 58 29 20 69 6e 74 65 72  a(C,N,P,X) inter
33290 66 61 63 65 20 73 61 76 65 73 20 50 20 61 73 20  face saves P as 
332a0 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68 65  metadata for the
332b0 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e   N-th.** argumen
332c0 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  t of the applica
332d0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
332e0 63 74 69 6f 6e 2e 20 20 5e 53 75 62 73 65 71 75  ction.  ^Subsequ
332f0 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ent.** calls to 
33300 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
33310 61 74 61 28 43 2c 4e 29 20 72 65 74 75 72 6e 20  ata(C,N) return 
33320 50 20 66 72 6f 6d 20 74 68 65 20 6d 6f 73 74 20  P from the most 
33330 72 65 63 65 6e 74 0a 2a 2a 20 73 71 6c 69 74 65  recent.** sqlite
33340 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c  3_set_auxdata(C,
33350 4e 2c 50 2c 58 29 20 63 61 6c 6c 20 69 66 20 74  N,P,X) call if t
33360 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 73  he metadata is s
33370 74 69 6c 6c 20 76 61 6c 69 64 20 6f 72 0a 2a 2a  till valid or.**
33380 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 6d 65 74   NULL if the met
33390 61 64 61 74 61 20 68 61 73 20 62 65 65 6e 20 64  adata has been d
333a0 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20 5e 41 66  iscarded..** ^Af
333b0 74 65 72 20 65 61 63 68 20 63 61 6c 6c 20 74 6f  ter each call to
333c0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
333d0 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 77 68  data(C,N,P,X) wh
333e0 65 72 65 20 58 20 69 73 20 6e 6f 74 20 4e 55 4c  ere X is not NUL
333f0 4c 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c  L,.** SQLite wil
33400 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73  l invoke the des
33410 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e  tructor function
33420 20 58 20 77 69 74 68 20 70 61 72 61 6d 65 74 65   X with paramete
33430 72 20 50 20 65 78 61 63 74 6c 79 0a 2a 2a 20 6f  r P exactly.** o
33440 6e 63 65 2c 20 77 68 65 6e 20 74 68 65 20 6d 65  nce, when the me
33450 74 61 64 61 74 61 20 69 73 20 64 69 73 63 61 72  tadata is discar
33460 64 65 64 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ded..** SQLite i
33470 73 20 66 72 65 65 20 74 6f 20 64 69 73 63 61 72  s free to discar
33480 64 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 61  d the metadata a
33490 74 20 61 6e 79 20 74 69 6d 65 2c 20 69 6e 63 6c  t any time, incl
334a0 75 64 69 6e 67 3a 20 3c 75 6c 3e 0a 2a 2a 20 3c  uding: <ul>.** <
334b0 6c 69 3e 20 77 68 65 6e 20 74 68 65 20 63 6f 72  li> when the cor
334c0 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74  responding funct
334d0 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68  ion parameter ch
334e0 61 6e 67 65 73 2c 20 6f 72 0a 2a 2a 20 3c 6c 69  anges, or.** <li
334f0 3e 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  > when [sqlite3_
33500 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
33510 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
33520 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 74   is called for t
33530 68 65 0a 2a 2a 20 20 20 20 20 20 53 51 4c 20 73  he.**      SQL s
33540 74 61 74 65 6d 65 6e 74 2c 20 6f 72 0a 2a 2a 20  tatement, or.** 
33550 3c 6c 69 3e 20 77 68 65 6e 20 73 71 6c 69 74 65  <li> when sqlite
33560 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
33570 69 73 20 69 6e 76 6f 6b 65 64 20 61 67 61 69 6e  is invoked again
33580 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 70 61 72   on the same par
33590 61 6d 65 74 65 72 2c 20 6f 72 0a 2a 2a 20 3c 6c  ameter, or.** <l
335a0 69 3e 20 64 75 72 69 6e 67 20 74 68 65 20 6f 72  i> during the or
335b0 69 67 69 6e 61 6c 20 73 71 6c 69 74 65 33 5f 73  iginal sqlite3_s
335c0 65 74 5f 61 75 78 64 61 74 61 28 29 20 63 61 6c  et_auxdata() cal
335d0 6c 20 77 68 65 6e 20 61 20 6d 65 6d 6f 72 79 20  l when a memory 
335e0 0a 2a 2a 20 20 20 20 20 20 61 6c 6c 6f 63 61 74  .**      allocat
335f0 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ion error occurs
33600 2e 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  . </ul>)^.**.** 
33610 4e 6f 74 65 20 74 68 65 20 6c 61 73 74 20 62 75  Note the last bu
33620 6c 6c 65 74 20 69 6e 20 70 61 72 74 69 63 75 6c  llet in particul
33630 61 72 2e 20 20 54 68 65 20 64 65 73 74 72 75 63  ar.  The destruc
33640 74 6f 72 20 58 20 69 6e 20 0a 2a 2a 20 73 71 6c  tor X in .** sql
33650 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
33660 28 43 2c 4e 2c 50 2c 58 29 20 6d 69 67 68 74 20  (C,N,P,X) might 
33670 62 65 20 63 61 6c 6c 65 64 20 69 6d 6d 65 64 69  be called immedi
33680 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 20 74 68  ately, before th
33690 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74  e.** sqlite3_set
336a0 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72  _auxdata() inter
336b0 66 61 63 65 20 65 76 65 6e 20 72 65 74 75 72 6e  face even return
336c0 73 2e 20 20 48 65 6e 63 65 20 73 71 6c 69 74 65  s.  Hence sqlite
336d0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 0a  3_set_auxdata().
336e0 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 63 61 6c  ** should be cal
336f0 6c 65 64 20 6e 65 61 72 20 74 68 65 20 65 6e 64  led near the end
33700 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
33710 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
33720 61 6e 64 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74  and the.** funct
33730 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
33740 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 6d 61  on should not ma
33750 6b 65 20 61 6e 79 20 75 73 65 20 6f 66 20 50 20  ke any use of P 
33760 61 66 74 65 72 0a 2a 2a 20 73 71 6c 69 74 65 33  after.** sqlite3
33770 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 68  _set_auxdata() h
33780 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 2e 0a  as been called..
33790 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74  **.** ^(In pract
337a0 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73  ice, metadata is
337b0 20 70 72 65 73 65 72 76 65 64 20 62 65 74 77 65   preserved betwe
337c0 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c  en function call
337d0 73 20 66 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  s for.** functio
337e0 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61  n parameters tha
337f0 74 20 61 72 65 20 63 6f 6d 70 69 6c 65 2d 74 69  t are compile-ti
33800 6d 65 20 63 6f 6e 73 74 61 6e 74 73 2c 20 69 6e  me constants, in
33810 63 6c 75 64 69 6e 67 20 6c 69 74 65 72 61 6c 0a  cluding literal.
33820 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 5b 70  ** values and [p
33830 61 72 61 6d 65 74 65 72 73 5d 20 61 6e 64 20 65  arameters] and e
33840 78 70 72 65 73 73 69 6f 6e 73 20 63 6f 6d 70 6f  xpressions compo
33850 73 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  sed from the sam
33860 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  e.)^.**.** These
33870 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
33880 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
33890 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
338a0 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51   which.** the SQ
338b0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  L function is ru
338c0 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  nning..*/.void *
338d0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
338e0 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
338f0 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f  ext*, int N);.vo
33900 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  id sqlite3_set_a
33910 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  uxdata(sqlite3_c
33920 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20  ontext*, int N, 
33930 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28  void*, void (*)(
33940 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  void*));.../*.**
33950 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74   CAPI3REF: Const
33960 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70  ants Defining Sp
33970 65 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72  ecial Destructor
33980 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20   Behavior.**.** 
33990 54 68 65 73 65 20 61 72 65 20 73 70 65 63 69 61  These are specia
339a0 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65  l values for the
339b0 20 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 74   destructor that
339c0 20 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 73   is passed in as
339d0 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72   the.** final ar
339e0 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e  gument to routin
339f0 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33  es like [sqlite3
33a00 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e  _result_blob()].
33a10 20 20 5e 49 66 20 74 68 65 20 64 65 73 74 72 75    ^If the destru
33a20 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  ctor.** argument
33a30 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49   is SQLITE_STATI
33a40 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74  C, it means that
33a50 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69   the content poi
33a60 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74  nter is constant
33a70 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76  .** and will nev
33a80 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64  er change.  It d
33a90 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
33aa0 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20 5e  be destroyed.  ^
33ab0 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52  The.** SQLITE_TR
33ac0 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65  ANSIENT value me
33ad0 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e  ans that the con
33ae0 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79  tent will likely
33af0 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68   change in.** th
33b00 65 20 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e  e near future an
33b10 64 20 74 68 61 74 20 53 51 4c 69 74 65 20 73 68  d that SQLite sh
33b20 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77  ould make its ow
33b30 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
33b40 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74  f.** the content
33b50 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e   before returnin
33b60 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70  g..**.** The typ
33b70 65 64 65 66 20 69 73 20 6e 65 63 65 73 73 61 72  edef is necessar
33b80 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64  y to work around
33b90 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72   problems in cer
33ba0 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70  tain.** C++ comp
33bb0 69 6c 65 72 73 2e 0a 2a 2f 0a 74 79 70 65 64 65  ilers..*/.typede
33bc0 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33  f void (*sqlite3
33bd0 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
33be0 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e  )(void*);.#defin
33bf0 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20  e SQLITE_STATIC 
33c00 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64       ((sqlite3_d
33c10 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30  estructor_type)0
33c20 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
33c30 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73  _TRANSIENT   ((s
33c40 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
33c50 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a  r_type)-1)../*.*
33c60 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 74  * CAPI3REF: Sett
33c70 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f  ing The Result O
33c80 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f  f An SQL Functio
33c90 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  n.**.** These ro
33ca0 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20  utines are used 
33cb0 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20  by the xFunc or 
33cc0 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73  xFinal callbacks
33cd0 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65   that.** impleme
33ce0 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  nt SQL functions
33cf0 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e   and aggregates.
33d00 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    See.** [sqlite
33d10 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
33d20 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
33d30 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
33d40 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64  n16()].** for ad
33d50 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
33d60 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tion..**.** Thes
33d70 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b  e functions work
33d80 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20   very much like 
33d90 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62  the [parameter b
33da0 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f  inding] family o
33db0 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75  f.** functions u
33dc0 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75  sed to bind valu
33dd0 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d  es to host param
33de0 65 74 65 72 73 20 69 6e 20 70 72 65 70 61 72 65  eters in prepare
33df0 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  d statements..**
33e00 20 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53   Refer to the [S
33e10 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f  QL parameter] do
33e20 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20  cumentation for 
33e30 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
33e40 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  mation..**.** ^T
33e50 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
33e60 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61  t_blob() interfa
33e70 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
33e80 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70  lt from.** an ap
33e90 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
33ea0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
33eb0 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20   the BLOB whose 
33ec0 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74  content is point
33ed0 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20  ed.** to by the 
33ee0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
33ef0 20 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20   and which is N 
33f00 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65  bytes long where
33f10 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69   N is the.** thi
33f20 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  rd parameter..**
33f30 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
33f40 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62  _result_zeroblob
33f50 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 73 65  () interfaces se
33f60 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a  t the result of.
33f70 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
33f80 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
33f90 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42  ion to be a BLOB
33fa0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20   containing all 
33fb0 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e  zero.** bytes an
33fc0 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  d N bytes in siz
33fd0 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  e, where N is th
33fe0 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32  e value of the 2
33ff0 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  nd parameter..**
34000 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
34010 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29  _result_double()
34020 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
34030 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a  the result from.
34040 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ** an applicatio
34050 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
34060 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74  on to be a float
34070 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20  ing point value 
34080 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20  specified.** by 
34090 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  its 2nd argument
340a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
340b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
340c0 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  r() and sqlite3_
340d0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
340e0 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61   functions.** ca
340f0 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  use the implemen
34100 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ted SQL function
34110 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63   to throw an exc
34120 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69  eption..** ^SQLi
34130 74 65 20 75 73 65 73 20 74 68 65 20 73 74 72 69  te uses the stri
34140 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ng pointed to by
34150 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61   the.** 2nd para
34160 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33  meter of sqlite3
34170 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
34180 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
34190 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61  t_error16().** a
341a0 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e  s the text of an
341b0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20   error message. 
341c0 20 5e 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72   ^SQLite interpr
341d0 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a  ets the error.**
341e0 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
341f0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73  from sqlite3_res
34200 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55  ult_error() as U
34210 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a  TF-8. ^SQLite.**
34220 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
34230 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69  string from sqli
34240 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
34250 31 36 28 29 20 61 73 20 55 54 46 2d 31 36 20 69  16() as UTF-16 i
34260 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65  n native.** byte
34270 20 6f 72 64 65 72 2e 20 20 5e 49 66 20 74 68 65   order.  ^If the
34280 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
34290 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
342a0 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72  lt_error().** or
342b0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
342c0 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67  error16() is neg
342d0 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74  ative then SQLit
342e0 65 20 74 61 6b 65 73 20 61 73 20 74 68 65 20 65  e takes as the e
342f0 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20  rror.** message 
34300 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f  all text up thro
34310 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65  ugh the first ze
34320 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  ro character..**
34330 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70   ^If the third p
34340 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
34350 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
34360 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
34370 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
34380 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  ) is non-negativ
34390 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  e then SQLite ta
343a0 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a  kes that many.**
343b0 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72   bytes (not char
343c0 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65  acters) from the
343d0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
343e0 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  s the error mess
343f0 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  age..** ^The sql
34400 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
34410 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  r() and sqlite3_
34420 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
34430 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b  .** routines mak
34440 65 20 61 20 70 72 69 76 61 74 65 20 63 6f 70 79  e a private copy
34450 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65   of the error me
34460 73 73 61 67 65 20 74 65 78 74 20 62 65 66 6f 72  ssage text befor
34470 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e  e.** they return
34480 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61  .  Hence, the ca
34490 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63  lling function c
344a0 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72  an deallocate or
344b0 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74  .** modify the t
344c0 65 78 74 20 61 66 74 65 72 20 74 68 65 79 20 72  ext after they r
344d0 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61  eturn without ha
344e0 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  rm..** ^The sqli
344f0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
34500 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e  _code() function
34510 20 63 68 61 6e 67 65 73 20 74 68 65 20 65 72 72   changes the err
34520 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72  or code.** retur
34530 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 73  ned by SQLite as
34540 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20   a result of an 
34550 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74  error in a funct
34560 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61 75 6c  ion.  ^By defaul
34570 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20  t,.** the error 
34580 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f 45  code is SQLITE_E
34590 52 52 4f 52 2e 20 20 5e 41 20 73 75 62 73 65 71  RROR.  ^A subseq
345a0 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c  uent call to sql
345b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
345c0 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  r().** or sqlite
345d0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
345e0 28 29 20 72 65 73 65 74 73 20 74 68 65 20 65 72  () resets the er
345f0 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49  ror code to SQLI
34600 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20  TE_ERROR..**.** 
34610 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
34620 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67  ult_error_toobig
34630 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  () interface cau
34640 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68  ses SQLite to th
34650 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20  row an.** error 
34660 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20  indicating that 
34670 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  a string or BLOB
34680 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20   is too long to 
34690 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a  represent..**.**
346a0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
346b0 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d  sult_error_nomem
346c0 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  () interface cau
346d0 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68  ses SQLite to th
346e0 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20  row an.** error 
346f0 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20  indicating that 
34700 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
34710 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a  ion failed..**.*
34720 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
34730 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65  esult_int() inte
34740 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
34750 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f  eturn value.** o
34760 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
34770 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
34780 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d  on to be the 32-
34790 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
347a0 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65  er.** value give
347b0 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67  n in the 2nd arg
347c0 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 73  ument..** ^The s
347d0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
347e0 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 20  t64() interface 
347f0 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20  sets the return 
34800 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20  value.** of the 
34810 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
34820 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
34830 62 65 20 74 68 65 20 36 34 2d 62 69 74 20 73 69  be the 64-bit si
34840 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
34850 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74  value given in t
34860 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e  he 2nd argument.
34870 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
34880 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28  te3_result_null(
34890 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
348a0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
348b0 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c  e.** of the appl
348c0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
348d0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e  function to be N
348e0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ULL..**.** ^The 
348f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
34900 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 72  ext(), sqlite3_r
34910 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a  esult_text16(),.
34920 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
34930 74 5f 74 65 78 74 31 36 6c 65 28 29 2c 20 61 6e  t_text16le(), an
34940 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
34950 5f 74 65 78 74 31 36 62 65 28 29 20 69 6e 74 65  _text16be() inte
34960 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 20 74 68  rfaces.** set th
34970 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
34980 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
34990 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
349a0 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65  on to be.** a te
349b0 78 74 20 73 74 72 69 6e 67 20 77 68 69 63 68 20  xt string which 
349c0 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 61  is represented a
349d0 73 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 20  s UTF-8, UTF-16 
349e0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
349f0 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74  r,.** UTF-16 lit
34a00 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55  tle endian, or U
34a10 54 46 2d 31 36 20 62 69 67 20 65 6e 64 69 61 6e  TF-16 big endian
34a20 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  , respectively..
34a30 2a 2a 20 5e 53 51 4c 69 74 65 20 74 61 6b 65 73  ** ^SQLite takes
34a40 20 74 68 65 20 74 65 78 74 20 72 65 73 75 6c 74   the text result
34a50 20 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63   from the applic
34a60 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68  ation from.** th
34a70 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
34a80 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  of the sqlite3_r
34a90 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
34aa0 72 66 61 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74  rfaces..** ^If t
34ab0 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
34ac0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
34ad0 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
34ae0 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65  erfaces.** is ne
34af0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c  gative, then SQL
34b00 69 74 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74  ite takes result
34b10 20 74 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32   text from the 2
34b20 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  nd parameter.** 
34b30 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73  through the firs
34b40 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72  t zero character
34b50 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64  ..** ^If the 3rd
34b60 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
34b70 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
34b80 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
34b90 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  s.** is non-nega
34ba0 74 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61  tive, then as ma
34bb0 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68  ny bytes (not ch
34bc0 61 72 61 63 74 65 72 73 29 20 6f 66 20 74 68 65  aracters) of the
34bd0 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64   text.** pointed
34be0 20 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70   to by the 2nd p
34bf0 61 72 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b  arameter are tak
34c00 65 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69 63  en as the applic
34c10 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a  ation-defined.**
34c20 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74   function result
34c30 2e 20 20 49 66 20 74 68 65 20 33 72 64 20 70 61  .  If the 3rd pa
34c40 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 6e  rameter is non-n
34c50 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74  egative, then it
34c60 0a 2a 2a 20 6d 75 73 74 20 62 65 20 74 68 65 20  .** must be the 
34c70 62 79 74 65 20 6f 66 66 73 65 74 20 69 6e 74 6f  byte offset into
34c80 20 74 68 65 20 73 74 72 69 6e 67 20 77 68 65 72   the string wher
34c90 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e  e the NUL termin
34ca0 61 74 6f 72 20 77 6f 75 6c 64 0a 2a 2a 20 61 70  ator would.** ap
34cb0 70 65 61 72 20 69 66 20 74 68 65 20 73 74 72 69  pear if the stri
34cc0 6e 67 20 77 68 65 72 65 20 4e 55 4c 20 74 65 72  ng where NUL ter
34cd0 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79  minated.  If any
34ce0 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 20   NUL characters 
34cf0 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20  occur.** in the 
34d00 73 74 72 69 6e 67 20 61 74 20 61 20 62 79 74 65  string at a byte
34d10 20 6f 66 66 73 65 74 20 74 68 61 74 20 69 73 20   offset that is 
34d20 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20 76 61  less than the va
34d30 6c 75 65 20 6f 66 20 74 68 65 20 33 72 64 0a 2a  lue of the 3rd.*
34d40 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65  * parameter, the
34d50 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  n the resulting 
34d60 73 74 72 69 6e 67 20 77 69 6c 6c 20 63 6f 6e 74  string will cont
34d70 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ain embedded NUL
34d80 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 72 65 73  s and the.** res
34d90 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f  ult of expressio
34da0 6e 73 20 6f 70 65 72 61 74 69 6e 67 20 6f 6e 20  ns operating on 
34db0 73 74 72 69 6e 67 73 20 77 69 74 68 20 65 6d 62  strings with emb
34dc0 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e  edded NULs is un
34dd0 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20  defined..** ^If 
34de0 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
34df0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
34e00 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
34e10 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73  terfaces.** or s
34e20 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
34e30 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c  ob is a non-NULL
34e40 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53   pointer, then S
34e50 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74  QLite calls that
34e60 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20  .** function as 
34e70 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f  the destructor o
34e80 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c  n the text or BL
34e90 4f 42 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69  OB result when i
34ea0 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65  t has.** finishe
34eb0 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73  d using that res
34ec0 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ult..** ^If the 
34ed0 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
34ee0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
34ef0 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
34f00 61 63 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71  aces or to.** sq
34f10 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
34f20 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c  b is the special
34f30 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45   constant SQLITE
34f40 5f 53 54 41 54 49 43 2c 20 74 68 65 6e 20 53 51  _STATIC, then SQ
34f50 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20  Lite.** assumes 
34f60 74 68 61 74 20 74 68 65 20 74 65 78 74 20 6f 72  that the text or
34f70 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 20   BLOB result is 
34f80 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63  in constant spac
34f90 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a  e and does not.*
34fa0 2a 20 63 6f 70 79 20 74 68 65 20 63 6f 6e 74 65  * copy the conte
34fb0 6e 74 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65  nt of the parame
34fc0 74 65 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64  ter nor call a d
34fd0 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65  estructor on the
34fe0 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e   content.** when
34ff0 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64   it has finished
35000 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75   using that resu
35010 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34  lt..** ^If the 4
35020 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
35030 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
35040 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
35050 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  ces.** or sqlite
35060 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73  3_result_blob is
35070 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e   the special con
35080 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41  stant SQLITE_TRA
35090 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53  NSIENT.** then S
350a0 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f  QLite makes a co
350b0 70 79 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  py of the result
350c0 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61   into space obta
350d0 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f  ined from.** fro
350e0 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
350f0 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72  c()] before it r
35100 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eturns..**.** ^T
35110 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
35120 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66  t_value() interf
35130 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
35140 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70  ult of.** the ap
35150 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
35160 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
35170 20 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b   a copy the.** [
35180 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
35190 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
351a0 74 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  t specified by t
351b0 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
351c0 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74  .  ^The.** sqlit
351d0 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
351e0 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65  ) interface make
351f0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
35200 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a  [sqlite3_value].
35210 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b  ** so that the [
35220 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73  sqlite3_value] s
35230 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20  pecified in the 
35240 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68  parameter may ch
35250 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65  ange or.** be de
35260 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20  allocated after 
35270 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
35280 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73 20 77  alue() returns w
35290 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20  ithout harm..** 
352a0 5e 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  ^A [protected sq
352b0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
352c0 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62  ect may always b
352d0 65 20 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a  e used where an.
352e0 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
352f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
35300 62 6a 65 63 74 20 69 73 20 72 65 71 75 69 72 65  bject is require
35310 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20  d, so either.** 
35320 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33  kind of [sqlite3
35330 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63  _value] object c
35340 61 6e 20 62 65 20 75 73 65 64 20 77 69 74 68 20  an be used with 
35350 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a  this interface..
35360 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72  **.** If these r
35370 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
35380 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74  ed from within t
35390 68 65 20 64 69 66 66 65 72 65 6e 74 20 74 68 72  he different thr
353a0 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20  ead.** than the 
353b0 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  one containing t
353c0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
353d0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
353e0 74 68 61 74 20 72 65 63 65 69 76 65 64 0a 2a 2a  that received.**
353f0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
35400 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20  ntext] pointer, 
35410 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
35420 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f  undefined..*/.vo
35430 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
35440 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63  t_blob(sqlite3_c
35450 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
35460 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
35470 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
35480 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35490 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63  double(sqlite3_c
354a0 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29  ontext*, double)
354b0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
354c0 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69  esult_error(sqli
354d0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
354e0 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b  nst char*, int);
354f0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
35500 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c  sult_error16(sql
35510 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
35520 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29  onst void*, int)
35530 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
35540 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62  esult_error_toob
35550 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ig(sqlite3_conte
35560 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  xt*);.void sqlit
35570 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
35580 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f  nomem(sqlite3_co
35590 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71  ntext*);.void sq
355a0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
355b0 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 5f  or_code(sqlite3_
355c0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a  context*, int);.
355d0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
355e0 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  ult_int(sqlite3_
355f0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a  context*, int);.
35600 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
35610 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  ult_int64(sqlite
35620 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69  3_context*, sqli
35630 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64  te3_int64);.void
35640 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35650 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e  null(sqlite3_con
35660 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  text*);.void sql
35670 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
35680 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
35690 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  *, const char*, 
356a0 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
356b0 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
356c0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
356d0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
356e0 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
356f0 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
35700 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
35710 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
35720 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
35730 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
35740 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f  , int,void(*)(vo
35750 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
35760 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
35770 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  6be(sqlite3_cont
35780 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
35790 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76  *, int,void(*)(v
357a0 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
357b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
357c0 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
357d0 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  t*, sqlite3_valu
357e0 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  e*);.void sqlite
357f0 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f  3_result_zeroblo
35800 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  b(sqlite3_contex
35810 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a  t*, int n);../*.
35820 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 66  ** CAPI3REF: Def
35830 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e  ine New Collatin
35840 67 20 53 65 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a  g Sequences.**.*
35850 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f  * ^These functio
35860 6e 73 20 61 64 64 2c 20 72 65 6d 6f 76 65 2c 20  ns add, remove, 
35870 6f 72 20 6d 6f 64 69 66 79 20 61 20 5b 63 6f 6c  or modify a [col
35880 6c 61 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74  lation] associat
35890 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  ed.** with the [
358a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
358b0 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 61  ion] specified a
358c0 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
358d0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ment..**.** ^The
358e0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c   name of the col
358f0 6c 61 74 69 6f 6e 20 69 73 20 61 20 55 54 46 2d  lation is a UTF-
35900 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20  8 string.** for 
35910 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
35920 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 73  ollation() and s
35930 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
35940 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20  llation_v2().** 
35950 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74 72  and a UTF-16 str
35960 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79  ing in native by
35970 74 65 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c  te order for sql
35980 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
35990 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 20 5e 43  ation16()..** ^C
359a0 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 73 20 74  ollation names t
359b0 68 61 74 20 63 6f 6d 70 61 72 65 20 65 71 75 61  hat compare equa
359c0 6c 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 5b  l according to [
359d0 73 71 6c 69 74 65 33 5f 73 74 72 6e 69 63 6d 70  sqlite3_strnicmp
359e0 28 29 5d 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69  ()] are.** consi
359f0 64 65 72 65 64 20 74 6f 20 62 65 20 74 68 65 20  dered to be the 
35a00 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a  same name..**.**
35a10 20 5e 28 54 68 65 20 74 68 69 72 64 20 61 72 67   ^(The third arg
35a20 75 6d 65 6e 74 20 28 65 54 65 78 74 52 65 70 29  ument (eTextRep)
35a30 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 20   must be one of 
35a40 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a  the constants:.*
35a50 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
35a60 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a  SQLITE_UTF8],.**
35a70 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54   <li> [SQLITE_UT
35a80 46 31 36 4c 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  F16LE],.** <li> 
35a90 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
35aa0 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
35ab0 45 5f 55 54 46 31 36 5d 2c 20 6f 72 0a 2a 2a 20  E_UTF16], or.** 
35ac0 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46  <li> [SQLITE_UTF
35ad0 31 36 5f 41 4c 49 47 4e 45 44 5d 2e 0a 2a 2a 20  16_ALIGNED]..** 
35ae0 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 54 68 65 20  </ul>)^.** ^The 
35af0 65 54 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e  eTextRep argumen
35b00 74 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65  t determines the
35b10 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 73 74 72   encoding of str
35b20 69 6e 67 73 20 70 61 73 73 65 64 0a 2a 2a 20 74  ings passed.** t
35b30 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  o the collating 
35b40 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63  function callbac
35b50 6b 2c 20 78 43 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  k, xCallback..**
35b60 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54   ^The [SQLITE_UT
35b70 46 31 36 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45  F16] and [SQLITE
35b80 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20  _UTF16_ALIGNED] 
35b90 76 61 6c 75 65 73 20 66 6f 72 20 65 54 65 78 74  values for eText
35ba0 52 65 70 0a 2a 2a 20 66 6f 72 63 65 20 73 74 72  Rep.** force str
35bb0 69 6e 67 73 20 74 6f 20 62 65 20 55 54 46 31 36  ings to be UTF16
35bc0 20 77 69 74 68 20 6e 61 74 69 76 65 20 62 79 74   with native byt
35bd0 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 54 68 65  e order..** ^The
35be0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41   [SQLITE_UTF16_A
35bf0 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 20 66 6f  LIGNED] value fo
35c00 72 20 65 54 65 78 74 52 65 70 20 66 6f 72 63 65  r eTextRep force
35c10 73 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65 67  s strings to beg
35c20 69 6e 0a 2a 2a 20 6f 6e 20 61 6e 20 65 76 65 6e  in.** on an even
35c30 20 62 79 74 65 20 61 64 64 72 65 73 73 2e 0a 2a   byte address..*
35c40 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68  *.** ^The fourth
35c50 20 61 72 67 75 6d 65 6e 74 2c 20 70 41 72 67 2c   argument, pArg,
35c60 20 69 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69   is an applicati
35c70 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20  on data pointer 
35c80 74 68 61 74 20 69 73 20 70 61 73 73 65 64 0a 2a  that is passed.*
35c90 2a 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65  * through as the
35ca0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
35cb0 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67  to the collating
35cc0 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61   function callba
35cd0 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ck..**.** ^The f
35ce0 69 66 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 78  ifth argument, x
35cf0 43 61 6c 6c 62 61 63 6b 2c 20 69 73 20 61 20 70  Callback, is a p
35d00 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 63 6f  ointer to the co
35d10 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
35d20 2e 0a 2a 2a 20 5e 4d 75 6c 74 69 70 6c 65 20 63  ..** ^Multiple c
35d30 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
35d40 6e 73 20 63 61 6e 20 62 65 20 72 65 67 69 73 74  ns can be regist
35d50 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 73  ered using the s
35d60 61 6d 65 20 6e 61 6d 65 20 62 75 74 0a 2a 2a 20  ame name but.** 
35d70 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 65  with different e
35d80 54 65 78 74 52 65 70 20 70 61 72 61 6d 65 74 65  TextRep paramete
35d90 72 73 20 61 6e 64 20 53 51 4c 69 74 65 20 77 69  rs and SQLite wi
35da0 6c 6c 20 75 73 65 20 77 68 69 63 68 65 76 65 72  ll use whichever
35db0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  .** function req
35dc0 75 69 72 65 73 20 74 68 65 20 6c 65 61 73 74 20  uires the least 
35dd0 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 74  amount of data t
35de0 72 61 6e 73 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  ransformation..*
35df0 2a 20 5e 49 66 20 74 68 65 20 78 43 61 6c 6c 62  * ^If the xCallb
35e00 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ack argument is 
35e10 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f  NULL then the co
35e20 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
35e30 20 69 73 0a 2a 2a 20 64 65 6c 65 74 65 64 2e 20   is.** deleted. 
35e40 20 5e 57 68 65 6e 20 61 6c 6c 20 63 6f 6c 6c 61   ^When all colla
35e50 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 68  ting functions h
35e60 61 76 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e  aving the same n
35e70 61 6d 65 20 61 72 65 20 64 65 6c 65 74 65 64 2c  ame are deleted,
35e80 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 6c 61 74 69  .** that collati
35e90 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  on is no longer 
35ea0 75 73 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  usable..**.** ^T
35eb0 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
35ec0 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 20 69  ction callback i
35ed0 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61  s invoked with a
35ee0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 70 41 72   copy of the pAr
35ef0 67 20 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  g .** applicatio
35f00 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 61  n data pointer a
35f10 6e 64 20 77 69 74 68 20 74 77 6f 20 73 74 72 69  nd with two stri
35f20 6e 67 73 20 69 6e 20 74 68 65 20 65 6e 63 6f 64  ngs in the encod
35f30 69 6e 67 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  ing specified.**
35f40 20 62 79 20 74 68 65 20 65 54 65 78 74 52 65 70   by the eTextRep
35f50 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 65 20   argument.  The 
35f60 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
35f70 6f 6e 20 6d 75 73 74 20 72 65 74 75 72 6e 20 61  on must return a
35f80 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 74 68 61  n.** integer tha
35f90 74 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 7a  t is negative, z
35fa0 65 72 6f 2c 20 6f 72 20 70 6f 73 69 74 69 76 65  ero, or positive
35fb0 0a 2a 2a 20 69 66 20 74 68 65 20 66 69 72 73 74  .** if the first
35fc0 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73 20   string is less 
35fd0 74 68 61 6e 2c 20 65 71 75 61 6c 20 74 6f 2c 20  than, equal to, 
35fe0 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  or greater than 
35ff0 74 68 65 20 73 65 63 6f 6e 64 2c 0a 2a 2a 20 72  the second,.** r
36000 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20 41 20  espectively.  A 
36010 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
36020 6f 6e 20 6d 75 73 74 20 61 6c 77 61 79 73 20 72  on must always r
36030 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20 61  eturn the same a
36040 6e 73 77 65 72 0a 2a 2a 20 67 69 76 65 6e 20 74  nswer.** given t
36050 68 65 20 73 61 6d 65 20 69 6e 70 75 74 73 2e 20  he same inputs. 
36060 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20   If two or more 
36070 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
36080 6f 6e 73 20 61 72 65 20 72 65 67 69 73 74 65 72  ons are register
36090 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d  ed.** to the sam
360a0 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65  e collation name
360b0 20 28 75 73 69 6e 67 20 64 69 66 66 65 72 65 6e   (using differen
360c0 74 20 65 54 65 78 74 52 65 70 20 76 61 6c 75 65  t eTextRep value
360d0 73 29 20 74 68 65 6e 20 61 6c 6c 0a 2a 2a 20 6d  s) then all.** m
360e0 75 73 74 20 67 69 76 65 20 61 6e 20 65 71 75 69  ust give an equi
360f0 76 61 6c 65 6e 74 20 61 6e 73 77 65 72 20 77 68  valent answer wh
36100 65 6e 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  en invoked with 
36110 65 71 75 69 76 61 6c 65 6e 74 20 73 74 72 69 6e  equivalent strin
36120 67 73 2e 0a 2a 2a 20 54 68 65 20 63 6f 6c 6c 61  gs..** The colla
36130 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75  ting function mu
36140 73 74 20 6f 62 65 79 20 74 68 65 20 66 6f 6c 6c  st obey the foll
36150 6f 77 69 6e 67 20 70 72 6f 70 65 72 74 69 65 73  owing properties
36160 20 66 6f 72 20 61 6c 6c 0a 2a 2a 20 73 74 72 69   for all.** stri
36170 6e 67 73 20 41 2c 20 42 2c 20 61 6e 64 20 43 3a  ngs A, B, and C:
36180 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
36190 6c 69 3e 20 49 66 20 41 3d 3d 42 20 74 68 65 6e  li> If A==B then
361a0 20 42 3d 3d 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49   B==A..** <li> I
361b0 66 20 41 3d 3d 42 20 61 6e 64 20 42 3d 3d 43 20  f A==B and B==C 
361c0 74 68 65 6e 20 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c  then A==C..** <l
361d0 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 54 48 45  i> If A&lt;B THE
361e0 4e 20 42 26 67 74 3b 41 2e 0a 2a 2a 20 3c 6c 69  N B&gt;A..** <li
361f0 3e 20 49 66 20 41 26 6c 74 3b 42 20 61 6e 64 20  > If A&lt;B and 
36200 42 26 6c 74 3b 43 20 74 68 65 6e 20 41 26 6c 74  B&lt;C then A&lt
36210 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a  ;C..** </ol>.**.
36220 2a 2a 20 49 66 20 61 20 63 6f 6c 6c 61 74 69 6e  ** If a collatin
36230 67 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73  g function fails
36240 20 61 6e 79 20 6f 66 20 74 68 65 20 61 62 6f 76   any of the abov
36250 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e  e constraints an
36260 64 20 74 68 61 74 0a 2a 2a 20 63 6f 6c 6c 61 74  d that.** collat
36270 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ing function is 
36280 20 72 65 67 69 73 74 65 72 65 64 20 61 6e 64 20   registered and 
36290 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 62  used, then the b
362a0 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74  ehavior of SQLit
362b0 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65  e.** is undefine
362c0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
362d0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
362e0 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b  lation_v2() work
362f0 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63  s like sqlite3_c
36300 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
36310 29 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 61 64  ).** with the ad
36320 64 69 74 69 6f 6e 20 74 68 61 74 20 74 68 65 20  dition that the 
36330 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63  xDestroy callbac
36340 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20  k is invoked on 
36350 70 41 72 67 20 77 68 65 6e 0a 2a 2a 20 74 68 65  pArg when.** the
36360 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
36370 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2e 0a  ion is deleted..
36380 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6e 67 20 66 75  ** ^Collating fu
36390 6e 63 74 69 6f 6e 73 20 61 72 65 20 64 65 6c 65  nctions are dele
363a0 74 65 64 20 77 68 65 6e 20 74 68 65 79 20 61 72  ted when they ar
363b0 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20  e overridden by 
363c0 6c 61 74 65 72 0a 2a 2a 20 63 61 6c 6c 73 20 74  later.** calls t
363d0 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20  o the collation 
363e0 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f  creation functio
363f0 6e 73 20 6f 72 20 77 68 65 6e 20 74 68 65 0a 2a  ns or when the.*
36400 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
36410 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65  ection] is close
36420 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
36430 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _close()]..**.**
36440 20 5e 54 68 65 20 78 44 65 73 74 72 6f 79 20 63   ^The xDestroy c
36450 61 6c 6c 62 61 63 6b 20 69 73 20 3c 75 3e 6e 6f  allback is <u>no
36460 74 3c 2f 75 3e 20 63 61 6c 6c 65 64 20 69 66 20  t</u> called if 
36470 74 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  the .** sqlite3_
36480 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
36490 5f 76 32 28 29 20 66 75 6e 63 74 69 6f 6e 20 66  _v2() function f
364a0 61 69 6c 73 2e 20 20 41 70 70 6c 69 63 61 74 69  ails.  Applicati
364b0 6f 6e 73 20 74 68 61 74 20 69 6e 76 6f 6b 65 0a  ons that invoke.
364c0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ** sqlite3_creat
364d0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
364e0 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c   with a non-NULL
364f0 20 78 44 65 73 74 72 6f 79 20 61 72 67 75 6d 65   xDestroy argume
36500 6e 74 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 63 68  nt should .** ch
36510 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63  eck the return c
36520 6f 64 65 20 61 6e 64 20 64 69 73 70 6f 73 65 20  ode and dispose 
36530 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
36540 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 0a  on data pointer.
36550 2a 2a 20 74 68 65 6d 73 65 6c 76 65 73 20 72 61  ** themselves ra
36560 74 68 65 72 20 74 68 61 6e 20 65 78 70 65 63 74  ther than expect
36570 69 6e 67 20 53 51 4c 69 74 65 20 74 6f 20 64 65  ing SQLite to de
36580 61 6c 20 77 69 74 68 20 69 74 20 66 6f 72 20 74  al with it for t
36590 68 65 6d 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20  hem..** This is 
365a0 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 65  different from e
365b0 76 65 72 79 20 6f 74 68 65 72 20 53 51 4c 69 74  very other SQLit
365c0 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68  e interface.  Th
365d0 65 20 69 6e 63 6f 6e 73 69 73 74 65 6e 63 79 20  e inconsistency 
365e0 0a 2a 2a 20 69 73 20 75 6e 66 6f 72 74 75 6e 61  .** is unfortuna
365f0 74 65 20 62 75 74 20 63 61 6e 6e 6f 74 20 62 65  te but cannot be
36600 20 63 68 61 6e 67 65 64 20 77 69 74 68 6f 75 74   changed without
36610 20 62 72 65 61 6b 69 6e 67 20 62 61 63 6b 77 61   breaking backwa
36620 72 64 73 20 0a 2a 2a 20 63 6f 6d 70 61 74 69 62  rds .** compatib
36630 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  ility..**.** See
36640 20 61 6c 73 6f 3a 20 20 5b 73 71 6c 69 74 65 33   also:  [sqlite3
36650 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
36660 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  d()] and [sqlite
36670 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
36680 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  ed16()]..*/.int 
36690 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
366a0 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69  ollation(.  sqli
366b0 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63  te3*, .  const c
366c0 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69  har *zName, .  i
366d0 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20  nt eTextRep, .  
366e0 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e  void *pArg,.  in
366f0 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69  t(*xCompare)(voi
36700 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
36710 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
36720 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  d*).);.int sqlit
36730 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
36740 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  ion_v2(.  sqlite
36750 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61  3*, .  const cha
36760 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74  r *zName, .  int
36770 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f   eTextRep, .  vo
36780 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28  id *pArg,.  int(
36790 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a  *xCompare)(void*
367a0 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
367b0 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
367c0 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74  ),.  void(*xDest
367d0 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69  roy)(void*).);.i
367e0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
367f0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20  e_collation16(. 
36800 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f   sqlite3*, .  co
36810 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c  nst void *zName,
36820 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
36830 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a   .  void *pArg,.
36840 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29    int(*xCompare)
36850 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
36860 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74   void*,int,const
36870 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a   void*).);../*.*
36880 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c  * CAPI3REF: Coll
36890 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c  ation Needed Cal
368a0 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f  lbacks.**.** ^To
368b0 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f   avoid having to
368c0 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f   register all co
368d0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
368e0 73 20 62 65 66 6f 72 65 20 61 20 64 61 74 61 62  s before a datab
368f0 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73  ase.** can be us
36900 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c  ed, a single cal
36910 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d  lback function m
36920 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65 64  ay be registered
36930 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61   with the.** [da
36940 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
36950 6e 5d 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  n] to be invoked
36960 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64   whenever an und
36970 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  efined collation
36980 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 69 73 20  .** sequence is 
36990 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
369a0 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ^If the function
369b0 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20 75   is registered u
369c0 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
369d0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
369e0 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e  d() API,.** then
369f0 20 69 74 20 69 73 20 70 61 73 73 65 64 20 74 68   it is passed th
36a00 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66  e names of undef
36a10 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73  ined collation s
36a20 65 71 75 65 6e 63 65 73 20 61 73 20 73 74 72 69  equences as stri
36a30 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69  ngs.** encoded i
36a40 6e 20 55 54 46 2d 38 2e 20 5e 49 66 20 73 71 6c  n UTF-8. ^If sql
36a50 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
36a60 65 65 64 65 64 31 36 28 29 20 69 73 20 75 73 65  eeded16() is use
36a70 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20  d,.** the names 
36a80 61 72 65 20 70 61 73 73 65 64 20 61 73 20 55 54  are passed as UT
36a90 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20  F-16 in machine 
36aa0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
36ab0 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f  r..** ^A call to
36ac0 20 65 69 74 68 65 72 20 66 75 6e 63 74 69 6f 6e   either function
36ad0 20 72 65 70 6c 61 63 65 73 20 74 68 65 20 65 78   replaces the ex
36ae0 69 73 74 69 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e  isting collation
36af0 2d 6e 65 65 64 65 64 20 63 61 6c 6c 62 61 63 6b  -needed callback
36b00 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20 74  ..**.** ^(When t
36b10 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  he callback is i
36b20 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73  nvoked, the firs
36b30 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65  t argument passe
36b40 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f  d is a copy.** o
36b50 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  f the second arg
36b60 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
36b70 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
36b80 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  d() or.** sqlite
36b90 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
36ba0 65 64 31 36 28 29 2e 20 20 54 68 65 20 73 65 63  ed16().  The sec
36bb0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
36bc0 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
36bd0 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65  connection.  The
36be0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
36bf0 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
36c00 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45  E_UTF8], [SQLITE
36c10 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72  _UTF16BE],.** or
36c20 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
36c30 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  ], indicating th
36c40 65 20 6d 6f 73 74 20 64 65 73 69 72 61 62 6c 65  e most desirable
36c50 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c   form of the col
36c60 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e  lation.** sequen
36c70 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  ce function requ
36c80 69 72 65 64 2e 20 20 54 68 65 20 66 6f 75 72 74  ired.  The fourt
36c90 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  h parameter is t
36ca0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a  he name of the.*
36cb0 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61  * required colla
36cc0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e 29 5e  tion sequence.)^
36cd0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62  .**.** The callb
36ce0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  ack function sho
36cf0 75 6c 64 20 72 65 67 69 73 74 65 72 20 74 68 65  uld register the
36d00 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69   desired collati
36d10 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  on using.** [sql
36d20 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
36d30 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  ation()], [sqlit
36d40 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
36d50 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20  ion16()], or.** 
36d60 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
36d70 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e  collation_v2()].
36d80 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
36d90 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
36da0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
36db0 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28   void*, .  void(
36dc0 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
36dd0 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63  *,int eTextRep,c
36de0 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69  onst char*).);.i
36df0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  nt sqlite3_colla
36e00 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20  tion_needed16(. 
36e10 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f   sqlite3*, .  vo
36e20 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76  id*,.  void(*)(v
36e30 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e  oid*,sqlite3*,in
36e40 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74  t eTextRep,const
36e50 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 23 69 66 64   void*).);..#ifd
36e60 65 66 20 53 51 4c 49 54 45 5f 48 41 53 5f 43 4f  ef SQLITE_HAS_CO
36e70 44 45 43 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66  DEC./*.** Specif
36e80 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e  y the key for an
36e90 20 65 6e 63 72 79 70 74 65 64 20 64 61 74 61 62   encrypted datab
36ea0 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69  ase.  This routi
36eb0 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  ne should be.** 
36ec0 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74  called right aft
36ed0 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  er sqlite3_open(
36ee0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64  )..**.** The cod
36ef0 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74  e to implement t
36f00 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61  his API is not a
36f10 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20  vailable in the 
36f20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a  public release.*
36f30 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  * of SQLite..*/.
36f40 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28  int sqlite3_key(
36f50 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
36f60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36f70 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f    /* Database to
36f80 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20   be rekeyed */. 
36f90 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65   const void *pKe
36fa0 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20  y, int nKey     
36fb0 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b  /* The key */.);
36fc0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79  .int sqlite3_key
36fd0 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
36fe0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
36ff0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
37000 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20  e to be rekeyed 
37010 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
37020 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20 20 20  *zDbName,       
37030 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
37040 68 65 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20  he database */. 
37050 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65   const void *pKe
37060 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20  y, int nKey     
37070 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b  /* The key */.);
37080 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74  ../*.** Change t
37090 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65  he key on an ope
370a0 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49 66 20  n database.  If 
370b0 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 61  the current data
370c0 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65  base is not.** e
370d0 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73 20 72  ncrypted, this r
370e0 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72  outine will encr
370f0 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77  ypt it.  If pNew
37100 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20  ==0 or nNew==0, 
37110 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
37120 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a  is decrypted..**
37130 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20  .** The code to 
37140 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41  implement this A
37150 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61  PI is not availa
37160 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69  ble in the publi
37170 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20  c release.** of 
37180 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73  SQLite..*/.int s
37190 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20  qlite3_rekey(.  
371a0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
371b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
371c0 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65  * Database to be
371d0 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f   rekeyed */.  co
371e0 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20  nst void *pKey, 
371f0 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20  int nKey     /* 
37200 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29  The new key */.)
37210 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  ;.int sqlite3_re
37220 6b 65 79 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  key_v2(.  sqlite
37230 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
37240 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
37250 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79  base to be rekey
37260 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  ed */.  const ch
37270 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20  ar *zDbName,    
37280 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
37290 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 2a  f the database *
372a0 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
372b0 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20  pKey, int nKey  
372c0 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65     /* The new ke
372d0 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53  y */.);../*.** S
372e0 70 65 63 69 66 79 20 74 68 65 20 61 63 74 69 76  pecify the activ
372f0 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20  ation key for a 
37300 53 45 45 20 64 61 74 61 62 61 73 65 2e 20 20 55  SEE database.  U
37310 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61  nless .** activa
37320 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65  ted, none of the
37330 20 53 45 45 20 72 6f 75 74 69 6e 65 73 20 77 69   SEE routines wi
37340 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64  ll work..*/.void
37350 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74   sqlite3_activat
37360 65 5f 73 65 65 28 0a 20 20 63 6f 6e 73 74 20 63  e_see(.  const c
37370 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65  har *zPassPhrase
37380 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76          /* Activ
37390 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a  ation phrase */.
373a0 29 3b 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64 65  );.#endif..#ifde
373b0 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f  f SQLITE_ENABLE_
373c0 43 45 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63  CEROD./*.** Spec
373d0 69 66 79 20 74 68 65 20 61 63 74 69 76 61 74 69  ify the activati
373e0 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 43 45 52  on key for a CER
373f0 4f 44 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e  OD database.  Un
37400 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74  less .** activat
37410 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20  ed, none of the 
37420 43 45 52 4f 44 20 72 6f 75 74 69 6e 65 73 20 77  CEROD routines w
37430 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69  ill work..*/.voi
37440 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61  d sqlite3_activa
37450 74 65 5f 63 65 72 6f 64 28 0a 20 20 63 6f 6e 73  te_cerod(.  cons
37460 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72  t char *zPassPhr
37470 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63  ase        /* Ac
37480 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20  tivation phrase 
37490 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a  */.);.#endif../*
374a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75  .** CAPI3REF: Su
374b0 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20  spend Execution 
374c0 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65  For A Short Time
374d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
374e0 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74  e3_sleep() funct
374f0 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65 20 63  ion causes the c
37500 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f  urrent thread to
37510 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74 69   suspend executi
37520 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61  on.** for at lea
37530 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d  st a number of m
37540 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63  illiseconds spec
37550 69 66 69 65 64 20 69 6e 20 69 74 73 20 70 61 72  ified in its par
37560 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66  ameter..**.** If
37570 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
37580 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73  ystem does not s
37590 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65 71  upport sleep req
375a0 75 65 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69  uests with.** mi
375b0 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 72  llisecond time r
375c0 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20  esolution, then 
375d0 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 65  the time will be
375e0 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a   rounded up to.*
375f0 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20 73 65  * the nearest se
37600 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65 72  cond. The number
37610 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   of milliseconds
37620 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c   of sleep actual
37630 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20  ly.** requested 
37640 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69  from the operati
37650 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72 65 74  ng system is ret
37660 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51  urned..**.** ^SQ
37670 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20  Lite implements 
37680 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 62  this interface b
37690 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53  y calling the xS
376a0 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  leep().** method
376b0 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20   of the default 
376c0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
376d0 6a 65 63 74 2e 20 20 49 66 20 74 68 65 20 78 53  ject.  If the xS
376e0 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 0a 2a 2a  leep() method.**
376f0 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20   of the default 
37700 56 46 53 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65  VFS is not imple
37710 6d 65 6e 74 65 64 20 63 6f 72 72 65 63 74 6c 79  mented correctly
37720 2c 20 6f 72 20 6e 6f 74 20 69 6d 70 6c 65 6d 65  , or not impleme
37730 6e 74 65 64 20 61 74 0a 2a 2a 20 61 6c 6c 2c 20  nted at.** all, 
37740 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
37750 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6c 65  r of sqlite3_sle
37760 65 70 28 29 20 6d 61 79 20 64 65 76 69 61 74 65  ep() may deviate
37770 20 66 72 6f 6d 20 74 68 65 20 64 65 73 63 72 69   from the descri
37780 70 74 69 6f 6e 0a 2a 2a 20 69 6e 20 74 68 65 20  ption.** in the 
37790 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61  previous paragra
377a0 70 68 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  phs..*/.int sqli
377b0 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a  te3_sleep(int);.
377c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
377d0 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c   Name Of The Fol
377e0 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70  der Holding Temp
377f0 6f 72 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a  orary Files.**.*
37800 2a 20 5e 28 49 66 20 74 68 69 73 20 67 6c 6f 62  * ^(If this glob
37810 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d  al variable is m
37820 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
37830 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69  a string which i
37840 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66  s.** the name of
37850 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61   a folder (a.k.a
37860 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68  . directory), th
37870 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79  en all temporary
37880 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65   files.** create
37890 64 20 62 79 20 53 51 4c 69 74 65 20 77 68 65 6e  d by SQLite when
378a0 20 75 73 69 6e 67 20 61 20 62 75 69 6c 74 2d 69   using a built-i
378b0 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c  n [sqlite3_vfs |
378c0 20 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65   VFS].** will be
378d0 20 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20   placed in that 
378e0 64 69 72 65 63 74 6f 72 79 2e 29 5e 20 20 5e 49  directory.)^  ^I
378f0 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a  f this variable.
37900 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  ** is a NULL poi
37910 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74  nter, then SQLit
37920 65 20 70 65 72 66 6f 72 6d 73 20 61 20 73 65 61  e performs a sea
37930 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f  rch for an appro
37940 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72  priate.** tempor
37950 61 72 79 20 66 69 6c 65 20 64 69 72 65 63 74 6f  ary file directo
37960 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20  ry..**.** It is 
37970 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64  not safe to read
37980 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20   or modify this 
37990 76 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65  variable in more
379a0 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72   than one.** thr
379b0 65 61 64 20 61 74 20 61 20 74 69 6d 65 2e 20 20  ead at a time.  
379c0 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
379d0 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79  o read or modify
379e0 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a   this variable.*
379f0 2a 20 69 66 20 61 20 5b 64 61 74 61 62 61 73 65  * if a [database
37a00 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20   connection] is 
37a10 62 65 69 6e 67 20 75 73 65 64 20 61 74 20 74 68  being used at th
37a20 65 20 73 61 6d 65 20 74 69 6d 65 20 69 6e 20 61  e same time in a
37a30 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 74 68 72   separate.** thr
37a40 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e  ead..** It is in
37a50 74 65 6e 64 65 64 20 74 68 61 74 20 74 68 69 73  tended that this
37a60 20 76 61 72 69 61 62 6c 65 20 62 65 20 73 65 74   variable be set
37a70 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74   once.** as part
37a80 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74   of process init
37a90 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62  ialization and b
37aa0 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65  efore any SQLite
37ab0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f   interface.** ro
37ac0 75 74 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e  utines have been
37ad0 20 63 61 6c 6c 65 64 20 61 6e 64 20 74 68 61 74   called and that
37ae0 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 72   this variable r
37af0 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a  emain unchanged.
37b00 2a 2a 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a  ** thereafter..*
37b10 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74 65 6d 70 5f  *.** ^The [temp_
37b20 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
37b30 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69  pragma] may modi
37b40 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  fy this variable
37b50 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 74   and cause.** it
37b60 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d   to point to mem
37b70 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
37b80 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
37b90 63 5d 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f 72  c].  ^Furthermor
37ba0 65 2c 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f  e,.** the [temp_
37bb0 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
37bc0 70 72 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 61  pragma] always a
37bd0 73 73 75 6d 65 73 20 74 68 61 74 20 61 6e 79 20  ssumes that any 
37be0 73 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74  string.** that t
37bf0 68 69 73 20 76 61 72 69 61 62 6c 65 20 70 6f 69  his variable poi
37c00 6e 74 73 20 74 6f 20 69 73 20 68 65 6c 64 20 69  nts to is held i
37c10 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  n memory obtaine
37c20 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69  d from .** [sqli
37c30 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20  te3_malloc] and 
37c40 74 68 65 20 70 72 61 67 6d 61 20 6d 61 79 20 61  the pragma may a
37c50 74 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74  ttempt to free t
37c60 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73  hat memory.** us
37c70 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  ing [sqlite3_fre
37c80 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66  e]..** Hence, if
37c90 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69   this variable i
37ca0 73 20 6d 6f 64 69 66 69 65 64 20 64 69 72 65 63  s modified direc
37cb0 74 6c 79 2c 20 65 69 74 68 65 72 20 69 74 20 73  tly, either it s
37cc0 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65  hould be.** made
37cd0 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f   NULL or made to
37ce0 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79   point to memory
37cf0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
37d00 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a  sqlite3_malloc].
37d10 2a 2a 20 6f 72 20 65 6c 73 65 20 74 68 65 20 75  ** or else the u
37d20 73 65 20 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f  se of the [temp_
37d30 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
37d40 70 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62  pragma] should b
37d50 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2a 0a 2a 2a  e avoided..**.**
37d60 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64   <b>Note to Wind
37d70 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72  ows Runtime user
37d80 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70  s:</b>  The temp
37d90 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72 79 20  orary directory 
37da0 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70  must be set.** p
37db0 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20  rior to calling 
37dc0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5d 20 6f  [sqlite3_open] o
37dd0 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  r [sqlite3_open_
37de0 76 32 5d 2e 20 20 4f 74 68 65 72 77 69 73 65 2c  v2].  Otherwise,
37df0 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74   various.** feat
37e00 75 72 65 73 20 74 68 61 74 20 72 65 71 75 69 72  ures that requir
37e10 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d  e the use of tem
37e20 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79  porary files may
37e30 20 66 61 69 6c 2e 20 20 48 65 72 65 20 69 73 20   fail.  Here is 
37e40 61 6e 0a 2a 2a 20 65 78 61 6d 70 6c 65 20 6f 66  an.** example of
37e50 20 68 6f 77 20 74 6f 20 64 6f 20 74 68 69 73 20   how to do this 
37e60 75 73 69 6e 67 20 43 2b 2b 20 77 69 74 68 20 74  using C++ with t
37e70 68 65 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69  he Windows Runti
37e80 6d 65 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  me:.**.** <block
37e90 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 4c  quote><pre>.** L
37ea0 50 43 57 53 54 52 20 7a 50 61 74 68 20 3d 20 57  PCWSTR zPath = W
37eb0 69 6e 64 6f 77 73 3a 3a 53 74 6f 72 61 67 65 3a  indows::Storage:
37ec0 3a 41 70 70 6c 69 63 61 74 69 6f 6e 44 61 74 61  :ApplicationData
37ed0 3a 3a 43 75 72 72 65 6e 74 2d 3e 0a 2a 2a 20 26  ::Current->.** &
37ee0 6e 62 73 70 3b 20 20 20 20 20 54 65 6d 70 6f 72  nbsp;     Tempor
37ef0 61 72 79 46 6f 6c 64 65 72 2d 3e 50 61 74 68 2d  aryFolder->Path-
37f00 3e 44 61 74 61 28 29 3b 0a 2a 2a 20 63 68 61 72  >Data();.** char
37f10 20 7a 50 61 74 68 42 75 66 26 23 39 31 3b 4d 41   zPathBuf&#91;MA
37f20 58 5f 50 41 54 48 20 2b 20 31 26 23 39 33 3b 3b  X_PATH + 1&#93;;
37f30 0a 2a 2a 20 6d 65 6d 73 65 74 28 7a 50 61 74 68  .** memset(zPath
37f40 42 75 66 2c 20 30 2c 20 73 69 7a 65 6f 66 28 7a  Buf, 0, sizeof(z
37f50 50 61 74 68 42 75 66 29 29 3b 0a 2a 2a 20 57 69  PathBuf));.** Wi
37f60 64 65 43 68 61 72 54 6f 4d 75 6c 74 69 42 79 74  deCharToMultiByt
37f70 65 28 43 50 5f 55 54 46 38 2c 20 30 2c 20 7a 50  e(CP_UTF8, 0, zP
37f80 61 74 68 2c 20 2d 31 2c 20 7a 50 61 74 68 42 75  ath, -1, zPathBu
37f90 66 2c 20 73 69 7a 65 6f 66 28 7a 50 61 74 68 42  f, sizeof(zPathB
37fa0 75 66 29 2c 0a 2a 2a 20 26 6e 62 73 70 3b 20 20  uf),.** &nbsp;  
37fb0 20 20 20 4e 55 4c 4c 2c 20 4e 55 4c 4c 29 3b 0a     NULL, NULL);.
37fc0 2a 2a 20 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f  ** sqlite3_temp_
37fd0 64 69 72 65 63 74 6f 72 79 20 3d 20 73 71 6c 69  directory = sqli
37fe0 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 25 73 22  te3_mprintf("%s"
37ff0 2c 20 7a 50 61 74 68 42 75 66 29 3b 0a 2a 2a 20  , zPathBuf);.** 
38000 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
38010 74 65 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58  te>.*/.SQLITE_EX
38020 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69 74  TERN char *sqlit
38030 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72  e3_temp_director
38040 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  y;../*.** CAPI3R
38050 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20  EF: Name Of The 
38060 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 44  Folder Holding D
38070 61 74 61 62 61 73 65 20 46 69 6c 65 73 0a 2a 2a  atabase Files.**
38080 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73 20 67 6c  .** ^(If this gl
38090 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73  obal variable is
380a0 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
380b0 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68  o a string which
380c0 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20   is.** the name 
380d0 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b  of a folder (a.k
380e0 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20  .a. directory), 
380f0 74 68 65 6e 20 61 6c 6c 20 64 61 74 61 62 61 73  then all databas
38100 65 20 66 69 6c 65 73 0a 2a 2a 20 73 70 65 63 69  e files.** speci
38110 66 69 65 64 20 77 69 74 68 20 61 20 72 65 6c 61  fied with a rela
38120 74 69 76 65 20 70 61 74 68 6e 61 6d 65 20 61 6e  tive pathname an
38130 64 20 63 72 65 61 74 65 64 20 6f 72 20 61 63 63  d created or acc
38140 65 73 73 65 64 20 62 79 0a 2a 2a 20 53 51 4c 69  essed by.** SQLi
38150 74 65 20 77 68 65 6e 20 75 73 69 6e 67 20 61 20  te when using a 
38160 62 75 69 6c 74 2d 69 6e 20 77 69 6e 64 6f 77 73  built-in windows
38170 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20   [sqlite3_vfs | 
38180 56 46 53 5d 20 77 69 6c 6c 20 62 65 20 61 73 73  VFS] will be ass
38190 75 6d 65 64 0a 2a 2a 20 74 6f 20 62 65 20 72 65  umed.** to be re
381a0 6c 61 74 69 76 65 20 74 6f 20 74 68 61 74 20 64  lative to that d
381b0 69 72 65 63 74 6f 72 79 2e 29 5e 20 5e 49 66 20  irectory.)^ ^If 
381c0 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 73  this variable is
381d0 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
381e0 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  er, then SQLite 
381f0 61 73 73 75 6d 65 73 20 74 68 61 74 20 61 6c 6c  assumes that all
38200 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20   database files 
38210 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 77 69 74  specified.** wit
38220 68 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74  h a relative pat
38230 68 6e 61 6d 65 20 61 72 65 20 72 65 6c 61 74 69  hname are relati
38240 76 65 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e  ve to the curren
38250 74 20 64 69 72 65 63 74 6f 72 79 0a 2a 2a 20 66  t directory.** f
38260 6f 72 20 74 68 65 20 70 72 6f 63 65 73 73 2e 20  or the process. 
38270 20 4f 6e 6c 79 20 74 68 65 20 77 69 6e 64 6f 77   Only the window
38280 73 20 56 46 53 20 6d 61 6b 65 73 20 75 73 65 20  s VFS makes use 
38290 6f 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 0a 2a  of this global.*
382a0 2a 20 76 61 72 69 61 62 6c 65 3b 20 69 74 20 69  * variable; it i
382b0 73 20 69 67 6e 6f 72 65 64 20 62 79 20 74 68 65  s ignored by the
382c0 20 75 6e 69 78 20 56 46 53 2e 0a 2a 2a 0a 2a 2a   unix VFS..**.**
382d0 20 43 68 61 6e 67 69 6e 67 20 74 68 65 20 76 61   Changing the va
382e0 6c 75 65 20 6f 66 20 74 68 69 73 20 76 61 72 69  lue of this vari
382f0 61 62 6c 65 20 77 68 69 6c 65 20 61 20 64 61 74  able while a dat
38300 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
38310 20 69 73 0a 2a 2a 20 6f 70 65 6e 20 63 61 6e 20   is.** open can 
38320 72 65 73 75 6c 74 20 69 6e 20 61 20 63 6f 72 72  result in a corr
38330 75 70 74 20 64 61 74 61 62 61 73 65 2e 0a 2a 2a  upt database..**
38340 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61  .** It is not sa
38350 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f  fe to read or mo
38360 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62  dify this variab
38370 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e 20  le in more than 
38380 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20 61 74  one.** thread at
38390 20 61 20 74 69 6d 65 2e 20 20 49 74 20 69 73 20   a time.  It is 
383a0 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64  not safe to read
383b0 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20   or modify this 
383c0 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20 61  variable.** if a
383d0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
383e0 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20  ction] is being 
383f0 75 73 65 64 20 61 74 20 74 68 65 20 73 61 6d 65  used at the same
38400 20 74 69 6d 65 20 69 6e 20 61 20 73 65 70 61 72   time in a separ
38410 61 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a 2a  ate.** thread..*
38420 2a 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64  * It is intended
38430 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61   that this varia
38440 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a  ble be set once.
38450 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70 72  ** as part of pr
38460 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61  ocess initializa
38470 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20  tion and before 
38480 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72  any SQLite inter
38490 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  face.** routines
384a0 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65   have been calle
384b0 64 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20  d and that this 
384c0 76 61 72 69 61 62 6c 65 20 72 65 6d 61 69 6e 20  variable remain 
384d0 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68 65  unchanged.** the
384e0 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  reafter..**.** ^
384f0 54 68 65 20 5b 64 61 74 61 5f 73 74 6f 72 65 5f  The [data_store_
38500 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
38510 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20 74 68 69  ] may modify thi
38520 73 20 76 61 72 69 61 62 6c 65 20 61 6e 64 20 63  s variable and c
38530 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20 70 6f  ause.** it to po
38540 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  int to memory ob
38550 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
38560 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 5e  ite3_malloc].  ^
38570 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20  Furthermore,.** 
38580 74 68 65 20 5b 64 61 74 61 5f 73 74 6f 72 65 5f  the [data_store_
38590 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
385a0 5d 20 61 6c 77 61 79 73 20 61 73 73 75 6d 65 73  ] always assumes
385b0 20 74 68 61 74 20 61 6e 79 20 73 74 72 69 6e 67   that any string
385c0 0a 2a 2a 20 74 68 61 74 20 74 68 69 73 20 76 61  .** that this va
385d0 72 69 61 62 6c 65 20 70 6f 69 6e 74 73 20 74 6f  riable points to
385e0 20 69 73 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f   is held in memo
385f0 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
38600 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61   .** [sqlite3_ma
38610 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20 70 72  lloc] and the pr
38620 61 67 6d 61 20 6d 61 79 20 61 74 74 65 6d 70 74  agma may attempt
38630 20 74 6f 20 66 72 65 65 20 74 68 61 74 20 6d 65   to free that me
38640 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20 5b 73  mory.** using [s
38650 71 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a  qlite3_free]..**
38660 20 48 65 6e 63 65 2c 20 69 66 20 74 68 69 73 20   Hence, if this 
38670 76 61 72 69 61 62 6c 65 20 69 73 20 6d 6f 64 69  variable is modi
38680 66 69 65 64 20 64 69 72 65 63 74 6c 79 2c 20 65  fied directly, e
38690 69 74 68 65 72 20 69 74 20 73 68 6f 75 6c 64 20  ither it should 
386a0 62 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c 20  be.** made NULL 
386b0 6f 72 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  or made to point
386c0 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69   to memory obtai
386d0 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
386e0 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20  3_malloc].** or 
386f0 65 6c 73 65 20 74 68 65 20 75 73 65 20 6f 66 20  else the use of 
38700 74 68 65 20 5b 64 61 74 61 5f 73 74 6f 72 65 5f  the [data_store_
38710 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
38720 5d 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f 69  ] should be avoi
38730 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45  ded..*/.SQLITE_E
38740 58 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69  XTERN char *sqli
38750 74 65 33 5f 64 61 74 61 5f 64 69 72 65 63 74 6f  te3_data_directo
38760 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ry;../*.** CAPI3
38770 52 45 46 3a 20 54 65 73 74 20 46 6f 72 20 41 75  REF: Test For Au
38780 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 0a 2a  to-Commit Mode.*
38790 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75 74  * KEYWORDS: {aut
387a0 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a  ocommit mode}.**
387b0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
387c0 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28  _get_autocommit(
387d0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
387e0 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a  rns non-zero or.
387f0 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68 65 20 67  ** zero if the g
38800 69 76 65 6e 20 64 61 74 61 62 61 73 65 20 63 6f  iven database co
38810 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72 20 69  nnection is or i
38820 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d  s not in autocom
38830 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73  mit mode,.** res
38840 70 65 63 74 69 76 65 6c 79 2e 20 20 5e 41 75 74  pectively.  ^Aut
38850 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20  ocommit mode is 
38860 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a