/ Hex Artifact Content
Login
SQLite training in Houston TX on 2019-11-05 (details)
Part of the 2019 Tcl Conference

Artifact 29199f78f9eba5f935c62dc79a3eb64f26b5e433:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
07d0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
07e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
07f0: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0800: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0810: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0820: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0830: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0840: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0850: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0860: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
0870: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
0880: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
0890: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08a0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08b0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08c0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
08d0: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
08e0: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
08f0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0900: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0910: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0920: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0930: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0940: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0950: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0960: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
0970: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
0980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0990: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09b0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09c0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
09d0: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
09e0: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
09f0: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a00: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a20: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a30: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a40: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a50: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a60: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0a70: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0a80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0a90: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0aa0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ab0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0ac0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0ad0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0ae0: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0af0: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b00: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b10: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b20: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b30: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b40: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b50: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b60: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0b70: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0b80: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0b90: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0ba0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0bb0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bc0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0bd0: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0be0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0bf0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c00: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c20: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c30: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c40: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c50: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c60: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0c70: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0c80: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0c90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0ca0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0cb0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cc0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0cd0: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0ce0: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0cf0: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d00: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d10: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d20: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d30: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d40: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d50: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d60: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0d70: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0d80: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0d90: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0da0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0db0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0dc0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0dd0: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0de0: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0df0: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e00: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e10: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e20: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e30: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e40: 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a  ro evaluates to.
0e50: 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  ** a string whic
0e60: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70  h identifies a p
0e70: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d  articular check-
0e80: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  in of SQLite.** 
0e90: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69  within its confi
0ea0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
0eb0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68  ent system.  ^Th
0ec0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
0ed0: 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ID.** string con
0ee0: 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61  tains the date a
0ef0: 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63  nd time of the c
0f00: 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e  heck-in (UTC) an
0f10: 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73  d an SHA1.** has
0f20: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
0f30: 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a  source tree..**.
0f40: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
0f50: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
0f60: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
0f70: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
0f80: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  er()], [sqlite3_
0f90: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20  sourceid()],.** 
0fa0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
0fb0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
0fc0: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
0fd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
0fe0: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d  ERSION        "-
0ff0: 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65  -VERS--".#define
1000: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
1010: 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e  NUMBER --VERSION
1020: 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e  -NUMBER--.#defin
1030: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
1040: 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43  ID      "--SOURC
1050: 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43  E-ID--"../*.** C
1060: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1070: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
1080: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59  n Numbers.** KEY
1090: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
10a0: 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f  ersion, sqlite3_
10b0: 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54  sourceid.**.** T
10c0: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
10d0: 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65  provide the same
10e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20   information as 
10f0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  the [SQLITE_VERS
1100: 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  ION],.** [SQLITE
1110: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d  _VERSION_NUMBER]
1120: 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f  , and [SQLITE_SO
1130: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72  URCE_ID] C prepr
1140: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a  ocessor macros.*
1150: 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69  * but are associ
1160: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69  ated with the li
1170: 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66  brary instead of
1180: 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65   the header file
1190: 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a  .  ^(Cautious.**
11a0: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
11b0: 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72  ht include asser
11c0: 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69  t() statements i
11d0: 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74  n their applicat
11e0: 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79  ion to.** verify
11f0: 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74   that values ret
1200: 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69  urned by these i
1210: 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20  nterfaces match 
1220: 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a  the macros in.**
1230: 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64   the header, and
1240: 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61   thus insure tha
1250: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
1260: 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  n is.** compiled
1270: 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c   with matching l
1280: 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65  ibrary and heade
1290: 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c  r files..**.** <
12a0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
12b0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69  .** assert( sqli
12c0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
12d0: 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f  umber()==SQLITE_
12e0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29  VERSION_NUMBER )
12f0: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72  ;.** assert( str
1300: 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72  cmp(sqlite3_sour
1310: 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f  ceid(),SQLITE_SO
1320: 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a  URCE_ID)==0 );.*
1330: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70  * assert( strcmp
1340: 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  (sqlite3_libvers
1350: 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52  ion(),SQLITE_VER
1360: 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c  SION)==0 );.** <
1370: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1380: 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1390: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
13a0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
13b0: 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74  t contains the t
13c0: 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56  ext of [SQLITE_V
13d0: 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f  ERSION].** macro
13e0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
13f0: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e  libversion() fun
1400: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20  ction returns a 
1410: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
1420: 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  * to the sqlite3
1430: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
1440: 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65  g constant.  The
1450: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1460: 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f  ion().** functio
1470: 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f  n is provided fo
1480: 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69  r use in DLLs si
1490: 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73  nce DLL users us
14a0: 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76  ually do not hav
14b0: 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65  e.** direct acce
14c0: 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e  ss to string con
14d0: 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68  stants within th
14e0: 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20  e DLL.  ^The.** 
14f0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1500: 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63  on_number() func
1510: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20  tion returns an 
1520: 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f  integer equal to
1530: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
1540: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54  ION_NUMBER].  ^T
1550: 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  he sqlite3_sourc
1560: 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  eid() function r
1570: 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69  eturns .** a poi
1580: 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67  nter to a string
1590: 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20   constant whose 
15a0: 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d  value is the sam
15b0: 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51  e as the .** [SQ
15c0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20  LITE_SOURCE_ID] 
15d0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
15e0: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  acro..**.** See 
15f0: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65  also: [sqlite_ve
1600: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
1610: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
1620: 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54  ]..*/.SQLITE_EXT
1630: 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73  ERN const char s
1640: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
1650: 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
1660: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1670: 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68  (void);.const ch
1680: 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72  ar *sqlite3_sour
1690: 63 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20  ceid(void);.int 
16a0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
16b0: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b  on_number(void);
16c0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16d0: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61  : Run-Time Libra
16e0: 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f  ry Compilation O
16f0: 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69  ptions Diagnosti
1700: 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  cs.**.** ^The sq
1710: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1720: 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74  ion_used() funct
1730: 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72  ion returns 0 or
1740: 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e   1 .** indicatin
1750: 67 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70  g whether the sp
1760: 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77  ecified option w
1770: 61 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a  as defined at .*
1780: 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  * compile time. 
1790: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72   ^The SQLITE_ pr
17a0: 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74  efix may be omit
17b0: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a  ted from the .**
17c0: 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73   option name pas
17d0: 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  sed to sqlite3_c
17e0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
17f0: 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  d().  .**.** ^Th
1800: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  e sqlite3_compil
1810: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75  eoption_get() fu
1820: 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74  nction allows it
1830: 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20  erating.** over 
1840: 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69  the list of opti
1850: 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65  ons that were de
1860: 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  fined at compile
1870: 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75   time by.** retu
1880: 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63  rning the N-th c
1890: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69  ompile time opti
18a0: 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20  on string.  ^If 
18b0: 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
18c0: 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  e,.** sqlite3_co
18d0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
18e0: 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
18f0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
1900: 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66  SQLITE_ .** pref
1910: 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  ix is omitted fr
1920: 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72  om any strings r
1930: 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73  eturned by .** s
1940: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1950: 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a  tion_get()..**.*
1960: 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74  * ^Support for t
1970: 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75  he diagnostic fu
1980: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f  nctions sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
19a0: 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ed().** and sqli
19b0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19c0: 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f  n_get() may be o
19d0: 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66  mitted by specif
19e0: 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51  ying the .** [SQ
19f0: 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c  LITE_OMIT_COMPIL
1a00: 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f  EOPTION_DIAGS] o
1a10: 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65  ption at compile
1a20: 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   time..**.** See
1a30: 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74   also: SQL funct
1a40: 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d  ions [sqlite_com
1a50: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1a60: 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
1a70: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
1a80: 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b  get()] and the [
1a90: 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20  compile_options 
1aa0: 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e  pragma]..*/.#ifn
1ab0: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
1ac0: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49  COMPILEOPTION_DI
1ad0: 41 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  AGS.int sqlite3_
1ae0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
1af0: 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  ed(const char *z
1b00: 4f 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20  OptName);.const 
1b10: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
1b20: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1b30: 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a  int N);.#endif..
1b40: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b50: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
1b60: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68  he Library Is Th
1b70: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e  readsafe.**.** ^
1b80: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65  The sqlite3_thre
1b90: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
1ba0: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69  n returns zero i
1bb0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
1bc0: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70   SQLite was comp
1bd0: 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69  iled with mutexi
1be0: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20  ng code omitted 
1bf0: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53  due to the.** [S
1c00: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1c10: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
1c20: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20  ption being set 
1c30: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  to 0..**.** SQLi
1c40: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c  te can be compil
1c50: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f  ed with or witho
1c60: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65  ut mutexes.  Whe
1c70: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  n.** the [SQLITE
1c80: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70  _THREADSAFE] C p
1c90: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
1ca0: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74  o is 1 or 2, mut
1cb0: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
1cc0: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69  led and SQLite i
1cd0: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57  s threadsafe.  W
1ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  hen the.** [SQLI
1cf0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
1d00: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74  acro is 0, .** t
1d10: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f  he mutexes are o
1d20: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74  mitted.  Without
1d30: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74   the mutexes, it
1d40: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20   is not safe.** 
1d50: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f  to use SQLite co
1d60: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20  ncurrently from 
1d70: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68  more than one th
1d80: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62  read..**.** Enab
1d90: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63  ling mutexes inc
1da0: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65  urs a measurable
1db0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e   performance pen
1dc0: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73  alty..** So if s
1dd0: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73  peed is of utmos
1de0: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74  t importance, it
1df0: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20   makes sense to 
1e00: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d  disable.** the m
1e10: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72  utexes.  But for
1e20: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c   maximum safety,
1e30: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20   mutexes should 
1e40: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e  be enabled..** ^
1e50: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  The default beha
1e60: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65  vior is for mute
1e70: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65  xes to be enable
1e80: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  d..**.** This in
1e90: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
1ea0: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63  sed by an applic
1eb0: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75  ation to make su
1ec0: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76  re that the.** v
1ed0: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
1ee0: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b   that it is link
1ef0: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20  ing against was 
1f00: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
1f10: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74   the desired set
1f20: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c  ting of the [SQL
1f30: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
1f40: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  macro..**.** Thi
1f50: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79  s interface only
1f60: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20   reports on the 
1f70: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74  compile-time mut
1f80: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66  ex setting.** of
1f90: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
1fa0: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20  EADSAFE] flag.  
1fb0: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
1fc0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51  piled with.** SQ
1fd0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
1fe0: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74  1 or =2 then mut
1ff0: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
2000: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
2010: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
2020: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
2030: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
2040: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
2050: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
2060: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
2070: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
2080: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
2090: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
20a0: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
20b0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
20c0: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e  ].  ^(The return
20d0: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a   value of the.**
20e0: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
20f0: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73  afe() function s
2100: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f  hows only the co
2110: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69  mpile-time setti
2120: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20  ng of.** thread 
2130: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20  safety, not any 
2140: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73  run-time changes
2150: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67   to that setting
2160: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69   made by.** sqli
2170: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e  te3_config(). In
2180: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2190: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
21a0: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65  rom sqlite3_thre
21b0: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75  adsafe().** is u
21c0: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c  nchanged by call
21d0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  s to sqlite3_con
21e0: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  fig().)^.**.** S
21f0: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
2200: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
2210: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
2220: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
2230: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2240: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64  _threadsafe(void
2250: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2260: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
2270: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a  nection Handle.*
2280: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74  * KEYWORDS: {dat
2290: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22a0: 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  } {database conn
22b0: 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45  ections}.**.** E
22c0: 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20  ach open SQLite 
22d0: 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72  database is repr
22e0: 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69  esented by a poi
22f0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
2300: 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70  nce of.** the op
2310: 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e  aque structure n
2320: 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20  amed "sqlite3". 
2330: 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f   It is useful to
2340: 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c   think of an sql
2350: 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ite3.** pointer 
2360: 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54  as an object.  T
2370: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
2380: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
2390: 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  en16()], and.** 
23a0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
23b0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61  ()] interfaces a
23c0: 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74  re its construct
23d0: 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ors, and [sqlite
23e0: 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e  3_close()].** an
23f0: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
2400: 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73 20 64  _v2()] are its d
2410: 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65  estructors.  The
2420: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
2430: 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  r.** interfaces 
2440: 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c  (such as.** [sql
2450: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2460: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
2470: 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c  ate_function()],
2480: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2490: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
24a0: 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72   to name but thr
24b0: 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74  ee) that are met
24c0: 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71  hods on an.** sq
24d0: 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f  lite3 object..*/
24e0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
24f0: 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b  sqlite3 sqlite3;
2500: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2510: 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72  : 64-Bit Integer
2520: 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Types.** KEYWOR
2530: 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  DS: sqlite_int64
2540: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a   sqlite_uint64.*
2550: 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
2560: 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70  re is no cross-p
2570: 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73  latform way to s
2580: 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e  pecify 64-bit in
2590: 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53  teger types.** S
25a0: 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74  QLite includes t
25b0: 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62  ypedefs for 64-b
25c0: 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e  it signed and un
25d0: 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e  signed integers.
25e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
25f0: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  e3_int64 and sql
2600: 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20  ite3_uint64 are 
2610: 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 79  the preferred ty
2620: 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a  pe definitions..
2630: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e  ** The sqlite_in
2640: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2650: 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 20  int64 types are 
2660: 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61  supported for ba
2670: 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61  ckwards.** compa
2680: 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a  tibility only..*
2690: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
26a0: 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  3_int64 and sqli
26b0: 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63  te_int64 types c
26c0: 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72  an store integer
26d0: 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65   values.** betwe
26e0: 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 35  en -922337203685
26f0: 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32  4775808 and +922
2700: 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30 37  3372036854775807
2710: 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68   inclusive.  ^Th
2720: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e  e.** sqlite3_uin
2730: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2740: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
2750: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
2760: 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e  lues .** between
2770: 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34   0 and +18446744
2780: 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 63  073709551615 inc
2790: 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65  lusive..*/.#ifde
27a0: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
27b0: 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51  YPE.  typedef SQ
27c0: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
27d0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20  sqlite_int64;.  
27e0: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64  typedef unsigned
27f0: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
2800: 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  PE sqlite_uint64
2810: 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28  ;.#elif defined(
2820: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66  _MSC_VER) || def
2830: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
2840: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69  _).  typedef __i
2850: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36  nt64 sqlite_int6
2860: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2870: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71  igned __int64 sq
2880: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
2890: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e  se.  typedef lon
28a0: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
28b0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
28c0: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67  ef unsigned long
28d0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
28e0: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a  _uint64;.#endif.
28f0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69  typedef sqlite_i
2900: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74  nt64 sqlite3_int
2910: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69  64;.typedef sqli
2920: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  te_uint64 sqlite
2930: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a  3_uint64;../*.**
2940: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f   If compiling fo
2950: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68  r a processor th
2960: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e  at lacks floatin
2970: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c  g point support,
2980: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69  .** substitute i
2990: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74  nteger for float
29a0: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69  ing-point..*/.#i
29b0: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
29c0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
29d0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
29e0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
29f0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2a00: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
2a10: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2a20: 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ion.**.** ^The s
2a30: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61  qlite3_close() a
2a40: 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nd sqlite3_close
2a50: 5f 76 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61  _v2() routines a
2a60: 72 65 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a  re destructors.*
2a70: 2a 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  * for the [sqlit
2a80: 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e  e3] object..** ^
2a90: 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
2aa0: 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c  _close() and sql
2ab0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
2ac0: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
2ad0: 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69   if.** the [sqli
2ae0: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73  te3] object is s
2af0: 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74  uccessfully dest
2b00: 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73  royed and all as
2b10: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f  sociated.** reso
2b20: 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f  urces are deallo
2b30: 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  cated..**.** ^If
2b40: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2b50: 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f  nnection is asso
2b60: 63 69 61 74 65 64 20 77 69 74 68 20 75 6e 66 69  ciated with unfi
2b70: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64  nalized prepared
2b80: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  .** statements o
2b90: 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c  r unfinished sql
2ba0: 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65  ite3_backup obje
2bb0: 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33  cts then sqlite3
2bc0: 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c  _close().** will
2bd0: 20 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 62   leave the datab
2be0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
2bf0: 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  pen and return [
2c00: 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a  SQLITE_BUSY]..**
2c10: 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f   ^If sqlite3_clo
2c20: 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65  se_v2() is calle
2c30: 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a  d with unfinaliz
2c40: 65 64 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ed prepared stat
2c50: 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 20 75 6e  ements.** and un
2c60: 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33  finished sqlite3
2c70: 5f 62 61 63 6b 75 70 73 2c 20 74 68 65 6e 20 74  _backups, then t
2c80: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2c90: 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a  ection becomes.*
2ca0: 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a  * an unusable "z
2cb0: 6f 6d 62 69 65 22 20 77 68 69 63 68 20 77 69 6c  ombie" which wil
2cc0: 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  l automatically 
2cd0: 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 77  be deallocated w
2ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20  hen the.** last 
2cf0: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d00: 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 20  nt is finalized 
2d10: 6f 72 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69  or the last sqli
2d20: 74 65 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a  te3_backup is.**
2d30: 20 66 69 6e 69 73 68 65 64 2e 20 20 54 68 65 20   finished.  The 
2d40: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
2d50: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
2d60: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
2d70: 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61   with.** host la
2d80: 6e 67 75 61 67 65 73 20 74 68 61 74 20 61 72 65  nguages that are
2d90: 20 67 61 72 62 61 67 65 20 63 6f 6c 6c 65 63 74   garbage collect
2da0: 65 64 2c 20 61 6e 64 20 77 68 65 72 65 20 74 68  ed, and where th
2db0: 65 20 6f 72 64 65 72 20 69 6e 20 77 68 69 63 68  e order in which
2dc0: 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 73 20  .** destructors 
2dd0: 61 72 65 20 63 61 6c 6c 65 64 20 69 73 20 61 72  are called is ar
2de0: 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41  bitrary..**.** A
2df0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
2e00: 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ld [sqlite3_fina
2e10: 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d  lize | finalize]
2e20: 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73   all [prepared s
2e30: 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b  tatements],.** [
2e40: 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
2e50: 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20  se | close] all 
2e60: 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20  [BLOB handles], 
2e70: 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  and .** [sqlite3
2e80: 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c  _backup_finish |
2e90: 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71   finish] all [sq
2ea0: 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62  lite3_backup] ob
2eb0: 6a 65 63 74 73 20 61 73 73 6f 63 69 61 74 65 64  jects associated
2ec0: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73 71  .** with the [sq
2ed0: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72  lite3] object pr
2ee0: 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e  ior to attemptin
2ef0: 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f  g to close the o
2f00: 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73  bject.  ^If.** s
2f10: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
2f20: 29 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61  ) is called on a
2f30: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2f40: 63 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c  ction] that stil
2f50: 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e  l has.** outstan
2f60: 64 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73  ding [prepared s
2f70: 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f  tatements], [BLO
2f80: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f  B handles], and/
2f90: 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  or.** [sqlite3_b
2fa0: 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 74  ackup] objects t
2fb0: 68 65 6e 20 69 74 20 72 65 74 75 72 6e 73 20 53  hen it returns S
2fc0: 51 4c 49 54 45 5f 4f 4b 20 62 75 74 20 74 68 65  QLITE_OK but the
2fd0: 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a   deallocation.**
2fe0: 20 6f 66 20 72 65 73 6f 75 72 63 65 73 20 69 73   of resources is
2ff0: 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20   deferred until 
3000: 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74  all [prepared st
3010: 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42  atements], [BLOB
3020: 20 68 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e   handles],.** an
3030: 64 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  d [sqlite3_backu
3040: 70 5d 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61  p] objects are a
3050: 6c 73 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a  lso destroyed..*
3060: 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c  *.** ^If an [sql
3070: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20  ite3] object is 
3080: 64 65 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20  destroyed while 
3090: 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
30a0: 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72   open,.** the tr
30b0: 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74  ansaction is aut
30c0: 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65  omatically rolle
30d0: 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68  d back..**.** Th
30e0: 65 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e C parameter to
30f0: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
3100: 43 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  C)] and [sqlite3
3110: 5f 63 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a  _close_v2(C)].**
3120: 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
3130: 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
3140: 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33  r or an [sqlite3
3150: 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72  ] object pointer
3160: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
3170: 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  m [sqlite3_open(
3180: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
3190: 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  n16()], or.** [s
31a0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
31b0: 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69  ], and not previ
31c0: 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a  ously closed..**
31d0: 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65   ^Calling sqlite
31e0: 33 5f 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c  3_close() or sql
31f0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
3200: 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
3210: 74 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ter.** argument 
3220: 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
3230: 2d 6f 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  -op..*/.int sqli
3240: 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65  te3_close(sqlite
3250: 33 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  3*);.int sqlite3
3260: 5f 63 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65  _close_v2(sqlite
3270: 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20  3*);../*.** The 
3280: 74 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62  type for a callb
3290: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ack function..**
32a0: 20 54 68 69 73 20 69 73 20 6c 65 67 61 63 79 20   This is legacy 
32b0: 61 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e 20  and deprecated. 
32c0: 20 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20   It is included 
32d0: 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a  for historical.*
32e0: 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  * compatibility 
32f0: 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d  and is not docum
3300: 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65  ented..*/.typede
3310: 66 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f  f int (*sqlite3_
3320: 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c  callback)(void*,
3330: 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72  int,char**, char
3340: 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  **);../*.** CAPI
3350: 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51  3REF: One-Step Q
3360: 75 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49  uery Execution I
3370: 6e 74 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54  nterface.**.** T
3380: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3390: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 61  ) interface is a
33a0: 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61   convenience wra
33b0: 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b  pper around.** [
33c0: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
33d0: 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v2()], [sqlite3_
33e0: 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71  step()], and [sq
33f0: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
3400: 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77  ],.** that allow
3410: 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  s an application
3420: 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65   to run multiple
3430: 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53   statements of S
3440: 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61  QL.** without ha
3450: 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f  ving to use a lo
3460: 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a  t of C code. .**
3470: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
3480: 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63  _exec() interfac
3490: 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d  e runs zero or m
34a0: 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  ore UTF-8 encode
34b0: 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d  d,.** semicolon-
34c0: 73 65 70 61 72 61 74 65 20 53 51 4c 20 73 74 61  separate SQL sta
34d0: 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69  tements passed i
34e0: 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75  nto its 2nd argu
34f0: 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20  ment,.** in the 
3500: 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b  context of the [
3510: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
3520: 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61  ion] passed in a
3530: 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67  s its 1st.** arg
3540: 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20  ument.  ^If the 
3550: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
3560: 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61 72 67  n of the 3rd arg
3570: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69  ument to.** sqli
3580: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f  te3_exec() is no
3590: 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20  t NULL, then it 
35a0: 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65  is invoked for e
35b0: 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a  ach result row.*
35c0: 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20  * coming out of 
35d0: 74 68 65 20 65 76 61 6c 75 61 74 65 64 20 53 51  the evaluated SQ
35e0: 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e  L statements.  ^
35f0: 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74  The 4th argument
3600: 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65   to.** sqlite3_e
3610: 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 65 64  xec() is relayed
3620: 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20   through to the 
3630: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  1st argument of 
3640: 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  each.** callback
3650: 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49   invocation.  ^I
3660: 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 70  f the callback p
3670: 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ointer to sqlite
3680: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e  3_exec().** is N
3690: 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c  ULL, then no cal
36a0: 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 69 6e  lback is ever in
36b0: 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 6c 74  voked and result
36c0: 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e   rows are.** ign
36d0: 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ored..**.** ^If 
36e0: 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
36f0: 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67  while evaluating
3700: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
3710: 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f 0a  nts passed into.
3720: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
3730: 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 69 6f  ), then executio
3740: 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  n of the current
3750: 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f 70 73   statement stops
3760: 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75 65   and.** subseque
3770: 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  nt statements ar
3780: 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 66 20  e skipped.  ^If 
3790: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
37a0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
37b0: 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55  c().** is not NU
37c0: 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 72 6f  LL then any erro
37d0: 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 72 69  r message is wri
37e0: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  tten into memory
37f0: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
3800: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
3810: 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 64 20  c()] and passed 
3820: 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65  back through the
3830: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 2e 0a   5th parameter..
3840: 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f  ** To avoid memo
3850: 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 61 70  ry leaks, the ap
3860: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
3870: 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33   invoke [sqlite3
3880: 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65  _free()].** on e
3890: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
38a0: 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 74 68  ings returned th
38b0: 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61  rough the 5th pa
38c0: 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66  rameter of.** of
38d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
38e0: 61 66 74 65 72 20 74 68 65 20 65 72 72 6f 72 20  after the error 
38f0: 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69  message string i
3900: 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64  s no longer need
3910: 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35  ed..** ^If the 5
3920: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
3930: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3940: 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e  s not NULL and n
3950: 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75  o errors.** occu
3960: 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  r, then sqlite3_
3970: 65 78 65 63 28 29 20 73 65 74 73 20 74 68 65 20  exec() sets the 
3980: 70 6f 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35  pointer in its 5
3990: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  th parameter to.
39a0: 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72  ** NULL before r
39b0: 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  eturning..**.** 
39c0: 5e 49 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65  ^If an sqlite3_e
39d0: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72  xec() callback r
39e0: 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
39f0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   the sqlite3_exe
3a00: 63 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  c().** routine r
3a10: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42  eturns SQLITE_AB
3a20: 4f 52 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f  ORT without invo
3a30: 6b 69 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63  king the callbac
3a40: 6b 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77  k again and.** w
3a50: 69 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61  ithout running a
3a60: 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 53 51  ny subsequent SQ
3a70: 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
3a80: 0a 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67  .** ^The 2nd arg
3a90: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
3aa0: 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c  ite3_exec() call
3ab0: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73  back function is
3ac0: 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
3ad0: 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
3ae0: 20 72 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33   result.  ^The 3
3af0: 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  rd argument to t
3b00: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3b10: 29 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73  ).** callback is
3b20: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
3b30: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
3b40: 20 6f 62 74 61 69 6e 65 64 20 61 73 20 69 66 20   obtained as if 
3b50: 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  from.** [sqlite3
3b60: 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c  _column_text()],
3b70: 20 6f 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f   one for each co
3b80: 6c 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c  lumn.  ^If an el
3b90: 65 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65  ement of a.** re
3ba0: 73 75 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c  sult row is NULL
3bb0: 20 74 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73   then the corres
3bc0: 70 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70  ponding string p
3bd0: 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a  ointer for the.*
3be0: 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  * sqlite3_exec()
3bf0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e   callback is a N
3c00: 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54  ULL pointer.  ^T
3c10: 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20  he 4th argument 
3c20: 74 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65  to the.** sqlite
3c30: 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63  3_exec() callbac
3c40: 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  k is an array of
3c50: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
3c60: 69 6e 67 73 20 77 68 65 72 65 20 65 61 63 68 0a  ings where each.
3c70: 2a 2a 20 65 6e 74 72 79 20 72 65 70 72 65 73 65  ** entry represe
3c80: 6e 74 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  nts the name of 
3c90: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65  corresponding re
3ca0: 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f  sult column as o
3cb0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
3cc0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
3cd0: 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  name()]..**.** ^
3ce0: 49 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  If the 2nd param
3cf0: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
3d00: 65 78 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c  exec() is a NULL
3d10: 20 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e   pointer, a poin
3d20: 74 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70  ter.** to an emp
3d30: 74 79 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20  ty string, or a 
3d40: 70 6f 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e  pointer that con
3d50: 74 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65  tains only white
3d60: 73 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a  space and/or .**
3d70: 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74   SQL comments, t
3d80: 68 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65  hen no SQL state
3d90: 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61  ments are evalua
3da0: 74 65 64 20 61 6e 64 20 74 68 65 20 64 61 74 61  ted and the data
3db0: 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63  base.** is not c
3dc0: 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65  hanged..**.** Re
3dd0: 73 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a  strictions:.**.*
3de0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  * <ul>.** <li> T
3df0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
3e00: 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 20  ust insure that 
3e10: 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65  the 1st paramete
3e20: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
3e30: 63 28 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61  c().**      is a
3e40: 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20   valid and open 
3e50: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3e60: 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54  tion]..** <li> T
3e70: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
3e80: 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 5b 64  ust not close [d
3e90: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
3ea0: 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79  on] specified by
3eb0: 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31 73 74  .**      the 1st
3ec0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3ed0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 69  lite3_exec() whi
3ee0: 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  le sqlite3_exec(
3ef0: 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  ) is running..**
3f00: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63   <li> The applic
3f10: 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d  ation must not m
3f20: 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20 73 74  odify the SQL st
3f30: 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70 61 73  atement text pas
3f40: 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20  sed into.**     
3f50: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
3f60: 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78  er of sqlite3_ex
3f70: 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74  ec() while sqlit
3f80: 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e  e3_exec() is run
3f90: 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  ning..** </ul>.*
3fa0: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  /.int sqlite3_ex
3fb0: 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  ec(.  sqlite3*, 
3fc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fe0: 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61   /* An open data
3ff0: 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  base */.  const 
4000: 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20  char *sql,      
4010: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4020: 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62       /* SQL to b
4030: 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20  e evaluated */. 
4040: 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29   int (*callback)
4050: 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a  (void*,int,char*
4060: 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43  *,char**),  /* C
4070: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
4080: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20   */.  void *,   
4090: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40b0: 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74   /* 1st argument
40c0: 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a   to callback */.
40d0: 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20    char **errmsg 
40e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
4100: 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65  Error msg writte
4110: 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a  n here */.);../*
4120: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
4130: 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45  sult Codes.** KE
4140: 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f  YWORDS: SQLITE_O
4150: 4b 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b  K {error code} {
4160: 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20  error codes}.** 
4170: 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c  KEYWORDS: {resul
4180: 74 20 63 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20  t code} {result 
4190: 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e  codes}.**.** Man
41a0: 79 20 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f  y SQLite functio
41b0: 6e 73 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74  ns return an int
41c0: 65 67 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65  eger result code
41d0: 20 66 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68   from the set sh
41e0: 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f  own.** here in o
41f0: 72 64 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65  rder to indicate
4200: 20 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c   success or fail
4210: 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65  ure..**.** New e
4220: 72 72 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62  rror codes may b
4230: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
4240: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
4250: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  Lite..**.** See 
4260: 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f  also: [SQLITE_IO
4270: 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e  ERR_READ | exten
4280: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4290: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  ],.** [sqlite3_v
42a0: 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28  tab_on_conflict(
42b0: 29 5d 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42  )] [SQLITE_ROLLB
42c0: 41 43 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64  ACK | result cod
42d0: 65 73 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  es]..*/.#define 
42e0: 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20  SQLITE_OK       
42f0: 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65      0   /* Succe
4300: 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a  ssful result */.
4310: 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d  /* beginning-of-
4320: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23  error-codes */.#
4330: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52  define SQLITE_ER
4340: 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 2f  ROR        1   /
4350: 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d  * SQL error or m
4360: 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65 20  issing database 
4370: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4380: 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32  E_INTERNAL     2
4390: 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c     /* Internal l
43a0: 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51  ogic error in SQ
43b0: 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  Lite */.#define 
43c0: 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20  SQLITE_PERM     
43d0: 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73      3   /* Acces
43e0: 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e  s permission den
43f0: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
4400: 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20  QLITE_ABORT     
4410: 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61     4   /* Callba
4420: 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65  ck routine reque
4430: 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f  sted an abort */
4440: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4450: 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20  BUSY         5  
4460: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
4470: 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20   file is locked 
4480: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4490: 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36  E_LOCKED       6
44a0: 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e     /* A table in
44b0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
44c0: 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69   locked */.#defi
44d0: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20  ne SQLITE_NOMEM 
44e0: 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20         7   /* A 
44f0: 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20  malloc() failed 
4500: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4510: 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38  E_READONLY     8
4520: 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f     /* Attempt to
4530: 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c   write a readonl
4540: 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64  y database */.#d
4550: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
4560: 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a  ERRUPT    9   /*
4570: 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69   Operation termi
4580: 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  nated by sqlite3
4590: 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23  _interrupt()*/.#
45a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
45b0: 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f  ERR       10   /
45c0: 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64  * Some kind of d
45d0: 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63  isk I/O error oc
45e0: 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e  curred */.#defin
45f0: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54  e SQLITE_CORRUPT
4600: 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65       11   /* The
4610: 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69   database disk i
4620: 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65  mage is malforme
4630: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4640: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20  ITE_NOTFOUND    
4650: 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20  12   /* Unknown 
4660: 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65  opcode in sqlite
4670: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
4680: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4690: 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31  TE_FULL        1
46a0: 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e  3   /* Insertion
46b0: 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20   failed because 
46c0: 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c  database is full
46d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
46e0: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31  TE_CANTOPEN    1
46f0: 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f  4   /* Unable to
4700: 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   open the databa
4710: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69  se file */.#defi
4720: 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43  ne SQLITE_PROTOC
4730: 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61  OL    15   /* Da
4740: 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74  tabase lock prot
4750: 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64  ocol error */.#d
4760: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50  efine SQLITE_EMP
4770: 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a  TY       16   /*
4780: 20 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70   Database is emp
4790: 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ty */.#define SQ
47a0: 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20  LITE_SCHEMA     
47b0: 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74   17   /* The dat
47c0: 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
47d0: 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nged */.#define 
47e0: 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20  SQLITE_TOOBIG   
47f0: 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e     18   /* Strin
4800: 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64  g or BLOB exceed
4810: 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a  s size limit */.
4820: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
4830: 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20  ONSTRAINT  19   
4840: 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20  /* Abort due to 
4850: 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
4860: 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  tion */.#define 
4870: 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20  SQLITE_MISMATCH 
4880: 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20     20   /* Data 
4890: 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f  type mismatch */
48a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
48b0: 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20  MISUSE      21  
48c0: 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64   /* Library used
48d0: 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a   incorrectly */.
48e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
48f0: 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20  OLFS       22   
4900: 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75  /* Uses OS featu
4910: 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65  res not supporte
4920: 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65  d on host */.#de
4930: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48  fine SQLITE_AUTH
4940: 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
4950: 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65  Authorization de
4960: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
4970: 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20  SQLITE_FORMAT   
4980: 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c     24   /* Auxil
4990: 69 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f  iary database fo
49a0: 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64  rmat error */.#d
49b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e  efine SQLITE_RAN
49c0: 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a  GE       25   /*
49d0: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
49e0: 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f  o sqlite3_bind o
49f0: 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23  ut of range */.#
4a00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
4a10: 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f  TADB      26   /
4a20: 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68  * File opened th
4a30: 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61  at is not a data
4a40: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
4a50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
4a60: 43 45 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20  CE      27   /* 
4a70: 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73 20 66 72  Notifications fr
4a80: 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  om sqlite3_log()
4a90: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4aa0: 54 45 5f 57 41 52 4e 49 4e 47 20 20 20 20 20 32  TE_WARNING     2
4ab0: 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73 20  8   /* Warnings 
4ac0: 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67  from sqlite3_log
4ad0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
4ae0: 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20  LITE_ROW        
4af0: 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33   100  /* sqlite3
4b00: 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74  _step() has anot
4b10: 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f  her row ready */
4b20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4b30: 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20  DONE        101 
4b40: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70   /* sqlite3_step
4b50: 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  () has finished 
4b60: 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20  executing */./* 
4b70: 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64  end-of-error-cod
4b80: 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  es */../*.** CAP
4b90: 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20  I3REF: Extended 
4ba0: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
4bb0: 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e  KEYWORDS: {exten
4bc0: 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 7d 20  ded error code} 
4bd0: 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  {extended error 
4be0: 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52  codes}.** KEYWOR
4bf0: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65  DS: {extended re
4c00: 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78 74 65  sult code} {exte
4c10: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4c20: 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 20  s}.**.** In its 
4c30: 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72  default configur
4c40: 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41 50  ation, SQLite AP
4c50: 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  I routines retur
4c60: 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74 65  n one of 26 inte
4c70: 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  ger.** [SQLITE_O
4c80: 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  K | result codes
4c90: 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70  ].  However, exp
4ca0: 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77  erience has show
4cb0: 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a  n that many of.*
4cc0: 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63  * these result c
4cd0: 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61  odes are too coa
4ce0: 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68  rse-grained.  Th
4cf0: 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64  ey do not provid
4d00: 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66  e as.** much inf
4d10: 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70  ormation about p
4d20: 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72  roblems as progr
4d30: 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b  ammers might lik
4d40: 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74  e.  In an effort
4d50: 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74   to.** address t
4d60: 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69  his, newer versi
4d70: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76  ons of SQLite (v
4d80: 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64  ersion 3.3.8 and
4d90: 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a   later) include.
4da0: 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61  ** support for a
4db0: 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74  dditional result
4dc0: 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76   codes that prov
4dd0: 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65  ide more detaile
4de0: 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  d information.**
4df0: 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54   about errors. T
4e00: 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  he extended resu
4e10: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e 61  lt codes are ena
4e20: 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64  bled or disabled
4e30: 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74  .** on a per dat
4e40: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
4e50: 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68 65   basis using the
4e60: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74  .** [sqlite3_ext
4e70: 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
4e80: 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a  es()] API..**.**
4e90: 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76 61   Some of the ava
4ea0: 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64 20  ilable extended 
4eb0: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4ec0: 20 6c 69 73 74 65 64 20 68 65 72 65 2e 0a 2a 2a   listed here..**
4ed0: 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 63 74 20   One may expect 
4ee0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78  the number of ex
4ef0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
4f00: 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78 70 61  des will be expa
4f10: 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65 2e  nd.** over time.
4f20: 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20    Software that 
4f30: 75 73 65 73 20 65 78 74 65 6e 64 65 64 20 72 65  uses extended re
4f40: 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f 75 6c  sult codes shoul
4f50: 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20 73  d expect.** to s
4f60: 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20 63 6f  ee new result co
4f70: 64 65 73 20 69 6e 20 66 75 74 75 72 65 20 72 65  des in future re
4f80: 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
4f90: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ..**.** The SQLI
4fa0: 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f 64  TE_OK result cod
4fb0: 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65 20  e will never be 
4fc0: 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77 69  extended.  It wi
4fd0: 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20  ll always.** be 
4fe0: 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f  exactly zero..*/
4ff0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5000: 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20 20  IOERR_READ      
5010: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5020: 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a  IOERR | (1<<8)).
5030: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5040: 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20  OERR_SHORT_READ 
5050: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5060: 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23  OERR | (2<<8)).#
5070: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5080: 45 52 52 5f 57 52 49 54 45 20 20 20 20 20 20 20  ERR_WRITE       
5090: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
50a0: 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  ERR | (3<<8)).#d
50b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
50c0: 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20  RR_FSYNC        
50d0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
50e0: 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65  RR | (4<<8)).#de
50f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5100: 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20 20  R_DIR_FSYNC     
5110: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5120: 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66  R | (5<<8)).#def
5130: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5140: 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20 20 20  _TRUNCATE       
5150: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5160: 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69   | (6<<8)).#defi
5170: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5180: 46 53 54 41 54 20 20 20 20 20 20 20 20 20 20 20  FSTAT           
5190: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
51a0: 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (7<<8)).#defin
51b0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55  e SQLITE_IOERR_U
51c0: 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  NLOCK           
51d0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
51e0: 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (8<<8)).#define
51f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44   SQLITE_IOERR_RD
5200: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20  LOCK            
5210: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5220: 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (9<<8)).#define 
5230: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c  SQLITE_IOERR_DEL
5240: 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 28  ETE            (
5250: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5260: 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  10<<8)).#define 
5270: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
5280: 43 4b 45 44 20 20 20 20 20 20 20 20 20 20 20 28  CKED           (
5290: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
52a0: 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  11<<8)).#define 
52b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d  SQLITE_IOERR_NOM
52c0: 45 4d 20 20 20 20 20 20 20 20 20 20 20 20 20 28  EM             (
52d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
52e0: 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  12<<8)).#define 
52f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 43  SQLITE_IOERR_ACC
5300: 45 53 53 20 20 20 20 20 20 20 20 20 20 20 20 28  ESS            (
5310: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5320: 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  13<<8)).#define 
5330: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48 45  SQLITE_IOERR_CHE
5340: 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b 20 28  CKRESERVEDLOCK (
5350: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5360: 31 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  14<<8)).#define 
5370: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f 43  SQLITE_IOERR_LOC
5380: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  K              (
5390: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
53a0: 31 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  15<<8)).#define 
53b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c 4f  SQLITE_IOERR_CLO
53c0: 53 45 20 20 20 20 20 20 20 20 20 20 20 20 20 28  SE             (
53d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
53e0: 31 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  16<<8)).#define 
53f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52  SQLITE_IOERR_DIR
5400: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 28  _CLOSE         (
5410: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5420: 31 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  17<<8)).#define 
5430: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
5440: 4f 50 45 4e 20 20 20 20 20 20 20 20 20 20 20 28  OPEN           (
5450: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5460: 31 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  18<<8)).#define 
5470: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
5480: 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 28  SIZE           (
5490: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
54a0: 31 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  19<<8)).#define 
54b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
54c0: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 28  LOCK           (
54d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
54e0: 32 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  20<<8)).#define 
54f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
5500: 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20 28  MAP            (
5510: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5520: 32 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  21<<8)).#define 
5530: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45 45  SQLITE_IOERR_SEE
5540: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  K              (
5550: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5560: 32 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  22<<8)).#define 
5570: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c  SQLITE_IOERR_DEL
5580: 45 54 45 5f 4e 4f 45 4e 54 20 20 20 20 20 20 28  ETE_NOENT      (
5590: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
55a0: 32 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  23<<8)).#define 
55b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4d 4d 41  SQLITE_IOERR_MMA
55c0: 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  P              (
55d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
55e0: 32 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  24<<8)).#define 
55f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 47 45 54  SQLITE_IOERR_GET
5600: 54 45 4d 50 50 41 54 48 20 20 20 20 20 20 20 28  TEMPPATH       (
5610: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5620: 32 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  25<<8)).#define 
5630: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4f 4e  SQLITE_IOERR_CON
5640: 56 50 41 54 48 20 20 20 20 20 20 20 20 20 20 28  VPATH          (
5650: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5660: 32 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  26<<8)).#define 
5670: 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48  SQLITE_LOCKED_SH
5680: 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20 28  AREDCACHE      (
5690: 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20  SQLITE_LOCKED | 
56a0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
56b0: 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 52 45 43   SQLITE_BUSY_REC
56c0: 4f 56 45 52 59 20 20 20 20 20 20 20 20 20 20 20  OVERY           
56d0: 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c  (SQLITE_BUSY   |
56e0: 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e    (1<<8)).#defin
56f0: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 53 4e  e SQLITE_BUSY_SN
5700: 41 50 53 48 4f 54 20 20 20 20 20 20 20 20 20 20  APSHOT          
5710: 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20   (SQLITE_BUSY   
5720: 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69  |  (2<<8)).#defi
5730: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
5740: 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20  EN_NOTEMPDIR    
5750: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50    (SQLITE_CANTOP
5760: 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  EN | (1<<8)).#de
5770: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54  fine SQLITE_CANT
5780: 4f 50 45 4e 5f 49 53 44 49 52 20 20 20 20 20 20  OPEN_ISDIR      
5790: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54      (SQLITE_CANT
57a0: 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29 29 0a 23  OPEN | (2<<8)).#
57b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
57c0: 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 41 54 48 20  NTOPEN_FULLPATH 
57d0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
57e0: 4e 54 4f 50 45 4e 20 7c 20 28 33 3c 3c 38 29 29  NTOPEN | (3<<8))
57f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5800: 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e 56 50 41 54  CANTOPEN_CONVPAT
5810: 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  H       (SQLITE_
5820: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 34 3c 3c 38  CANTOPEN | (4<<8
5830: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5840: 45 5f 43 4f 52 52 55 50 54 5f 56 54 41 42 20 20  E_CORRUPT_VTAB  
5850: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5860: 45 5f 43 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c  E_CORRUPT | (1<<
5870: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5880: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f  TE_READONLY_RECO
5890: 56 45 52 59 20 20 20 20 20 20 20 28 53 51 4c 49  VERY       (SQLI
58a0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31  TE_READONLY | (1
58b0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
58c0: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41  LITE_READONLY_CA
58d0: 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20 28 53 51  NTLOCK       (SQ
58e0: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20  LITE_READONLY | 
58f0: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
5900: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
5910: 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 28  ROLLBACK       (
5920: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
5930: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (3<<8)).#defin
5940: 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52  e SQLITE_ABORT_R
5950: 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 20 20  OLLBACK         
5960: 20 28 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c   (SQLITE_ABORT |
5970: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
5980: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5990: 4e 54 5f 43 48 45 43 4b 20 20 20 20 20 20 20 20  NT_CHECK        
59a0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
59b0: 4e 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  NT | (1<<8)).#de
59c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
59d0: 54 52 41 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f  TRAINT_COMMITHOO
59e0: 4b 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53  K   (SQLITE_CONS
59f0: 54 52 41 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29  TRAINT | (2<<8))
5a00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5a10: 43 4f 4e 53 54 52 41 49 4e 54 5f 46 4f 52 45 49  CONSTRAINT_FOREI
5a20: 47 4e 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f  GNKEY   (SQLITE_
5a30: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 33 3c  CONSTRAINT | (3<
5a40: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5a50: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46  ITE_CONSTRAINT_F
5a60: 55 4e 43 54 49 4f 4e 20 20 20 20 20 28 53 51 4c  UNCTION     (SQL
5a70: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5a80: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
5a90: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5aa0: 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20  NT_NOTNULL      
5ab0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5ac0: 4e 54 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65  NT | (5<<8)).#de
5ad0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5ae0: 54 52 41 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45  TRAINT_PRIMARYKE
5af0: 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53  Y   (SQLITE_CONS
5b00: 54 52 41 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29  TRAINT | (6<<8))
5b10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5b20: 43 4f 4e 53 54 52 41 49 4e 54 5f 54 52 49 47 47  CONSTRAINT_TRIGG
5b30: 45 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  ER      (SQLITE_
5b40: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 37 3c  CONSTRAINT | (7<
5b50: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5b60: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55  ITE_CONSTRAINT_U
5b70: 4e 49 51 55 45 20 20 20 20 20 20 20 28 53 51 4c  NIQUE       (SQL
5b80: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5b90: 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (8<<8)).#define
5ba0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5bb0: 4e 54 5f 56 54 41 42 20 20 20 20 20 20 20 20 20  NT_VTAB         
5bc0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5bd0: 4e 54 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65  NT | (9<<8)).#de
5be0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
5bf0: 43 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20 20  CE_RECOVER_WAL  
5c00: 20 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49      (SQLITE_NOTI
5c10: 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  CE | (1<<8)).#de
5c20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
5c30: 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42  CE_RECOVER_ROLLB
5c40: 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49  ACK (SQLITE_NOTI
5c50: 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  CE | (2<<8)).#de
5c60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e  fine SQLITE_WARN
5c70: 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20 20  ING_AUTOINDEX   
5c80: 20 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52 4e      (SQLITE_WARN
5c90: 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f  ING | (1<<8))../
5ca0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
5cb0: 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70  lags For File Op
5cc0: 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  en Operations.**
5cd0: 0a 2a 2a 20 54 68 65 73 65 20 62 69 74 20 76 61  .** These bit va
5ce0: 6c 75 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65  lues are intende
5cf0: 64 20 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65  d for use in the
5d00: 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65  .** 3rd paramete
5d10: 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
5d20: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74  3_open_v2()] int
5d30: 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e  erface and.** in
5d40: 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
5d50: 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
5d60: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65  e3_vfs.xOpen] me
5d70: 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  thod..*/.#define
5d80: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
5d90: 44 4f 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78  DONLY         0x
5da0: 30 30 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20  00000001  /* Ok 
5db0: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
5dc0: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
5dd0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
5de0: 44 57 52 49 54 45 20 20 20 20 20 20 20 20 30 78  DWRITE        0x
5df0: 30 30 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20  00000002  /* Ok 
5e00: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
5e10: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
5e20: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
5e30: 41 54 45 20 20 20 20 20 20 20 20 20 20 20 30 78  ATE           0x
5e40: 30 30 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20  00000004  /* Ok 
5e50: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
5e60: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
5e70: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c   SQLITE_OPEN_DEL
5e80: 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78  ETEONCLOSE    0x
5e90: 30 30 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53  00000008  /* VFS
5ea0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
5eb0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43   SQLITE_OPEN_EXC
5ec0: 4c 55 53 49 56 45 20 20 20 20 20 20 20 20 30 78  LUSIVE        0x
5ed0: 30 30 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53  00000010  /* VFS
5ee0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
5ef0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54   SQLITE_OPEN_AUT
5f00: 4f 50 52 4f 58 59 20 20 20 20 20 20 20 20 30 78  OPROXY        0x
5f10: 30 30 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53  00000020  /* VFS
5f20: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
5f30: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49   SQLITE_OPEN_URI
5f40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
5f50: 30 30 30 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20  00000040  /* Ok 
5f60: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
5f70: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
5f80: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d   SQLITE_OPEN_MEM
5f90: 4f 52 59 20 20 20 20 20 20 20 20 20 20 20 30 78  ORY           0x
5fa0: 30 30 30 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20  00000080  /* Ok 
5fb0: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
5fc0: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
5fd0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49   SQLITE_OPEN_MAI
5fe0: 4e 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78  N_DB          0x
5ff0: 30 30 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53  00000100  /* VFS
6000: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
6010: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d   SQLITE_OPEN_TEM
6020: 50 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78  P_DB          0x
6030: 30 30 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53  00000200  /* VFS
6040: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
6050: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41   SQLITE_OPEN_TRA
6060: 4e 53 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78  NSIENT_DB     0x
6070: 30 30 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53  00000400  /* VFS
6080: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
6090: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49   SQLITE_OPEN_MAI
60a0: 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78  N_JOURNAL     0x
60b0: 30 30 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53  00000800  /* VFS
60c0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
60d0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d   SQLITE_OPEN_TEM
60e0: 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78  P_JOURNAL     0x
60f0: 30 30 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53  00001000  /* VFS
6100: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
6110: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42   SQLITE_OPEN_SUB
6120: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78  JOURNAL       0x
6130: 30 30 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53  00002000  /* VFS
6140: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
6150: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53   SQLITE_OPEN_MAS
6160: 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78  TER_JOURNAL   0x
6170: 30 30 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53  00004000  /* VFS
6180: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
6190: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d   SQLITE_OPEN_NOM
61a0: 55 54 45 58 20 20 20 20 20 20 20 20 20 20 30 78  UTEX          0x
61b0: 30 30 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20  00008000  /* Ok 
61c0: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
61d0: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
61e0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c   SQLITE_OPEN_FUL
61f0: 4c 4d 55 54 45 58 20 20 20 20 20 20 20 20 30 78  LMUTEX        0x
6200: 30 30 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20  00010000  /* Ok 
6210: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
6220: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
6230: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41   SQLITE_OPEN_SHA
6240: 52 45 44 43 41 43 48 45 20 20 20 20 20 20 30 78  REDCACHE      0x
6250: 30 30 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20  00020000  /* Ok 
6260: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
6270: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
6280: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49   SQLITE_OPEN_PRI
6290: 56 41 54 45 43 41 43 48 45 20 20 20 20 20 30 78  VATECACHE     0x
62a0: 30 30 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20  00040000  /* Ok 
62b0: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
62c0: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
62d0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c   SQLITE_OPEN_WAL
62e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
62f0: 30 30 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53  00080000  /* VFS
6300: 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73   only */../* Res
6310: 65 72 76 65 64 3a 20 20 20 20 20 20 20 20 20 20  erved:          
6320: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
6330: 78 30 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a  x00F00000 */../*
6340: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
6350: 76 69 63 65 20 43 68 61 72 61 63 74 65 72 69 73  vice Characteris
6360: 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  tics.**.** The x
6370: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
6380: 73 74 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20  stics method of 
6390: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
63a0: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65  methods].** obje
63b0: 63 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e  ct returns an in
63c0: 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 61  teger which is a
63d0: 20 76 65 63 74 6f 72 20 6f 66 20 74 68 65 73 65   vector of these
63e0: 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65  .** bit values e
63f0: 78 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68  xpressing I/O ch
6400: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6f 66  aracteristics of
6410: 20 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67   the mass storag
6420: 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74  e.** device that
6430: 20 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20   holds the file 
6440: 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65  that the [sqlite
6450: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  3_io_methods].**
6460: 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a   refers to..**.*
6470: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43  * The SQLITE_IOC
6480: 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72  AP_ATOMIC proper
6490: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c  ty means that al
64a0: 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61  l writes of.** a
64b0: 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d  ny size are atom
64c0: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ic.  The SQLITE_
64d0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20  IOCAP_ATOMICnnn 
64e0: 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74  values.** mean t
64f0: 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c  hat writes of bl
6500: 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e  ocks that are nn
6510: 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20  n bytes in size 
6520: 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e  and.** are align
6530: 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73  ed to an address
6540: 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74   which is an int
6550: 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66  eger multiple of
6560: 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d  .** nnn are atom
6570: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ic.  The SQLITE_
6580: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
6590: 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a  D value means.**
65a0: 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20   that when data 
65b0: 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61  is appended to a
65c0: 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20   file, the data 
65d0: 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66  is appended.** f
65e0: 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69  irst then the si
65f0: 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69  ze of the file i
6600: 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65  s extended, neve
6610: 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77  r the other.** w
6620: 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20  ay around.  The 
6630: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
6640: 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79  UENTIAL property
6650: 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69   means that.** i
6660: 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72  nformation is wr
6670: 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e  itten to disk in
6680: 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20   the same order 
6690: 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78  as calls.** to x
66a0: 57 72 69 74 65 28 29 2e 20 20 54 68 65 20 53 51  Write().  The SQ
66b0: 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52  LITE_IOCAP_POWER
66c0: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 70  SAFE_OVERWRITE p
66d0: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
66e0: 61 74 0a 2a 2a 20 61 66 74 65 72 20 72 65 62 6f  at.** after rebo
66f0: 6f 74 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63  ot following a c
6700: 72 61 73 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f  rash or power lo
6710: 73 73 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79 74  ss, the only byt
6720: 65 73 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20  es in a.** file 
6730: 74 68 61 74 20 77 65 72 65 20 77 72 69 74 74 65  that were writte
6740: 6e 20 61 74 20 74 68 65 20 61 70 70 6c 69 63 61  n at the applica
6750: 74 69 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74  tion level might
6760: 20 68 61 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a   have changed.**
6770: 20 61 6e 64 20 74 68 61 74 20 61 64 6a 61 63 65   and that adjace
6780: 6e 74 20 62 79 74 65 73 2c 20 65 76 65 6e 20 62  nt bytes, even b
6790: 79 74 65 73 20 77 69 74 68 69 6e 20 74 68 65 20  ytes within the 
67a0: 73 61 6d 65 20 73 65 63 74 6f 72 20 61 72 65 0a  same sector are.
67b0: 2a 2a 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f  ** guaranteed to
67c0: 20 62 65 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a   be unchanged..*
67d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
67e0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20  _IOCAP_ATOMIC   
67f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6800: 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65  00000001.#define
6810: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6820: 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 20 20  OMIC512         
6830: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0a       0x00000002.
6840: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6850: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20  OCAP_ATOMIC1K   
6860: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6870: 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53  000004.#define S
6880: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6890: 49 43 32 4b 20 20 20 20 20 20 20 20 20 20 20 20  IC2K            
68a0: 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23 64     0x00000008.#d
68b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
68c0: 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20  AP_ATOMIC4K     
68d0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
68e0: 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0010.#define SQL
68f0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6900: 38 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  8K              
6910: 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 65 66   0x00000020.#def
6920: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6930: 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20  _ATOMIC16K      
6940: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6950: 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  40.#define SQLIT
6960: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32  E_IOCAP_ATOMIC32
6970: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  K              0
6980: 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e  x00000080.#defin
6990: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
69a0: 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20 20  TOMIC64K        
69b0: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30        0x00000100
69c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
69d0: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
69e0: 44 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30  D            0x0
69f0: 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20  0000200.#define 
6a00: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
6a10: 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20 20 20  UENTIAL         
6a20: 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a 23      0x00000400.#
6a30: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6a40: 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f  CAP_UNDELETABLE_
6a50: 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30  WHEN_OPEN  0x000
6a60: 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00800.#define SQ
6a70: 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52  LITE_IOCAP_POWER
6a80: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20  SAFE_OVERWRITE  
6a90: 20 20 30 78 30 30 30 30 31 30 30 30 0a 0a 2f 2a    0x00001000../*
6aa0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69  .** CAPI3REF: Fi
6ab0: 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c  le Locking Level
6ac0: 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75  s.**.** SQLite u
6ad0: 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65  ses one of these
6ae0: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
6af0: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  as the second.**
6b00: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c   argument to cal
6b10: 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74  ls it makes to t
6b20: 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78  he xLock() and x
6b30: 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73  Unlock() methods
6b40: 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  .** of an [sqlit
6b50: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
6b60: 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e  bject..*/.#defin
6b70: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f  e SQLITE_LOCK_NO
6b80: 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23 64  NE          0.#d
6b90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
6ba0: 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 20  K_SHARED        
6bb0: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
6bc0: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20  _LOCK_RESERVED  
6bd0: 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
6be0: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
6bf0: 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e  G       3.#defin
6c00: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58  e SQLITE_LOCK_EX
6c10: 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f  CLUSIVE     4../
6c20: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
6c30: 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54  ynchronization T
6c40: 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20  ype Flags.**.** 
6c50: 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f  When SQLite invo
6c60: 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 29 20  kes the xSync() 
6c70: 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20  method of an.** 
6c80: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
6c90: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75  ods] object it u
6ca0: 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f  ses a combinatio
6cb0: 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e  n of.** these in
6cc0: 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20  teger values as 
6cd0: 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
6ce0: 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  ent..**.** When 
6cf0: 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  the SQLITE_SYNC_
6d00: 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73  DATAONLY flag is
6d10: 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20   used, it means 
6d20: 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63  that the.** sync
6d30: 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20   operation only 
6d40: 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64  needs to flush d
6d50: 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72  ata to mass stor
6d60: 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69  age.  Inode.** i
6d70: 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20  nformation need 
6d80: 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20  not be flushed. 
6d90: 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75  If the lower fou
6da0: 72 20 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c  r bits of the fl
6db0: 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49  ag.** equal SQLI
6dc0: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20  TE_SYNC_NORMAL, 
6dd0: 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73  that means to us
6de0: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29  e normal fsync()
6df0: 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49   semantics..** I
6e00: 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72  f the lower four
6e10: 20 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49   bits equal SQLI
6e20: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68  TE_SYNC_FULL, th
6e30: 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75  at means.** to u
6e40: 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c  se Mac OS X styl
6e50: 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65  e fullsync inste
6e60: 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a  ad of fsync()..*
6e70: 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66  *.** Do not conf
6e80: 75 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f 53  use the SQLITE_S
6e90: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
6ea0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
6eb0: 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 68  flags.** with th
6ec0: 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72  e [PRAGMA synchr
6ed0: 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e  onous]=NORMAL an
6ee0: 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72  d [PRAGMA synchr
6ef0: 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73  onous]=FULL.** s
6f00: 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b 73  ettings.  The [s
6f10: 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d  ynchronous pragm
6f20: 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68  a] determines wh
6f30: 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a  en calls to the.
6f40: 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65 74  ** xSync VFS met
6f50: 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61 70  hod occur and ap
6f60: 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20  plies uniformly 
6f70: 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66  across all platf
6f80: 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  orms..** The SQL
6f90: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
6fa0: 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  and SQLITE_SYNC_
6fb0: 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 72  FULL flags deter
6fc0: 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72  mine how.** ener
6fd0: 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f 75  getic or rigorou
6fe0: 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 68  s or forceful th
6ff0: 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e  e sync operation
7000: 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c  s are and.** onl
7010: 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72 65  y make a differe
7020: 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66  nce on Mac OSX f
7030: 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74 20 53  or the default S
7040: 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28  QLite code..** (
7050: 54 68 69 72 64 2d 70 61 72 74 79 20 56 46 53 20  Third-party VFS 
7060: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
7070: 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20  might also make 
7080: 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a  the distinction.
7090: 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54  ** between SQLIT
70a0: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e  E_SYNC_NORMAL an
70b0: 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  d SQLITE_SYNC_FU
70c0: 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 68  LL, but among th
70d0: 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 73  e.** operating s
70e0: 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 20  ystems natively 
70f0: 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c  supported by SQL
7100: 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53  ite, only Mac OS
7110: 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 74  X.** cares about
7120: 20 74 68 65 20 64 69 66 66 65 72 65 6e 63 65 2e   the difference.
7130: 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ).*/.#define SQL
7140: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
7150: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a 23         0x00002.#
7160: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
7170: 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20  NC_FULL         
7180: 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65   0x00003.#define
7190: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54   SQLITE_SYNC_DAT
71a0: 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30  AONLY      0x000
71b0: 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  10../*.** CAPI3R
71c0: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65  EF: OS Interface
71d0: 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c   Open File Handl
71e0: 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69  e.**.** An [sqli
71f0: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
7200: 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f   represents an o
7210: 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20  pen file in the 
7220: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  .** [sqlite3_vfs
7230: 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20   | OS interface 
7240: 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 64  layer].  Individ
7250: 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65  ual OS interface
7260: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
7270: 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74  ons will.** want
7280: 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69   to subclass thi
7290: 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65  s object by appe
72a0: 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c  nding additional
72b0: 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74   fields.** for t
72c0: 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54  heir own use.  T
72d0: 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72  he pMethods entr
72e0: 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  y is a pointer t
72f0: 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  o an.** [sqlite3
7300: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
7310: 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73  ect that defines
7320: 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72   methods for per
7330: 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f  forming.** I/O o
7340: 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65  perations on the
7350: 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74   open file..*/.t
7360: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
7370: 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74  lite3_file sqlit
7380: 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20  e3_file;.struct 
7390: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20  sqlite3_file {. 
73a0: 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71   const struct sq
73b0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
73c0: 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20   *pMethods;  /* 
73d0: 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f  Methods for an o
73e0: 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a  pen file */.};..
73f0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7400: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c  OS Interface Fil
7410: 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64  e Virtual Method
7420: 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45  s Object.**.** E
7430: 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64  very file opened
7440: 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
7450: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
7460: 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a  od populates an.
7470: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
7480: 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f  ] object (or, mo
7490: 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73  re commonly, a s
74a0: 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a  ubclass of the.*
74b0: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  * [sqlite3_file]
74c0: 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61 20   object) with a 
74d0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
74e0: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
74f0: 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f  bject..** This o
7500: 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68  bject defines th
7510: 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74  e methods used t
7520: 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75  o perform variou
7530: 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20  s operations.** 
7540: 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e  against the open
7550: 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65   file represente
7560: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
7570: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a  3_file] object..
7580: 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 71  **.** If the [sq
7590: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
75a0: 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68 65   method sets the
75b0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
75c0: 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a  ethods element .
75d0: 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c  ** to a non-NULL
75e0: 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74   pointer, then t
75f0: 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  he sqlite3_io_me
7600: 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74  thods.xClose met
7610: 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e  hod.** may be in
7620: 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74 68  voked even if th
7630: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
7640: 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20 74  Open] reported t
7650: 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20  hat it failed.  
7660: 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20  The.** only way 
7670: 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c  to prevent a cal
7680: 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c  l to xClose foll
7690: 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 5b  owing a failed [
76a0: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
76b0: 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 65  n].** is for the
76c0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
76d0: 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65 20  pen] to set the 
76e0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
76f0: 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a  thods element.**
7700: 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   to NULL..**.** 
7710: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
7720: 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20  nt to xSync may 
7730: 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  be one of [SQLIT
7740: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f  E_SYNC_NORMAL] o
7750: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e  r.** [SQLITE_SYN
7760: 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69  C_FULL].  The fi
7770: 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68  rst choice is th
7780: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29  e normal fsync()
7790: 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
77a0: 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20  choice is a Mac 
77b0: 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73  OS X style fulls
77c0: 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ync.  The [SQLIT
77d0: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d  E_SYNC_DATAONLY]
77e0: 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20  .** flag may be 
77f0: 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63  ORed in to indic
7800: 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68  ate that only th
7810: 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69  e data of the fi
7820: 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74  le.** and not it
7830: 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f  s inode needs to
7840: 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a   be synced..**.*
7850: 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61  * The integer va
7860: 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20  lues to xLock() 
7870: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72  and xUnlock() ar
7880: 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e  e one of.** <ul>
7890: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
78a0: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20  _LOCK_NONE],.** 
78b0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
78c0: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c  K_SHARED],.** <l
78d0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
78e0: 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c  RESERVED],.** <l
78f0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
7900: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20  PENDING], or.** 
7910: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
7920: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a  K_EXCLUSIVE]..**
7930: 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28   </ul>.** xLock(
7940: 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20  ) increases the 
7950: 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20  lock. xUnlock() 
7960: 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f  decreases the lo
7970: 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63  ck..** The xChec
7980: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20  kReservedLock() 
7990: 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68  method checks wh
79a0: 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61  ether any databa
79b0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a  se connection,.*
79c0: 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73  * either in this
79d0: 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73   process or in s
79e0: 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73  ome other proces
79f0: 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  s, is holding a 
7a00: 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e  RESERVED,.** PEN
7a10: 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49  DING, or EXCLUSI
7a20: 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66  VE lock on the f
7a30: 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73  ile.  It returns
7a40: 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68   true.** if such
7a50: 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61   a lock exists a
7a60: 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69  nd false otherwi
7a70: 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  se..**.** The xF
7a80: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74  ileControl() met
7a90: 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63  hod is a generic
7aa0: 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
7ab0: 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a  allows custom.**
7ac0: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
7ad0: 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79  ions to directly
7ae0: 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e   control an open
7af0: 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a   file using the.
7b00: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
7b10: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65  _control()] inte
7b20: 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f  rface.  The seco
7b30: 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74  nd "op" argument
7b40: 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65   is an.** intege
7b50: 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74  r opcode.  The t
7b60: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
7b70: 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74   a generic point
7b80: 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a  er intended to.*
7b90: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  * point to a str
7ba0: 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20  ucture that may 
7bb0: 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74  contain argument
7bc0: 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68  s or space in wh
7bd0: 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20  ich to.** write 
7be0: 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20  return values.  
7bf0: 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66  Potential uses f
7c00: 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28  or xFileControl(
7c10: 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75  ) might be.** fu
7c20: 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c  nctions to enabl
7c30: 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73  e blocking locks
7c40: 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20   with timeouts, 
7c50: 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a  to change the.**
7c60: 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67   locking strateg
7c70: 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74  y (for example t
7c80: 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c  o use dot-file l
7c90: 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72  ocks), to inquir
7ca0: 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73  e.** about the s
7cb0: 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c  tatus of a lock,
7cc0: 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61   or to break sta
7cd0: 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53  le locks.  The S
7ce0: 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65  QLite.** core re
7cf0: 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64  serves all opcod
7d00: 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30  es less than 100
7d10: 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65   for its own use
7d20: 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46  ..** A [SQLITE_F
7d30: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c  CNTL_LOCKSTATE |
7d40: 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73   list of opcodes
7d50: 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20  ] less than 100 
7d60: 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a  is available..**
7d70: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
7d80: 61 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74  at define a cust
7d90: 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  om xFileControl 
7da0: 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73  method should us
7db0: 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65  e opcodes.** gre
7dc0: 61 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f  ater than 100 to
7dd0: 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73   avoid conflicts
7de0: 2e 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  .  VFS implement
7df0: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a  ations should.**
7e00: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
7e10: 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69  NOTFOUND] for fi
7e20: 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64  le control opcod
7e30: 65 73 20 74 68 61 74 20 74 68 65 79 20 64 6f 20  es that they do 
7e40: 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65  not.** recognize
7e50: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63  ..**.** The xSec
7e60: 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64  torSize() method
7e70: 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63   returns the sec
7e80: 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a  tor size of the.
7e90: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75  ** device that u
7ea0: 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c  nderlies the fil
7eb0: 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73  e.  The sector s
7ec0: 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69  ize is the.** mi
7ed0: 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74  nimum write that
7ee0: 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65   can be performe
7ef0: 64 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72  d without distur
7f00: 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79  bing.** other by
7f10: 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e  tes in the file.
7f20: 20 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61    The xDeviceCha
7f30: 72 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a  racteristics().*
7f40: 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  * method returns
7f50: 20 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65   a bit vector de
7f60: 73 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f  scribing behavio
7f70: 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64  rs of the.** und
7f80: 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a  erlying device:.
7f90: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
7fa0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
7fb0: 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e  _ATOMIC].** <li>
7fc0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
7fd0: 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69  TOMIC512].** <li
7fe0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
7ff0: 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC1K].** <li
8000: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8010: 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC2K].** <li
8020: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8030: 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC4K].** <li
8040: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8050: 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC8K].** <li
8060: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8070: 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC16K].** <l
8080: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8090: 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c  _ATOMIC32K].** <
80a0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
80b0: 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20  P_ATOMIC64K].** 
80c0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
80d0: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a  AP_SAFE_APPEND].
80e0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
80f0: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
8100: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
8110: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
8120: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
8130: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
8140: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
8150: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
8160: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
8170: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
8180: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
8190: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
81a0: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
81b0: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
81c0: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
81d0: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
81e0: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
81f0: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
8200: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
8210: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
8220: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
8230: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
8240: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
8250: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
8260: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
8270: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
8280: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
8290: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
82a0: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
82b0: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
82c0: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
82d0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
82e0: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
82f0: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
8300: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
8310: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
8320: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
8330: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
8340: 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66  rite()..**.** If
8350: 20 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73   xRead() returns
8360: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
8370: 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74  ORT_READ it must
8380: 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e   also fill.** in
8390: 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74   the unread port
83a0: 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66  ions of the buff
83b0: 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20  er with zeros.  
83c0: 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61  A VFS that.** fa
83d0: 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c  ils to zero-fill
83e0: 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67   short reads mig
83f0: 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e  ht seem to work.
8400: 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61    However,.** fa
8410: 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69  ilure to zero-fi
8420: 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77  ll short reads w
8430: 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c  ill eventually l
8440: 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61  ead to.** databa
8450: 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  se corruption..*
8460: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
8470: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
8480: 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ods sqlite3_io_m
8490: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
84a0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
84b0: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
84c0: 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f  on;.  int (*xClo
84d0: 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  se)(sqlite3_file
84e0: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61  *);.  int (*xRea
84f0: 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  d)(sqlite3_file*
8500: 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  , void*, int iAm
8510: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
8520: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
8530: 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33  *xWrite)(sqlite3
8540: 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f  _file*, const vo
8550: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
8560: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
8570: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72  st);.  int (*xTr
8580: 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f  uncate)(sqlite3_
8590: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
85a0: 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e  nt64 size);.  in
85b0: 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74  t (*xSync)(sqlit
85c0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c  e3_file*, int fl
85d0: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  ags);.  int (*xF
85e0: 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33  ileSize)(sqlite3
85f0: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
8600: 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20  int64 *pSize);. 
8610: 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71   int (*xLock)(sq
8620: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8630: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f  );.  int (*xUnlo
8640: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
8650: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
8660: 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c  *xCheckReservedL
8670: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
8680: 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74  e*, int *pResOut
8690: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65  );.  int (*xFile
86a0: 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33  Control)(sqlite3
86b0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20  _file*, int op, 
86c0: 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69  void *pArg);.  i
86d0: 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65  nt (*xSectorSize
86e0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
86f0: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63  ;.  int (*xDevic
8700: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
8710: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
8720: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
8730: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
8740: 6f 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a  or version 1 */.
8750: 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29    int (*xShmMap)
8760: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8770: 69 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73  int iPg, int pgs
8780: 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c  z, int, void vol
8790: 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20  atile**);.  int 
87a0: 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69  (*xShmLock)(sqli
87b0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f  te3_file*, int o
87c0: 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e  ffset, int n, in
87d0: 74 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64  t flags);.  void
87e0: 20 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28   (*xShmBarrier)(
87f0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
8800: 20 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61    int (*xShmUnma
8810: 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  p)(sqlite3_file*
8820: 2c 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67  , int deleteFlag
8830: 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  );.  /* Methods 
8840: 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20  above are valid 
8850: 66 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f  for version 2 */
8860: 0a 20 20 69 6e 74 20 28 2a 78 46 65 74 63 68 29  .  int (*xFetch)
8870: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8880: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f  sqlite3_int64 iO
8890: 66 73 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76  fst, int iAmt, v
88a0: 6f 69 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74  oid **pp);.  int
88b0: 20 28 2a 78 55 6e 66 65 74 63 68 29 28 73 71 6c   (*xUnfetch)(sql
88c0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
88d0: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c  te3_int64 iOfst,
88e0: 20 76 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20   void *p);.  /* 
88f0: 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  Methods above ar
8900: 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73  e valid for vers
8910: 69 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64  ion 3 */.  /* Ad
8920: 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73  ditional methods
8930: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
8940: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
8950: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
8960: 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64  PI3REF: Standard
8970: 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70   File Control Op
8980: 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  codes.**.** Thes
8990: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
89a0: 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20  nts are opcodes 
89b0: 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e  for the xFileCon
89c0: 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f  trol method.** o
89d0: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  f the [sqlite3_i
89e0: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
89f0: 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73  t and for the [s
8a00: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
8a10: 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  rol()].** interf
8a20: 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  ace..**.** The [
8a30: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43  SQLITE_FCNTL_LOC
8a40: 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69  KSTATE] opcode i
8a50: 73 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67  s used for debug
8a60: 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f  ging.  This.** o
8a70: 70 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65  pcode causes the
8a80: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
8a90: 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68  thod to write th
8aa0: 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 20  e current state 
8ab0: 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28  of.** the lock (
8ac0: 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c  one of [SQLITE_L
8ad0: 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49  OCK_NONE], [SQLI
8ae0: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c  TE_LOCK_SHARED],
8af0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  .** [SQLITE_LOCK
8b00: 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c  _RESERVED], [SQL
8b10: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47  ITE_LOCK_PENDING
8b20: 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f  ], or [SQLITE_LO
8b30: 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a  CK_EXCLUSIVE]).*
8b40: 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65  * into an intege
8b50: 72 20 74 68 61 74 20 74 68 65 20 70 41 72 67 20  r that the pArg 
8b60: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20  argument points 
8b70: 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62 69 6c  to. This capabil
8b80: 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64  ity.** is used d
8b90: 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e  uring testing an
8ba0: 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  d only needs to 
8bb0: 62 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65  be supported whe
8bc0: 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a  n SQLITE_TEST.**
8bd0: 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 20   is defined..** 
8be0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  <ul>.** <li>[[SQ
8bf0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f  LITE_FCNTL_SIZE_
8c00: 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  HINT]].** The [S
8c10: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45  QLITE_FCNTL_SIZE
8c20: 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73  _HINT] opcode is
8c30: 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 20   used by SQLite 
8c40: 74 6f 20 67 69 76 65 20 74 68 65 20 56 46 53 0a  to give the VFS.
8c50: 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74 20  ** layer a hint 
8c60: 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68 65  of how large the
8c70: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
8c80: 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20 64  ill grow to be d
8c90: 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72  uring the.** cur
8ca0: 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  rent transaction
8cb0: 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73 20  .  This hint is 
8cc0: 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20 74  not guaranteed t
8cd0: 6f 20 62 65 20 61 63 63 75 72 61 74 65 20 62 75  o be accurate bu
8ce0: 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e  t it.** is often
8cf0: 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e 64   close.  The und
8d00: 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67 68  erlying VFS migh
8d10: 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65 61  t choose to prea
8d20: 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73 65  llocate database
8d30: 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20 62  .** file space b
8d40: 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69 6e  ased on this hin
8d50: 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68 65  t in order to he
8d60: 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74 68 65  lp writes to the
8d70: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c   database.** fil
8d80: 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a  e run faster..**
8d90: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
8da0: 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a  _FCNTL_CHUNK_SIZ
8db0: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
8dc0: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
8dd0: 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  IZE] opcode is u
8de0: 73 65 64 20 74 6f 20 72 65 71 75 65 73 74 20 74  sed to request t
8df0: 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65  hat the VFS.** e
8e00: 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63  xtends and trunc
8e10: 61 74 65 73 20 74 68 65 20 64 61 74 61 62 61 73  ates the databas
8e20: 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73  e file in chunks
8e30: 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63 69   of a size speci
8e40: 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75  fied.** by the u
8e50: 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20  ser. The fourth 
8e60: 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
8e70: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
8e80: 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20  l()] should .** 
8e90: 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65  point to an inte
8ea0: 67 65 72 20 28 74 79 70 65 20 69 6e 74 29 20 63  ger (type int) c
8eb0: 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65  ontaining the ne
8ec0: 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20  w chunk-size to 
8ed0: 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e  use.** for the n
8ee0: 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61 73  ominated databas
8ef0: 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61  e. Allocating da
8f00: 74 61 62 61 73 65 20 66 69 6c 65 20 73 70 61 63  tabase file spac
8f10: 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68  e in large.** ch
8f20: 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74  unks (say 1MB at
8f30: 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65   a time), may re
8f40: 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d  duce file-system
8f50: 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61   fragmentation a
8f60: 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65  nd.** improve pe
8f70: 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d  rformance on som
8f80: 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a  e systems..**.**
8f90: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
8fa0: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52  NTL_FILE_POINTER
8fb0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
8fc0: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49  E_FCNTL_FILE_POI
8fd0: 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20  NTER] opcode is 
8fe0: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61  used to obtain a
8ff0: 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
9000: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
9010: 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61  ] object associa
9020: 74 65 64 20 77 69 74 68 20 61 20 70 61 72 74 69  ted with a parti
9030: 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a  cular database.*
9040: 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53  * connection.  S
9050: 65 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ee the [sqlite3_
9060: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
9070: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
9080: 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20  r.** additional 
9090: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
90a0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
90b0: 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54  FCNTL_SYNC_OMITT
90c0: 45 44 5d 5d 0a 2a 2a 20 5e 28 54 68 65 20 5b 53  ED]].** ^(The [S
90d0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
90e0: 5f 4f 4d 49 54 54 45 44 5d 20 6f 70 63 6f 64 65  _OMITTED] opcode
90f0: 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e   is generated in
9100: 74 65 72 6e 61 6c 6c 79 20 62 79 0a 2a 2a 20 53  ternally by.** S
9110: 51 4c 69 74 65 20 61 6e 64 20 73 65 6e 74 20 74  QLite and sent t
9120: 6f 20 61 6c 6c 20 56 46 53 65 73 20 69 6e 20 70  o all VFSes in p
9130: 6c 61 63 65 20 6f 66 20 61 20 63 61 6c 6c 20 74  lace of a call t
9140: 6f 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  o the xSync meth
9150: 6f 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 64  od.** when the d
9160: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
9170: 6f 6e 20 68 61 73 20 5b 50 52 41 47 4d 41 20 73  on has [PRAGMA s
9180: 79 6e 63 68 72 6f 6e 6f 75 73 5d 20 73 65 74 20  ynchronous] set 
9190: 74 6f 20 4f 46 46 2e 29 5e 0a 2a 2a 20 53 6f 6d  to OFF.)^.** Som
91a0: 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46  e specialized VF
91b0: 53 65 73 20 6e 65 65 64 20 74 68 69 73 20 73 69  Ses need this si
91c0: 67 6e 61 6c 20 69 6e 20 6f 72 64 65 72 20 74 6f  gnal in order to
91d0: 20 6f 70 65 72 61 74 65 20 63 6f 72 72 65 63 74   operate correct
91e0: 6c 79 0a 2a 2a 20 77 68 65 6e 20 5b 50 52 41 47  ly.** when [PRAG
91f0: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c  MA synchronous |
9200: 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e   PRAGMA synchron
9210: 6f 75 73 3d 4f 46 46 5d 20 69 73 20 73 65 74 2c  ous=OFF] is set,
9220: 20 62 75 74 20 6d 6f 73 74 20 0a 2a 2a 20 56 46   but most .** VF
9230: 53 65 73 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20  Ses do not need 
9240: 74 68 69 73 20 73 69 67 6e 61 6c 20 61 6e 64 20  this signal and 
9250: 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20  should silently 
9260: 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f  ignore this opco
9270: 64 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  de..** Applicati
9280: 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63  ons should not c
9290: 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  all [sqlite3_fil
92a0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74  e_control()] wit
92b0: 68 20 74 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65  h this.** opcode
92c0: 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79   as doing so may
92d0: 20 64 69 73 72 75 70 74 20 74 68 65 20 6f 70 65   disrupt the ope
92e0: 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70  ration of the sp
92f0: 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 0a  ecialized VFSes.
9300: 2a 2a 20 74 68 61 74 20 64 6f 20 72 65 71 75 69  ** that do requi
9310: 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c  re it.  .**.** <
9320: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
9330: 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59  L_WIN32_AV_RETRY
9340: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
9350: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41  TE_FCNTL_WIN32_A
9360: 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f 64 65 20  V_RETRY] opcode 
9370: 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69  is used to confi
9380: 67 75 72 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a  gure automatic.*
9390: 2a 20 72 65 74 72 79 20 63 6f 75 6e 74 73 20 61  * retry counts a
93a0: 6e 64 20 69 6e 74 65 72 76 61 6c 73 20 66 6f 72  nd intervals for
93b0: 20 63 65 72 74 61 69 6e 20 64 69 73 6b 20 49 2f   certain disk I/
93c0: 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f 72  O operations for
93d0: 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20   the.** windows 
93e0: 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74  [VFS] in order t
93f0: 6f 20 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74  o provide robust
9400: 6e 65 73 73 20 69 6e 20 74 68 65 20 70 72 65 73  ness in the pres
9410: 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d  ence of.** anti-
9420: 76 69 72 75 73 20 70 72 6f 67 72 61 6d 73 2e 20  virus programs. 
9430: 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65   By default, the
9440: 20 77 69 6e 64 6f 77 73 20 56 46 53 20 77 69 6c   windows VFS wil
9450: 6c 20 72 65 74 72 79 20 66 69 6c 65 20 72 65 61  l retry file rea
9460: 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74 65  d,.** file write
9470: 2c 20 61 6e 64 20 66 69 6c 65 20 64 65 6c 65 74  , and file delet
9480: 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 75 70 20  e operations up 
9490: 74 6f 20 31 30 20 74 69 6d 65 73 2c 20 77 69 74  to 10 times, wit
94a0: 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20  h a delay.** of 
94b0: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  25 milliseconds 
94c0: 62 65 66 6f 72 65 20 74 68 65 20 66 69 72 73 74  before the first
94d0: 20 72 65 74 72 79 20 61 6e 64 20 77 69 74 68 20   retry and with 
94e0: 74 68 65 20 64 65 6c 61 79 20 69 6e 63 72 65 61  the delay increa
94f0: 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64  sing.** by an ad
9500: 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c  ditional 25 mill
9510: 69 73 65 63 6f 6e 64 73 20 77 69 74 68 20 65 61  iseconds with ea
9520: 63 68 20 73 75 62 73 65 71 75 65 6e 74 20 72 65  ch subsequent re
9530: 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70  try.  This.** op
9540: 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68 65 73  code allows thes
9550: 65 20 74 77 6f 20 76 61 6c 75 65 73 20 28 31 30  e two values (10
9560: 20 72 65 74 72 69 65 73 20 61 6e 64 20 32 35 20   retries and 25 
9570: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
9580: 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20  delay).** to be 
9590: 61 64 6a 75 73 74 65 64 2e 20 20 54 68 65 20 76  adjusted.  The v
95a0: 61 6c 75 65 73 20 61 72 65 20 63 68 61 6e 67 65  alues are change
95b0: 64 20 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 61  d for all databa
95c0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a  se connections.*
95d0: 2a 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  * within the sam
95e0: 65 20 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20  e process.  The 
95f0: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
9600: 69 6e 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61  inter to an arra
9610: 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65  y of two.** inte
9620: 67 65 72 73 20 77 68 65 72 65 20 74 68 65 20 66  gers where the f
9630: 69 72 73 74 20 69 6e 74 65 67 65 72 20 69 20 74  irst integer i t
9640: 68 65 20 6e 65 77 20 72 65 74 72 79 20 63 6f 75  he new retry cou
9650: 6e 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  nt and the secon
9660: 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69 73 20  d.** integer is 
9670: 74 68 65 20 64 65 6c 61 79 2e 20 20 49 66 20 65  the delay.  If e
9680: 69 74 68 65 72 20 69 6e 74 65 67 65 72 20 69 73  ither integer is
9690: 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
96a0: 74 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69  the setting.** i
96b0: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 62 75  s not changed bu
96c0: 74 20 69 6e 73 74 65 61 64 20 74 68 65 20 70 72  t instead the pr
96d0: 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 61  ior value of tha
96e0: 74 20 73 65 74 74 69 6e 67 20 69 73 20 77 72 69  t setting is wri
96f0: 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65  tten.** into the
9700: 20 61 72 72 61 79 20 65 6e 74 72 79 2c 20 61 6c   array entry, al
9710: 6c 6f 77 69 6e 67 20 74 68 65 20 63 75 72 72 65  lowing the curre
9720: 6e 74 20 72 65 74 72 79 20 73 65 74 74 69 6e 67  nt retry setting
9730: 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72  s to be.** inter
9740: 72 6f 67 61 74 65 64 2e 20 20 54 68 65 20 7a 44  rogated.  The zD
9750: 62 4e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  bName parameter 
9760: 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a  is ignored..**.*
9770: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9780: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c  CNTL_PERSIST_WAL
9790: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
97a0: 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54  TE_FCNTL_PERSIST
97b0: 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20  _WAL] opcode is 
97c0: 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71  used to set or q
97d0: 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73  uery the.** pers
97e0: 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72  istent [WAL | Wr
97f0: 69 74 65 20 41 68 65 61 64 20 4c 6f 67 5d 20 73  ite Ahead Log] s
9800: 65 74 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61  etting.  By defa
9810: 75 6c 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61  ult, the auxilia
9820: 72 79 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61  ry.** write ahea
9830: 64 20 6c 6f 67 20 61 6e 64 20 73 68 61 72 65 64  d log and shared
9840: 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 75 73   memory files us
9850: 65 64 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69  ed for transacti
9860: 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72  on control.** ar
9870: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
9880: 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65  deleted when the
9890: 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69   latest connecti
98a0: 6f 6e 20 74 6f 20 74 68 65 20 64 61 74 61 62 61  on to the databa
98b0: 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53  se.** closes.  S
98c0: 65 74 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e  etting persisten
98d0: 74 20 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65  t WAL mode cause
98e0: 73 20 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f  s those files to
98f0: 20 70 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a   persist after.*
9900: 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73  * close.  Persis
9910: 74 69 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69  ting the files i
9920: 73 20 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74  s useful when ot
9930: 68 65 72 20 70 72 6f 63 65 73 73 65 73 20 74 68  her processes th
9940: 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76  at do not.** hav
9950: 65 20 77 72 69 74 65 20 70 65 72 6d 69 73 73 69  e write permissi
9960: 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74  on on the direct
9970: 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ory containing t
9980: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
9990: 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64   want.** to read
99a0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
99b0: 6c 65 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61  le, as the WAL a
99c0: 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79  nd shared memory
99d0: 20 66 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73   files must exis
99e0: 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f  t.** in order fo
99f0: 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74  r the database t
9a00: 6f 20 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20  o be readable.  
9a10: 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
9a20: 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  eter to.** [sqli
9a30: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
9a40: 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63  ()] for this opc
9a50: 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20  ode should be a 
9a60: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
9a70: 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69  teger..** That i
9a80: 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64  nteger is 0 to d
9a90: 69 73 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e  isable persisten
9aa0: 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20  t WAL mode or 1 
9ab0: 74 6f 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73  to enable persis
9ac0: 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65  tent.** WAL mode
9ad0: 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65  .  If the intege
9ae0: 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74  r is -1, then it
9af0: 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20   is overwritten 
9b00: 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
9b10: 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65  .** WAL persiste
9b20: 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a  nce setting..**.
9b30: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9b40: 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f  FCNTL_POWERSAFE_
9b50: 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e  OVERWRITE]].** ^
9b60: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
9b70: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  L_POWERSAFE_OVER
9b80: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  WRITE] opcode is
9b90: 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20   used to set or 
9ba0: 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72  query the.** per
9bb0: 73 69 73 74 65 6e 74 20 22 70 6f 77 65 72 73 61  sistent "powersa
9bc0: 66 65 2d 6f 76 65 72 77 72 69 74 65 22 20 6f 72  fe-overwrite" or
9bd0: 20 22 50 53 4f 57 22 20 73 65 74 74 69 6e 67 2e   "PSOW" setting.
9be0: 20 20 54 68 65 20 50 53 4f 57 20 73 65 74 74 69    The PSOW setti
9bf0: 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73  ng.** determines
9c00: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43   the [SQLITE_IOC
9c10: 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  AP_POWERSAFE_OVE
9c20: 52 57 52 49 54 45 5d 20 62 69 74 20 6f 66 20 74  RWRITE] bit of t
9c30: 68 65 0a 2a 2a 20 78 44 65 76 69 63 65 43 68 61  he.** xDeviceCha
9c40: 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74  racteristics met
9c50: 68 6f 64 73 2e 20 54 68 65 20 66 6f 75 72 74 68  hods. The fourth
9c60: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
9c70: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
9c80: 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68  ontrol()] for th
9c90: 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64  is opcode should
9ca0: 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   be a pointer to
9cb0: 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20   an integer..** 
9cc0: 54 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20  That integer is 
9cd0: 30 20 74 6f 20 64 69 73 61 62 6c 65 20 7a 65 72  0 to disable zer
9ce0: 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72  o-damage mode or
9cf0: 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72   1 to enable zer
9d00: 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65  o-damage.** mode
9d10: 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65  .  If the intege
9d20: 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74  r is -1, then it
9d30: 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20   is overwritten 
9d40: 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
9d50: 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20  .** zero-damage 
9d60: 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a  mode setting..**
9d70: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9d80: 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45  _FCNTL_OVERWRITE
9d90: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
9da0: 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49  TE_FCNTL_OVERWRI
9db0: 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6e  TE] opcode is in
9dc0: 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20  voked by SQLite 
9dd0: 61 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a  after opening.**
9de0: 20 61 20 77 72 69 74 65 20 74 72 61 6e 73 61 63   a write transac
9df0: 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74 65  tion to indicate
9e00: 20 74 68 61 74 2c 20 75 6e 6c 65 73 73 20 69 74   that, unless it
9e10: 20 69 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   is rolled back 
9e20: 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73  for some.** reas
9e30: 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72 65 20 64  on, the entire d
9e40: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c  atabase file wil
9e50: 6c 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e  l be overwritten
9e60: 20 62 79 20 74 68 65 20 63 75 72 72 65 6e 74 20   by the current 
9e70: 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e  .** transaction.
9e80: 20 54 68 69 73 20 69 73 20 75 73 65 64 20 62 79   This is used by
9e90: 20 56 41 43 55 55 4d 20 6f 70 65 72 61 74 69 6f   VACUUM operatio
9ea0: 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ns..**.** <li>[[
9eb0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
9ec0: 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  NAME]].** ^The [
9ed0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
9ee0: 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e  NAME] opcode can
9ef0: 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61   be used to obta
9f00: 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a  in the names of.
9f10: 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69  ** all [VFSes] i
9f20: 6e 20 74 68 65 20 56 46 53 20 73 74 61 63 6b 2e  n the VFS stack.
9f30: 20 20 54 68 65 20 6e 61 6d 65 73 20 61 72 65 20    The names are 
9f40: 6f 66 20 61 6c 6c 20 56 46 53 20 73 68 69 6d 73  of all VFS shims
9f50: 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61   and the.** fina
9f60: 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56  l bottom-level V
9f70: 46 53 20 61 72 65 20 77 72 69 74 74 65 6e 20 69  FS are written i
9f80: 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69  nto memory obtai
9f90: 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71  ned from .** [sq
9fa0: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
9fb0: 61 6e 64 20 74 68 65 20 72 65 73 75 6c 74 20 69  and the result i
9fc0: 73 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20  s stored in the 
9fd0: 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a  char* variable.*
9fe0: 2a 20 74 68 61 74 20 74 68 65 20 66 6f 75 72 74  * that the fourt
9ff0: 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 5b  h parameter of [
a000: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
a010: 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74  trol()] points t
a020: 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72  o..** The caller
a030: 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
a040: 66 6f 72 20 66 72 65 65 69 6e 67 20 74 68 65 20  for freeing the 
a050: 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65  memory when done
a060: 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c  .  As with.** al
a070: 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61  l file-control a
a080: 63 74 69 6f 6e 73 2c 20 74 68 65 72 65 20 69 73  ctions, there is
a090: 20 6e 6f 20 67 75 61 72 61 6e 74 65 65 20 74 68   no guarantee th
a0a0: 61 74 20 74 68 69 73 20 77 69 6c 6c 20 61 63 74  at this will act
a0b0: 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74  ually.** do anyt
a0c0: 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20 73  hing.  Callers s
a0d0: 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65  hould initialize
a0e0: 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61   the char* varia
a0f0: 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a  ble to a NULL.**
a100: 20 70 6f 69 6e 74 65 72 20 69 6e 20 63 61 73 65   pointer in case
a110: 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72   this file-contr
a120: 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d  ol is not implem
a130: 65 6e 74 65 64 2e 20 20 54 68 69 73 20 66 69 6c  ented.  This fil
a140: 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20  e-control.** is 
a150: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 64 69 61  intended for dia
a160: 67 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c 79  gnostic use only
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 50 52 41 47 4d  LITE_FCNTL_PRAGM
a190: 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72  A]].** ^Whenever
a1a0: 20 61 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74   a [PRAGMA] stat
a1b0: 65 6d 65 6e 74 20 69 73 20 70 61 72 73 65 64 2c  ement is parsed,
a1c0: 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54   an [SQLITE_FCNT
a1d0: 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69  L_PRAGMA] .** fi
a1e0: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65  le control is se
a1f0: 6e 74 20 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b  nt to the open [
a200: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
a210: 6a 65 63 74 20 63 6f 72 72 65 73 70 6f 6e 64 69  ject correspondi
a220: 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61 74  ng.** to the dat
a230: 61 62 61 73 65 20 66 69 6c 65 20 74 6f 20 77 68  abase file to wh
a240: 69 63 68 20 74 68 65 20 70 72 61 67 6d 61 20 73  ich the pragma s
a250: 74 61 74 65 6d 65 6e 74 20 72 65 66 65 72 73 2e  tatement refers.
a260: 20 5e 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a   ^The argument.*
a270: 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c 49 54 45  * to the [SQLITE
a280: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66  _FCNTL_PRAGMA] f
a290: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61  ile control is a
a2a0: 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f  n array of.** po
a2b0: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67  inters to string
a2c0: 73 20 28 63 68 61 72 2a 2a 29 20 69 6e 20 77 68  s (char**) in wh
a2d0: 69 63 68 20 74 68 65 20 73 65 63 6f 6e 64 20 65  ich the second e
a2e0: 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 72  lement of the ar
a2f0: 72 61 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61  ray.** is the na
a300: 6d 65 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61  me of the pragma
a310: 20 61 6e 64 20 74 68 65 20 74 68 69 72 64 20 65   and the third e
a320: 6c 65 6d 65 6e 74 20 69 73 20 74 68 65 20 61 72  lement is the ar
a330: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a  gument to the.**
a340: 20 70 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20   pragma or NULL 
a350: 69 66 20 74 68 65 20 70 72 61 67 6d 61 20 68 61  if the pragma ha
a360: 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20  s no argument.  
a370: 5e 54 68 65 20 68 61 6e 64 6c 65 72 20 66 6f 72  ^The handler for
a380: 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46   an.** [SQLITE_F
a390: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c  CNTL_PRAGMA] fil
a3a0: 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70  e control can op
a3b0: 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68  tionally make th
a3c0: 65 20 66 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a  e first element.
a3d0: 2a 2a 20 6f 66 20 74 68 65 20 63 68 61 72 2a 2a  ** of the char**
a3e0: 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20   argument point 
a3f0: 74 6f 20 61 20 73 74 72 69 6e 67 20 6f 62 74 61  to a string obta
a400: 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
a410: 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a  e3_mprintf()].**
a420: 20 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c 65   or the equivale
a430: 6e 74 20 61 6e 64 20 74 68 61 74 20 73 74 72 69  nt and that stri
a440: 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74  ng will become t
a450: 68 65 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65  he result of the
a460: 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68   pragma or.** th
a470: 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
a480: 69 66 20 74 68 65 20 70 72 61 67 6d 61 20 66 61  if the pragma fa
a490: 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20  ils. ^If the.** 
a4a0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
a4b0: 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72  AGMA] file contr
a4c0: 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ol returns [SQLI
a4d0: 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68  TE_NOTFOUND], th
a4e0: 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50  en normal .** [P
a4f0: 52 41 47 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e  RAGMA] processin
a500: 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49  g continues.  ^I
a510: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  f the [SQLITE_FC
a520: 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66  NTL_PRAGMA].** f
a530: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75  ile control retu
a540: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  rns [SQLITE_OK],
a550: 20 74 68 65 6e 20 74 68 65 20 70 61 72 73 65 72   then the parser
a560: 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
a570: 65 0a 2a 2a 20 56 46 53 20 68 61 73 20 68 61 6e  e.** VFS has han
a580: 64 6c 65 64 20 74 68 65 20 50 52 41 47 4d 41 20  dled the PRAGMA 
a590: 69 74 73 65 6c 66 20 61 6e 64 20 74 68 65 20 70  itself and the p
a5a0: 61 72 73 65 72 20 67 65 6e 65 72 61 74 65 73 20  arser generates 
a5b0: 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61  a no-op.** prepa
a5c0: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  red statement.  
a5d0: 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ^If the [SQLITE_
a5e0: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69  FCNTL_PRAGMA] fi
a5f0: 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72  le control retur
a600: 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74  ns.** any result
a610: 20 63 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e   code other than
a620: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20   [SQLITE_OK] or 
a630: 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44  [SQLITE_NOTFOUND
a640: 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a  ], that means.**
a650: 20 74 68 61 74 20 74 68 65 20 56 46 53 20 65 6e   that the VFS en
a660: 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72  countered an err
a670: 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e  or while handlin
a680: 67 20 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61  g the [PRAGMA] a
a690: 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c  nd the.** compil
a6a0: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41  ation of the PRA
a6b0: 47 4d 41 20 66 61 69 6c 73 20 77 69 74 68 20 61  GMA fails with a
a6c0: 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b  n error.  ^The [
a6d0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
a6e0: 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e  GMA].** file con
a6f0: 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74  trol occurs at t
a700: 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
a710: 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74  pragma statement
a720: 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f   analysis and so
a730: 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74  .** it is able t
a740: 6f 20 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74  o override built
a750: 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61  -in [PRAGMA] sta
a760: 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c  tements..**.** <
a770: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
a780: 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a  L_BUSYHANDLER]].
a790: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
a7a0: 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45  FCNTL_BUSYHANDLE
a7b0: 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72  R].** file-contr
a7c0: 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65  ol may be invoke
a7d0: 64 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 74  d by SQLite on t
a7e0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
a7f0: 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74   handle.** short
a800: 6c 79 20 61 66 74 65 72 20 69 74 20 69 73 20 6f  ly after it is o
a810: 70 65 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74  pened in order t
a820: 6f 20 70 72 6f 76 69 64 65 20 61 20 63 75 73 74  o provide a cust
a830: 6f 6d 20 56 46 53 20 77 69 74 68 20 61 63 63 65  om VFS with acce
a840: 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e  ss.** to the con
a850: 6e 65 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 61  nections busy-ha
a860: 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20  ndler callback. 
a870: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
a880: 6f 66 20 74 79 70 65 20 28 76 6f 69 64 20 2a 2a  of type (void **
a890: 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 20  ).** - an array 
a8a0: 6f 66 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 20  of two (void *) 
a8b0: 76 61 6c 75 65 73 2e 20 54 68 65 20 66 69 72 73  values. The firs
a8c0: 74 20 28 76 6f 69 64 20 2a 29 20 61 63 74 75 61  t (void *) actua
a8d0: 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f  lly points.** to
a8e0: 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74   a function of t
a8f0: 79 70 65 20 28 69 6e 74 20 28 2a 29 28 76 6f 69  ype (int (*)(voi
a900: 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 20  d *)). In order 
a910: 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f  to invoke the co
a920: 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73  nnections.** bus
a930: 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 20  y-handler, this 
a940: 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20  function should 
a950: 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  be invoked with 
a960: 74 68 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 64  the second (void
a970: 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72   *) in.** the ar
a980: 72 61 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 20  ray as the only 
a990: 61 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20  argument. If it 
a9a0: 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
a9b0: 2c 20 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61  , then the opera
a9c0: 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62  tion.** should b
a9d0: 65 20 72 65 74 72 69 65 64 2e 20 49 66 20 69 74  e retried. If it
a9e0: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74   returns zero, t
a9f0: 68 65 20 63 75 73 74 6f 6d 20 56 46 53 20 73 68  he custom VFS sh
aa00: 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 65  ould abandon the
aa10: 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 72  .** current oper
aa20: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ation..**.** <li
aa30: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
aa40: 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a  TEMPFILENAME]].*
aa50: 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20 63  * ^Application c
aa60: 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b 53  an invoke the [S
aa70: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50  QLITE_FCNTL_TEMP
aa80: 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d 63  FILENAME] file-c
aa90: 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76  ontrol.** to hav
aaa0: 65 20 53 51 4c 69 74 65 20 67 65 6e 65 72 61 74  e SQLite generat
aab0: 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79  e a.** temporary
aac0: 20 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20   filename using 
aad0: 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74  the same algorit
aae0: 68 6d 20 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f  hm that is follo
aaf0: 77 65 64 20 74 6f 20 67 65 6e 65 72 61 74 65 0a  wed to generate.
ab00: 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ** temporary fil
ab10: 65 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d 50 20  enames for TEMP 
ab20: 74 61 62 6c 65 73 20 61 6e 64 20 6f 74 68 65 72  tables and other
ab30: 20 69 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e 20   internal uses. 
ab40: 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74   The.** argument
ab50: 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63 68 61   should be a cha
ab60: 72 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62  r** which will b
ab70: 65 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  e filled with th
ab80: 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72  e filename.** wr
ab90: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72  itten into memor
aba0: 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
abb0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
abc0: 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65 72 20  )].  The caller 
abd0: 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65  should.** invoke
abe0: 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
abf0: 5d 20 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 20  ] on the result 
ac00: 74 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72  to avoid a memor
ac10: 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  y leak..**.** <l
ac20: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
ac30: 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20  _MMAP_SIZE]].** 
ac40: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
ac50: 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c  L_MMAP_SIZE] fil
ac60: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65  e control is use
ac70: 64 20 74 6f 20 71 75 65 72 79 20 6f 72 20 73 65  d to query or se
ac80: 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d  t the.** maximum
ac90: 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
aca0: 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20 75 73   that will be us
acb0: 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61  ed for memory-ma
acc0: 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65  pped I/O..** The
acd0: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
ace0: 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 75  ointer to a valu
acf0: 65 20 6f 66 20 74 79 70 65 20 73 71 6c 69 74 65  e of type sqlite
ad00: 33 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20  3_int64 that.** 
ad10: 69 73 20 61 6e 20 61 64 76 69 73 6f 72 79 20 6d  is an advisory m
ad20: 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
ad30: 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69   bytes in the fi
ad40: 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70  le to memory map
ad50: 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65  .  The.** pointe
ad60: 72 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e  r is overwritten
ad70: 20 77 69 74 68 20 74 68 65 20 6f 6c 64 20 76 61   with the old va
ad80: 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d 69 74 20  lue.  The limit 
ad90: 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 69  is not changed i
ada0: 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f  f.** the value o
adb0: 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 65  riginally pointe
adc0: 64 20 74 6f 20 69 73 20 6e 65 67 61 74 69 76 65  d to is negative
add0: 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 63 75 72  , and so the cur
ade0: 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 63  rent limit .** c
adf0: 61 6e 20 62 65 20 71 75 65 72 69 65 64 20 62 79  an be queried by
ae00: 20 70 61 73 73 69 6e 67 20 69 6e 20 61 20 70 6f   passing in a po
ae10: 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 67 61 74  inter to a negat
ae20: 69 76 65 20 6e 75 6d 62 65 72 2e 20 20 54 68 69  ive number.  Thi
ae30: 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  s.** file-contro
ae40: 6c 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e  l is used intern
ae50: 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  ally to implemen
ae60: 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73  t [PRAGMA mmap_s
ae70: 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 2f 75 6c  ize]..**.** </ul
ae80: 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
ae90: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54  ITE_FCNTL_LOCKST
aea0: 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ATE             
aeb0: 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
aec0: 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TE_GET_LOCKPROXY
aed0: 46 49 4c 45 20 20 20 20 20 20 20 20 20 20 20 20  FILE            
aee0: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
aef0: 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  E_SET_LOCKPROXYF
af00: 49 4c 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ILE             
af10: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
af20: 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20  _LAST_ERRNO     
af30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 34                 4
af40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
af50: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20  FCNTL_SIZE_HINT 
af60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a                5.
af70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
af80: 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20  CNTL_CHUNK_SIZE 
af90: 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23               6.#
afa0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
afb0: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52  NTL_FILE_POINTER
afc0: 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64              7.#d
afd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
afe0: 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20  TL_SYNC_OMITTED 
aff0: 20 20 20 20 20 20 20 20 20 20 20 38 0a 23 64 65             8.#de
b000: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
b010: 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59  L_WIN32_AV_RETRY
b020: 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66            9.#def
b030: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
b040: 5f 50 45 52 53 49 53 54 5f 57 41 4c 20 20 20 20  _PERSIST_WAL    
b050: 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 66 69          10.#defi
b060: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
b070: 4f 56 45 52 57 52 49 54 45 20 20 20 20 20 20 20  OVERWRITE       
b080: 20 20 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e         11.#defin
b090: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56  e SQLITE_FCNTL_V
b0a0: 46 53 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20  FSNAME          
b0b0: 20 20 20 20 20 20 31 32 0a 23 64 65 66 69 6e 65        12.#define
b0c0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f   SQLITE_FCNTL_PO
b0d0: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
b0e0: 45 20 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20  E    13.#define 
b0f0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
b100: 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20  GMA             
b110: 20 20 20 20 31 34 0a 23 64 65 66 69 6e 65 20 53      14.#define S
b120: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59  QLITE_FCNTL_BUSY
b130: 48 41 4e 44 4c 45 52 20 20 20 20 20 20 20 20 20  HANDLER         
b140: 20 20 20 31 35 0a 23 64 65 66 69 6e 65 20 53 51     15.#define SQ
b150: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46  LITE_FCNTL_TEMPF
b160: 49 4c 45 4e 41 4d 45 20 20 20 20 20 20 20 20 20  ILENAME         
b170: 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c    16.#define SQL
b180: 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53  ITE_FCNTL_MMAP_S
b190: 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  IZE             
b1a0: 20 31 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   18../*.** CAPI3
b1b0: 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c  REF: Mutex Handl
b1c0: 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65  e.**.** The mute
b1d0: 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20  x module within 
b1e0: 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b  SQLite defines [
b1f0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74  sqlite3_mutex] t
b200: 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72  o be an.** abstr
b210: 61 63 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d  act type for a m
b220: 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68  utex object.  Th
b230: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65  e SQLite core ne
b240: 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20  ver looks.** at 
b250: 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70  the internal rep
b260: 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61  resentation of a
b270: 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  n [sqlite3_mutex
b280: 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64  ].  It only.** d
b290: 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65  eals with pointe
b2a0: 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  rs to the [sqlit
b2b0: 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74  e3_mutex] object
b2c0: 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20  ..**.** Mutexes 
b2d0: 61 72 65 20 63 72 65 61 74 65 64 20 75 73 69 6e  are created usin
b2e0: 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
b2f0: 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79  _alloc()]..*/.ty
b300: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
b310: 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74  ite3_mutex sqlit
b320: 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a  e3_mutex;../*.**
b330: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
b340: 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a  terface Object.*
b350: 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
b360: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
b370: 76 66 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e  vfs object defin
b380: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
b390: 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20   between.** the 
b3a0: 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20  SQLite core and 
b3b0: 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f  the underlying o
b3c0: 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e  perating system.
b3d0: 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69    The "vfs".** i
b3e0: 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
b3f0: 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20  e object stands 
b400: 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c  for "virtual fil
b410: 65 20 73 79 73 74 65 6d 22 2e 20 20 53 65 65 0a  e system".  See.
b420: 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c 20 56 46  ** the [VFS | VF
b430: 53 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d  S documentation]
b440: 20 66 6f 72 20 66 75 72 74 68 65 72 20 69 6e 66   for further inf
b450: 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
b460: 54 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  The value of the
b470: 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20   iVersion field 
b480: 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62  is initially 1 b
b490: 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72  ut may be larger
b4a0: 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76 65   in.** future ve
b4b0: 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
b4c0: 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69  .  Additional fi
b4d0: 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65  elds may be appe
b4e0: 6e 64 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20  nded to this.** 
b4f0: 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 68 65 20  object when the 
b500: 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 69  iVersion value i
b510: 73 20 69 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f  s increased.  No
b520: 74 65 20 74 68 61 74 20 74 68 65 20 73 74 72 75  te that the stru
b530: 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20  cture.** of the 
b540: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
b550: 63 74 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  ct changes in th
b560: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65  e transaction be
b570: 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20  tween.** SQLite 
b580: 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e  version 3.5.9 an
b590: 64 20 33 2e 36 2e 30 20 61 6e 64 20 79 65 74 20  d 3.6.0 and yet 
b5a0: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65  the iVersion fie
b5b0: 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f  ld was not.** mo
b5c0: 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  dified..**.** Th
b5d0: 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64  e szOsFile field
b5e0: 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20   is the size of 
b5f0: 74 68 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b  the subclassed [
b600: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a  sqlite3_file].**
b610: 20 73 74 72 75 63 74 75 72 65 20 75 73 65 64 20   structure used 
b620: 62 79 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78  by this VFS.  mx
b630: 50 61 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20  Pathname is the 
b640: 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
b650: 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20  f.** a pathname 
b660: 69 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a  in this VFS..**.
b670: 2a 2a 20 52 65 67 69 73 74 65 72 65 64 20 73 71  ** Registered sq
b680: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74  lite3_vfs object
b690: 73 20 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20  s are kept on a 
b6a0: 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d  linked list form
b6b0: 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65  ed by.** the pNe
b6c0: 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65  xt pointer.  The
b6d0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65   [sqlite3_vfs_re
b6e0: 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64  gister()].** and
b6f0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e   [sqlite3_vfs_un
b700: 72 65 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65  register()] inte
b710: 72 66 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68  rfaces manage th
b720: 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20  is list.** in a 
b730: 74 68 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e  thread-safe way.
b740: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76    The [sqlite3_v
b750: 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72  fs_find()] inter
b760: 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73  face.** searches
b770: 20 74 68 65 20 6c 69 73 74 2e 20 20 4e 65 69 74   the list.  Neit
b780: 68 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  her the applicat
b790: 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68 65  ion code nor the
b7a0: 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   VFS.** implemen
b7b0: 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73  tation should us
b7c0: 65 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e  e the pNext poin
b7d0: 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  ter..**.** The p
b7e0: 4e 65 78 74 20 66 69 65 6c 64 20 69 73 20 74 68  Next field is th
b7f0: 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20  e only field in 
b800: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a  the sqlite3_vfs.
b810: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 74 68 61  ** structure tha
b820: 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76  t SQLite will ev
b830: 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69  er modify.  SQLi
b840: 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63  te will only acc
b850: 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79  ess.** or modify
b860: 20 74 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c   this field whil
b870: 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74  e holding a part
b880: 69 63 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75  icular static mu
b890: 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  tex..** The appl
b8a0: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e  ication should n
b8b0: 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74  ever modify anyt
b8c0: 68 69 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20  hing within the 
b8d0: 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f  sqlite3_vfs.** o
b8e0: 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f  bject once the o
b8f0: 62 6a 65 63 74 20 68 61 73 20 62 65 65 6e 20 72  bject has been r
b900: 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a  egistered..**.**
b910: 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64   The zName field
b920: 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20   holds the name 
b930: 6f 66 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c  of the VFS modul
b940: 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73  e.  The name mus
b950: 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61  t.** be unique a
b960: 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f  cross all VFS mo
b970: 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73  dules..**.** [[s
b980: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
b990: 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75  ]].** ^SQLite gu
b9a0: 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
b9b0: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
b9c0: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a  meter to xOpen.*
b9d0: 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55  * is either a NU
b9e0: 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74  LL pointer or st
b9f0: 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  ring obtained.**
ba00: 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e   from xFullPathn
ba10: 61 6d 65 28 29 20 77 69 74 68 20 61 6e 20 6f 70  ame() with an op
ba20: 74 69 6f 6e 61 6c 20 73 75 66 66 69 78 20 61 64  tional suffix ad
ba30: 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75  ded..** ^If a su
ba40: 66 66 69 78 20 69 73 20 61 64 64 65 64 20 74 6f  ffix is added to
ba50: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
ba60: 61 72 61 6d 65 74 65 72 2c 20 69 74 20 77 69 6c  arameter, it wil
ba70: 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20  l.** consist of 
ba80: 61 20 73 69 6e 67 6c 65 20 22 2d 22 20 63 68 61  a single "-" cha
ba90: 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20  racter followed 
baa0: 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a  by no more than.
bab0: 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75 6d 65 72  ** 11 alphanumer
bac0: 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68  ic and/or "-" ch
bad0: 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51  aracters..** ^SQ
bae0: 4c 69 74 65 20 66 75 72 74 68 65 72 20 67 75 61  Lite further gua
baf0: 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20  rantees that.** 
bb00: 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20  the string will 
bb10: 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63  be valid and unc
bb20: 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c  hanged until xCl
bb30: 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c  ose() is.** call
bb40: 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74  ed. Because of t
bb50: 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74  he previous sent
bb60: 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71  ence,.** the [sq
bb70: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20  lite3_file] can 
bb80: 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70  safely store a p
bb90: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
bba0: 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20   filename if it 
bbb0: 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65  needs to remembe
bbc0: 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66  r the filename f
bbd0: 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a  or some reason..
bbe0: 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e  ** If the zFilen
bbf0: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ame parameter to
bc00: 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c   xOpen is a NULL
bc10: 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f   pointer then xO
bc20: 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65  pen.** must inve
bc30: 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f  nt its own tempo
bc40: 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68  rary name for th
bc50: 65 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76  e file.  ^Whenev
bc60: 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65  er the .** xFile
bc70: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69  name parameter i
bc80: 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61  s NULL it will a
bc90: 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73 65 20  lso be the case 
bca0: 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67  that the.** flag
bcb0: 73 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c  s parameter will
bcc0: 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45   include [SQLITE
bcd0: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
bce0: 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  OSE]..**.** The 
bcf0: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
bd00: 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64  o xOpen() includ
bd10: 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20  es all bits set 
bd20: 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20  in.** the flags 
bd30: 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
bd40: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e  ite3_open_v2()].
bd50: 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33    Or if [sqlite3
bd60: 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b  _open()].** or [
bd70: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
bd80: 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20  ] is used, then 
bd90: 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61  flags includes a
bda0: 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49  t least.** [SQLI
bdb0: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
bdc0: 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  E] | [SQLITE_OPE
bdd0: 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49  N_CREATE]. .** I
bde0: 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20  f xOpen() opens 
bdf0: 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79  a file read-only
be00: 20 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70   then it sets *p
be10: 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69  OutFlags to.** i
be20: 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f  nclude [SQLITE_O
be30: 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20  PEN_READONLY].  
be40: 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70  Other bits in *p
be50: 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20  OutFlags may be 
be60: 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c  set..**.** ^(SQL
be70: 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64  ite will also ad
be80: 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  d one of the fol
be90: 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20  lowing flags to 
bea0: 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63  the xOpen().** c
beb0: 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f  all, depending o
bec0: 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69  n the object bei
bed0: 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a  ng opened:.**.**
bee0: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b   <ul>.** <li>  [
bef0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
bf00: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
bf10: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
bf20: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
bf30: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
bf40: 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  EMP_DB].** <li> 
bf50: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45   [SQLITE_OPEN_TE
bf60: 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  MP_JOURNAL].** <
bf70: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
bf80: 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a  N_TRANSIENT_DB].
bf90: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
bfa0: 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c  _OPEN_SUBJOURNAL
bfb0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
bfc0: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a  TE_OPEN_MASTER_J
bfd0: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
bfe0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41   [SQLITE_OPEN_WA
bff0: 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  L].** </ul>)^.**
c000: 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f  .** The file I/O
c010: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
c020: 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65  can use the obje
c030: 63 74 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f  ct type flags to
c040: 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77  .** change the w
c050: 61 79 20 69 74 20 64 65 61 6c 73 20 77 69 74 68  ay it deals with
c060: 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61   files.  For exa
c070: 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61  mple, an applica
c080: 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65  tion.** that doe
c090: 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74  s not care about
c0a0: 20 63 72 61 73 68 20 72 65 63 6f 76 65 72 79 20   crash recovery 
c0b0: 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68  or rollback migh
c0c0: 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70  t make.** the op
c0d0: 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20  en of a journal 
c0e0: 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57  file a no-op.  W
c0f0: 72 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f  rites to this jo
c100: 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61  urnal would.** a
c110: 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61  lso be no-ops, a
c120: 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74  nd any attempt t
c130: 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e  o read the journ
c140: 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a  al would return.
c150: 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e  ** SQLITE_IOERR.
c160: 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65    Or the impleme
c170: 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65  ntation might re
c180: 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64  cognize that a d
c190: 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20  atabase.** file 
c1a0: 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61  will be doing pa
c1b0: 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f  ge-aligned secto
c1c0: 72 20 72 65 61 64 73 20 61 6e 64 20 77 72 69 74  r reads and writ
c1d0: 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a  es in a random.*
c1e0: 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20  * order and set 
c1f0: 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79  up its I/O subsy
c200: 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79  stem accordingly
c210: 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  ..**.** SQLite m
c220: 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e  ight also add on
c230: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
c240: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20  ng flags to the 
c250: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a  xOpen method:.**
c260: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
c270: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
c280: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20  LETEONCLOSE].** 
c290: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45  <li> [SQLITE_OPE
c2a0: 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20  N_EXCLUSIVE].** 
c2b0: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
c2c0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
c2d0: 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67  ETEONCLOSE] flag
c2e0: 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20   means the file 
c2f0: 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c  should be.** del
c300: 65 74 65 64 20 77 68 65 6e 20 69 74 20 69 73 20  eted when it is 
c310: 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b 53  closed.  ^The [S
c320: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
c330: 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c  EONCLOSE].** wil
c340: 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d  l be set for TEM
c350: 50 20 64 61 74 61 62 61 73 65 73 20 61 6e 64 20  P databases and 
c360: 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20  their journals, 
c370: 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74  transient.** dat
c380: 61 62 61 73 65 73 2c 20 61 6e 64 20 73 75 62 6a  abases, and subj
c390: 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e  ournals..**.** ^
c3a0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
c3b0: 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67  _EXCLUSIVE] flag
c3c0: 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20   is always used 
c3d0: 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a  in conjunction.*
c3e0: 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49  * with the [SQLI
c3f0: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20  TE_OPEN_CREATE] 
c400: 66 6c 61 67 2c 20 77 68 69 63 68 20 61 72 65 20  flag, which are 
c410: 62 6f 74 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a  both directly.**
c420: 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68   analogous to th
c430: 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43  e O_EXCL and O_C
c440: 52 45 41 54 20 66 6c 61 67 73 20 6f 66 20 74 68  REAT flags of th
c450: 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a  e POSIX open().*
c460: 2a 20 41 50 49 2e 20 20 54 68 65 20 53 51 4c 49  * API.  The SQLI
c470: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
c480: 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 69  E flag, when pai
c490: 72 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a  red with the .**
c4a0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
c4b0: 41 54 45 2c 20 69 73 20 75 73 65 64 20 74 6f 20  ATE, is used to 
c4c0: 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 66 69  indicate that fi
c4d0: 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73  le should always
c4e0: 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 64 2c 20  .** be created, 
c4f0: 61 6e 64 20 74 68 61 74 20 69 74 20 69 73 20 61  and that it is a
c500: 6e 20 65 72 72 6f 72 20 69 66 20 69 74 20 61 6c  n error if it al
c510: 72 65 61 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a  ready exists..**
c520: 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69   It is <i>not</i
c530: 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61  > used to indica
c540: 74 65 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75  te the file shou
c550: 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a  ld be opened .**
c560: 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61   for exclusive a
c570: 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74  ccess..**.** ^At
c580: 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20   least szOsFile 
c590: 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20  bytes of memory 
c5a0: 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  are allocated by
c5b0: 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f   SQLite.** to ho
c5c0: 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33  ld the  [sqlite3
c5d0: 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65  _file] structure
c5e0: 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74   passed as the t
c5f0: 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  hird.** argument
c600: 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20   to xOpen.  The 
c610: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65  xOpen method doe
c620: 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a  s not have to.**
c630: 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74   allocate the st
c640: 72 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75  ructure; it shou
c650: 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20  ld just fill it 
c660: 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a  in.  Note that.*
c670: 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68  * the xOpen meth
c680: 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68 65 20  od must set the 
c690: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
c6a0: 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65 72 0a  thods to either.
c6b0: 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71 6c 69  ** a valid [sqli
c6c0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
c6d0: 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c  object or to NUL
c6e0: 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74 20 64  L.  xOpen must d
c6f0: 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e 20 69  o.** this even i
c700: 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69 6c 73  f the open fails
c710: 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65 63 74  .  SQLite expect
c720: 73 20 74 68 61 74 20 74 68 65 20 73 71 6c 69 74  s that the sqlit
c730: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
c740: 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c  .** element will
c750: 20 62 65 20 76 61 6c 69 64 20 61 66 74 65 72 20   be valid after 
c760: 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20 72 65  xOpen returns re
c770: 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20  gardless of the 
c780: 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61  success.** or fa
c790: 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78 4f 70  ilure of the xOp
c7a0: 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b  en call..**.** [
c7b0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 41 63  [sqlite3_vfs.xAc
c7c0: 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66  cess]].** ^The f
c7d0: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
c7e0: 20 78 41 63 63 65 73 73 28 29 20 6d 61 79 20 62   xAccess() may b
c7f0: 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  e [SQLITE_ACCESS
c800: 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74  _EXISTS].** to t
c810: 65 73 74 20 66 6f 72 20 74 68 65 20 65 78 69 73  est for the exis
c820: 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c  tence of a file,
c830: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45   or [SQLITE_ACCE
c840: 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f  SS_READWRITE] to
c850: 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68 65 72  .** test whether
c860: 20 61 20 66 69 6c 65 20 69 73 20 72 65 61 64 61   a file is reada
c870: 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65  ble and writable
c880: 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43  , or [SQLITE_ACC
c890: 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20  ESS_READ].** to 
c8a0: 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66  test whether a f
c8b0: 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74 20  ile is at least 
c8c0: 72 65 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20  readable.   The 
c8d0: 66 69 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a  file can be a.**
c8e0: 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a   directory..**.*
c8f0: 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 61  * ^SQLite will a
c900: 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61  lways allocate a
c910: 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61  t least mxPathna
c920: 6d 65 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74  me+1 bytes for t
c930: 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66  he.** output buf
c940: 66 65 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d  fer xFullPathnam
c950: 65 2e 20 20 54 68 65 20 65 78 61 63 74 20 73 69  e.  The exact si
c960: 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74  ze of the output
c970: 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c   buffer.** is al
c980: 73 6f 20 70 61 73 73 65 64 20 61 73 20 61 20 70  so passed as a p
c990: 61 72 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68  arameter to both
c9a0: 20 20 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68    methods. If th
c9b0: 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a  e output buffer.
c9c0: 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20  ** is not large 
c9d0: 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f  enough, [SQLITE_
c9e0: 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64  CANTOPEN] should
c9f0: 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69   be returned. Si
ca00: 6e 63 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68  nce this is.** h
ca10: 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61 74 61  andled as a fata
ca20: 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74  l error by SQLit
ca30: 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74  e, vfs implement
ca40: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e  ations should en
ca50: 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65  deavor.** to pre
ca60: 76 65 6e 74 20 74 68 69 73 20 62 79 20 73 65 74  vent this by set
ca70: 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20  ting mxPathname 
ca80: 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c  to a sufficientl
ca90: 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a  y large value..*
caa0: 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d  *.** The xRandom
cab0: 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29  ness(), xSleep()
cac0: 2c 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29  , xCurrentTime()
cad0: 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69  , and xCurrentTi
cae0: 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74  meInt64().** int
caf0: 65 72 66 61 63 65 73 20 61 72 65 20 6e 6f 74 20  erfaces are not 
cb00: 73 74 72 69 63 74 6c 79 20 61 20 70 61 72 74 20  strictly a part 
cb10: 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73 74 65  of the filesyste
cb20: 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72 65 0a  m, but they are.
cb30: 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74  ** included in t
cb40: 68 65 20 56 46 53 20 73 74 72 75 63 74 75 72 65  he VFS structure
cb50: 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73   for completenes
cb60: 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f  s..** The xRando
cb70: 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e  mness() function
cb80: 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74   attempts to ret
cb90: 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73  urn nBytes bytes
cba0: 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c  .** of good-qual
cbb0: 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69  ity randomness i
cbc0: 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72  nto zOut.  The r
cbd0: 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a  eturn value is.*
cbe0: 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d  * the actual num
cbf0: 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20  ber of bytes of 
cc00: 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69  randomness obtai
cc10: 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65  ned..** The xSle
cc20: 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73  ep() method caus
cc30: 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74  es the calling t
cc40: 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66  hread to sleep f
cc50: 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74  or at.** least t
cc60: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63  he number of mic
cc70: 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e  roseconds given.
cc80: 20 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54    ^The xCurrentT
cc90: 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20  ime().** method 
cca0: 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e  returns a Julian
ccb0: 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20   Day Number for 
ccc0: 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 65  the current date
ccd0: 20 61 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20   and time as.** 
cce0: 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  a floating point
ccf0: 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20   value..** ^The 
cd00: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
cd10: 34 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72  4() method retur
cd20: 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74 65 67 65  ns, as an intege
cd30: 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a  r, the Julian.**
cd40: 20 44 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74   Day Number mult
cd50: 69 70 6c 69 65 64 20 62 79 20 38 36 34 30 30 30  iplied by 864000
cd60: 30 30 20 28 74 68 65 20 6e 75 6d 62 65 72 20 6f  00 (the number o
cd70: 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69  f milliseconds i
cd80: 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20  n .** a 24-hour 
cd90: 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69  day).  .** ^SQLi
cda0: 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20  te will use the 
cdb0: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
cdc0: 34 28 29 20 6d 65 74 68 6f 64 20 74 6f 20 67 65  4() method to ge
cdd0: 74 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  t the current.**
cde0: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 69   date and time i
cdf0: 66 20 74 68 61 74 20 6d 65 74 68 6f 64 20 69 73  f that method is
ce00: 20 61 76 61 69 6c 61 62 6c 65 20 28 69 66 20 69   available (if i
ce10: 56 65 72 73 69 6f 6e 20 69 73 20 32 20 6f 72 20  Version is 2 or 
ce20: 0a 2a 2a 20 67 72 65 61 74 65 72 20 61 6e 64 20  .** greater and 
ce30: 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69  the function poi
ce40: 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  nter is not NULL
ce50: 29 20 61 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20  ) and will fall 
ce60: 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72  back.** to xCurr
ce70: 65 6e 74 54 69 6d 65 28 29 20 69 66 20 78 43 75  entTime() if xCu
ce80: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
ce90: 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e   is unavailable.
cea0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74  .**.** ^The xSet
ceb0: 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47  SystemCall(), xG
cec0: 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20  etSystemCall(), 
ced0: 61 6e 64 20 78 4e 65 73 74 53 79 73 74 65 6d 43  and xNestSystemC
cee0: 61 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 73  all() interfaces
cef0: 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75 73 65 64  .** are not used
cf00: 20 62 79 20 74 68 65 20 53 51 4c 69 74 65 20 63   by the SQLite c
cf10: 6f 72 65 2e 20 20 54 68 65 73 65 20 6f 70 74 69  ore.  These opti
cf20: 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20  onal interfaces 
cf30: 61 72 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20  are provided.** 
cf40: 62 79 20 73 6f 6d 65 20 56 46 53 65 73 20 74 6f  by some VFSes to
cf50: 20 66 61 63 69 6c 69 74 61 74 65 20 74 65 73 74   facilitate test
cf60: 69 6e 67 20 6f 66 20 74 68 65 20 56 46 53 20 63  ing of the VFS c
cf70: 6f 64 65 2e 20 42 79 20 6f 76 65 72 72 69 64 69  ode. By overridi
cf80: 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61  ng .** system ca
cf90: 6c 6c 73 20 77 69 74 68 20 66 75 6e 63 74 69 6f  lls with functio
cfa0: 6e 73 20 75 6e 64 65 72 20 69 74 73 20 63 6f 6e  ns under its con
cfb0: 74 72 6f 6c 2c 20 61 20 74 65 73 74 20 70 72 6f  trol, a test pro
cfc0: 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75  gram can.** simu
cfd0: 6c 61 74 65 20 66 61 75 6c 74 73 20 61 6e 64 20  late faults and 
cfe0: 65 72 72 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73  error conditions
cff0: 20 74 68 61 74 20 77 6f 75 6c 64 20 6f 74 68 65   that would othe
d000: 72 77 69 73 65 20 62 65 20 64 69 66 66 69 63 75  rwise be difficu
d010: 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69  lt.** or impossi
d020: 62 6c 65 20 74 6f 20 69 6e 64 75 63 65 2e 20 20  ble to induce.  
d030: 54 68 65 20 73 65 74 20 6f 66 20 73 79 73 74 65  The set of syste
d040: 6d 20 63 61 6c 6c 73 20 74 68 61 74 20 63 61 6e  m calls that can
d050: 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a   be overridden.*
d060: 2a 20 76 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e  * varies from on
d070: 65 20 56 46 53 20 74 6f 20 61 6e 6f 74 68 65 72  e VFS to another
d080: 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76  , and from one v
d090: 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 73 61  ersion of the sa
d0a0: 6d 65 20 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a  me VFS to the.**
d0b0: 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74   next.  Applicat
d0c0: 69 6f 6e 73 20 74 68 61 74 20 75 73 65 20 74 68  ions that use th
d0d0: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ese interfaces m
d0e0: 75 73 74 20 62 65 20 70 72 65 70 61 72 65 64 20  ust be prepared 
d0f0: 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c  for any.** or al
d100: 6c 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 72  l of these inter
d110: 66 61 63 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c  faces to be NULL
d120: 20 6f 72 20 66 6f 72 20 74 68 65 69 72 20 62 65   or for their be
d130: 68 61 76 69 6f 72 20 74 6f 20 63 68 61 6e 67 65  havior to change
d140: 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c  .** from one rel
d150: 65 61 73 65 20 74 6f 20 74 68 65 20 6e 65 78 74  ease to the next
d160: 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  .  Applications 
d170: 6d 75 73 74 20 6e 6f 74 20 61 74 74 65 6d 70 74  must not attempt
d180: 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e   to access.** an
d190: 79 20 6f 66 20 74 68 65 73 65 20 6d 65 74 68 6f  y of these metho
d1a0: 64 73 20 69 66 20 74 68 65 20 69 56 65 72 73 69  ds if the iVersi
d1b0: 6f 6e 20 6f 66 20 74 68 65 20 56 46 53 20 69 73  on of the VFS is
d1c0: 20 6c 65 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f   less than 3..*/
d1d0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
d1e0: 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69  sqlite3_vfs sqli
d1f0: 74 65 33 5f 76 66 73 3b 0a 74 79 70 65 64 65 66  te3_vfs;.typedef
d200: 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f   void (*sqlite3_
d210: 73 79 73 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69  syscall_ptr)(voi
d220: 64 29 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  d);.struct sqlit
d230: 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69  e3_vfs {.  int i
d240: 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20  Version;        
d250: 20 20 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65      /* Structure
d260: 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20   version number 
d270: 28 63 75 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f  (currently 3) */
d280: 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b  .  int szOsFile;
d290: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
d2a0: 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65  ize of subclasse
d2b0: 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a  d sqlite3_file *
d2c0: 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61  /.  int mxPathna
d2d0: 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  me;          /* 
d2e0: 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74  Maximum file pat
d2f0: 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a  hname length */.
d300: 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70    sqlite3_vfs *p
d310: 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65  Next;      /* Ne
d320: 78 74 20 72 65 67 69 73 74 65 72 65 64 20 56 46  xt registered VF
d330: 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  S */.  const cha
d340: 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20  r *zName;       
d350: 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20  /* Name of this 
d360: 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73  virtual file sys
d370: 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70  tem */.  void *p
d380: 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20  AppData;        
d390: 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20    /* Pointer to 
d3a0: 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63  application-spec
d3b0: 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69  ific data */.  i
d3c0: 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69  nt (*xOpen)(sqli
d3d0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
d3e0: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c  char *zName, sql
d3f0: 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20  ite3_file*,.    
d400: 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 66             int f
d410: 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46  lags, int *pOutF
d420: 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78  lags);.  int (*x
d430: 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f  Delete)(sqlite3_
d440: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
d450: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e   *zName, int syn
d460: 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78  cDir);.  int (*x
d470: 41 63 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f  Access)(sqlite3_
d480: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
d490: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61   *zName, int fla
d4a0: 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74  gs, int *pResOut
d4b0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c  );.  int (*xFull
d4c0: 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65  Pathname)(sqlite
d4d0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
d4e0: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e  ar *zName, int n
d4f0: 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29  Out, char *zOut)
d500: 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f  ;.  void *(*xDlO
d510: 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73  pen)(sqlite3_vfs
d520: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
d530: 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69  Filename);.  voi
d540: 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71  d (*xDlError)(sq
d550: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
d560: 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72  nByte, char *zEr
d570: 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a  rMsg);.  void (*
d580: 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65  (*xDlSym)(sqlite
d590: 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f  3_vfs*,void*, co
d5a0: 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f  nst char *zSymbo
d5b0: 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69  l))(void);.  voi
d5c0: 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71  d (*xDlClose)(sq
d5d0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64  lite3_vfs*, void
d5e0: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e  *);.  int (*xRan
d5f0: 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33  domness)(sqlite3
d600: 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65  _vfs*, int nByte
d610: 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20  , char *zOut);. 
d620: 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73   int (*xSleep)(s
d630: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
d640: 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a   microseconds);.
d650: 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74    int (*xCurrent
d660: 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66  Time)(sqlite3_vf
d670: 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20  s*, double*);.  
d680: 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 74 45 72  int (*xGetLastEr
d690: 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ror)(sqlite3_vfs
d6a0: 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b  *, int, char *);
d6b0: 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d  .  /*.  ** The m
d6c0: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
d6d0: 20 69 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f 66   in version 1 of
d6e0: 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20   the sqlite_vfs 
d6f0: 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64 65 66 69  object.  ** defi
d700: 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74  nition.  Those t
d710: 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61  hat follow are a
d720: 64 64 65 64 20 69 6e 20 76 65 72 73 69 6f 6e 20  dded in version 
d730: 32 20 6f 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a  2 or later.  */.
d740: 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74    int (*xCurrent
d750: 54 69 6d 65 49 6e 74 36 34 29 28 73 71 6c 69 74  TimeInt64)(sqlit
d760: 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69 74 65 33  e3_vfs*, sqlite3
d770: 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20  _int64*);.  /*. 
d780: 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20   ** The methods 
d790: 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72  above are in ver
d7a0: 73 69 6f 6e 73 20 31 20 61 6e 64 20 32 20 6f 66  sions 1 and 2 of
d7b0: 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20   the sqlite_vfs 
d7c0: 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f  object..  ** Tho
d7d0: 73 65 20 62 65 6c 6f 77 20 61 72 65 20 66 6f 72  se below are for
d7e0: 20 76 65 72 73 69 6f 6e 20 33 20 61 6e 64 20 67   version 3 and g
d7f0: 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69  reater..  */.  i
d800: 6e 74 20 28 2a 78 53 65 74 53 79 73 74 65 6d 43  nt (*xSetSystemC
d810: 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73  all)(sqlite3_vfs
d820: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
d830: 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 73 79  Name, sqlite3_sy
d840: 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71  scall_ptr);.  sq
d850: 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74  lite3_syscall_pt
d860: 72 20 28 2a 78 47 65 74 53 79 73 74 65 6d 43 61  r (*xGetSystemCa
d870: 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ll)(sqlite3_vfs*
d880: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
d890: 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68  ame);.  const ch
d8a0: 61 72 20 2a 28 2a 78 4e 65 78 74 53 79 73 74 65  ar *(*xNextSyste
d8b0: 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76  mCall)(sqlite3_v
d8c0: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
d8d0: 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20  *zName);.  /*.  
d8e0: 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61  ** The methods a
d8f0: 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73  bove are in vers
d900: 69 6f 6e 73 20 31 20 74 68 72 6f 75 67 68 20 33  ions 1 through 3
d910: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
d920: 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20  fs object..  ** 
d930: 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62  New fields may b
d940: 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20 66 69  e appended in fi
d950: 67 75 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20  gure versions.  
d960: 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a  The iVersion.  *
d970: 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63  * value will inc
d980: 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20  rement whenever 
d990: 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20 0a 20  this happens. . 
d9a0: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
d9b0: 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f  PI3REF: Flags fo
d9c0: 72 20 74 68 65 20 78 41 63 63 65 73 73 20 56 46  r the xAccess VF
d9d0: 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54  S method.**.** T
d9e0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
d9f0: 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20 75 73  stants can be us
da00: 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20  ed as the third 
da10: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
da20: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
da30: 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65  od of an [sqlite
da40: 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20  3_vfs] object.  
da50: 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a  They determine.*
da60: 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 70  * what kind of p
da70: 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 78  ermissions the x
da80: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 69 73  Access method is
da90: 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a   looking for..**
daa0: 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
dab0: 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68 65 20  ESS_EXISTS, the 
dac0: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
dad0: 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b 73 20  * simply checks 
dae0: 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65  whether the file
daf0: 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68   exists..** With
db00: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
db10: 45 41 44 57 52 49 54 45 2c 20 74 68 65 20 78 41  EADWRITE, the xA
db20: 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20  ccess method.** 
db30: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74  checks whether t
db40: 68 65 20 6e 61 6d 65 64 20 64 69 72 65 63 74 6f  he named directo
db50: 72 79 20 69 73 20 62 6f 74 68 20 72 65 61 64 61  ry is both reada
db60: 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65  ble and writable
db70: 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72 20 77 6f  .** (in other wo
db80: 72 64 73 2c 20 69 66 20 66 69 6c 65 73 20 63 61  rds, if files ca
db90: 6e 20 62 65 20 61 64 64 65 64 2c 20 72 65 6d 6f  n be added, remo
dba0: 76 65 64 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64  ved, and renamed
dbb0: 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64   within.** the d
dbc0: 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68  irectory)..** Th
dbd0: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
dbe0: 52 45 41 44 57 52 49 54 45 20 63 6f 6e 73 74 61  READWRITE consta
dbf0: 6e 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  nt is currently 
dc00: 75 73 65 64 20 6f 6e 6c 79 20 62 79 20 74 68 65  used only by the
dc10: 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f  .** [temp_store_
dc20: 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
dc30: 5d 2c 20 74 68 6f 75 67 68 20 74 68 69 73 20 63  ], though this c
dc40: 6f 75 6c 64 20 63 68 61 6e 67 65 20 69 6e 20 61  ould change in a
dc50: 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61   future.** relea
dc60: 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  se of SQLite..**
dc70: 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
dc80: 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20 78 41  ESS_READ, the xA
dc90: 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20  ccess method.** 
dca0: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74  checks whether t
dcb0: 68 65 20 66 69 6c 65 20 69 73 20 72 65 61 64 61  he file is reada
dcc0: 62 6c 65 2e 20 20 54 68 65 20 53 51 4c 49 54 45  ble.  The SQLITE
dcd0: 5f 41 43 43 45 53 53 5f 52 45 41 44 20 63 6f 6e  _ACCESS_READ con
dce0: 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72  stant is.** curr
dcf0: 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c 20 74 68  ently unused, th
dd00: 6f 75 67 68 20 69 74 20 6d 69 67 68 74 20 62 65  ough it might be
dd10: 20 75 73 65 64 20 69 6e 20 61 20 66 75 74 75 72   used in a futur
dd20: 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20  e release of.** 
dd30: 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69  SQLite..*/.#defi
dd40: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
dd50: 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23 64 65  _EXISTS    0.#de
dd60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
dd70: 53 53 5f 52 45 41 44 57 52 49 54 45 20 31 20 20  SS_READWRITE 1  
dd80: 20 2f 2a 20 55 73 65 64 20 62 79 20 50 52 41 47   /* Used by PRAG
dd90: 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69  MA temp_store_di
dda0: 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69  rectory */.#defi
ddb0: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
ddc0: 5f 52 45 41 44 20 20 20 20 20 20 32 20 20 20 2f  _READ      2   /
ddd0: 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a  * Unused */../*.
dde0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
ddf0: 67 73 20 66 6f 72 20 74 68 65 20 78 53 68 6d 4c  gs for the xShmL
de00: 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a  ock VFS method.*
de10: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
de20: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66  er constants def
de30: 69 6e 65 20 74 68 65 20 76 61 72 69 6f 75 73 20  ine the various 
de40: 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f  locking operatio
de50: 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79  ns.** allowed by
de60: 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65   the xShmLock me
de70: 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69 74 65 33  thod of [sqlite3
de80: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54  _io_methods].  T
de90: 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  he.** following 
dea0: 61 72 65 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67  are the only leg
deb0: 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20  al combinations 
dec0: 6f 66 20 66 6c 61 67 73 20 74 6f 20 74 68 65 0a  of flags to the.
ded0: 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  ** xShmLock meth
dee0: 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  od:.**.** <ul>.*
def0: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
df00: 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  HM_LOCK | SQLITE
df10: 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c  _SHM_SHARED.** <
df20: 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f  li>  SQLITE_SHM_
df30: 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
df40: 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c  M_EXCLUSIVE.** <
df50: 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f  li>  SQLITE_SHM_
df60: 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f  UNLOCK | SQLITE_
df70: 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c  SHM_SHARED.** <l
df80: 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55  i>  SQLITE_SHM_U
df90: 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53  NLOCK | SQLITE_S
dfa0: 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20  HM_EXCLUSIVE.** 
dfb0: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  </ul>.**.** When
dfc0: 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20   unlocking, the 
dfd0: 73 61 6d 65 20 53 48 41 52 45 44 20 6f 72 20 45  same SHARED or E
dfe0: 58 43 4c 55 53 49 56 45 20 66 6c 61 67 20 6d 75  XCLUSIVE flag mu
dff0: 73 74 20 62 65 20 73 75 70 70 6c 69 65 64 20 61  st be supplied a
e000: 73 0a 2a 2a 20 77 61 73 20 67 69 76 65 6e 20 6e  s.** was given n
e010: 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  o the correspond
e020: 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a  ing lock.  .**.*
e030: 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d  * The xShmLock m
e040: 65 74 68 6f 64 20 63 61 6e 20 74 72 61 6e 73 69  ethod can transi
e050: 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c  tion between unl
e060: 6f 63 6b 65 64 20 61 6e 64 20 53 48 41 52 45 44  ocked and SHARED
e070: 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75   or.** between u
e080: 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45 58 43 4c  nlocked and EXCL
e090: 55 53 49 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f  USIVE.  It canno
e0a0: 74 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74  t transition bet
e0b0: 77 65 65 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61  ween SHARED.** a
e0c0: 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f  nd EXCLUSIVE..*/
e0d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
e0e0: 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20  SHM_UNLOCK      
e0f0: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
e100: 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20  E_SHM_LOCK      
e110: 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
e120: 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 20 20  ITE_SHM_SHARED  
e130: 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
e140: 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53  QLITE_SHM_EXCLUS
e150: 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20  IVE    8../*.** 
e160: 43 41 50 49 33 52 45 46 3a 20 4d 61 78 69 6d 75  CAPI3REF: Maximu
e170: 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78  m xShmLock index
e180: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c  .**.** The xShmL
e190: 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73  ock method on [s
e1a0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
e1b0: 73 5d 20 6d 61 79 20 75 73 65 20 76 61 6c 75 65  s] may use value
e1c0: 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61  s.** between 0 a
e1d0: 6e 64 20 74 68 69 73 20 75 70 70 65 72 20 62 6f  nd this upper bo
e1e0: 75 6e 64 20 61 73 20 69 74 73 20 22 6f 66 66 73  und as its "offs
e1f0: 65 74 22 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  et" argument..**
e200: 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
e210: 20 77 69 6c 6c 20 6e 65 76 65 72 20 61 74 74 65   will never atte
e220: 6d 70 74 20 74 6f 20 61 63 71 75 69 72 65 20 6f  mpt to acquire o
e230: 72 20 72 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c  r release a.** l
e240: 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f 66 20 74  ock outside of t
e250: 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65  his range.*/.#de
e260: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
e270: 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 38 0a 0a  NLOCK        8..
e280: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
e290: 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20   Initialize The 
e2a0: 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a  SQLite Library.*
e2b0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
e2c0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72  3_initialize() r
e2d0: 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a  outine initializ
e2e0: 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65  es the.** SQLite
e2f0: 20 6c 69 62 72 61 72 79 2e 20 20 5e 54 68 65 20   library.  ^The 
e300: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
e310: 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65  () routine.** de
e320: 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65  allocates any re
e330: 73 6f 75 72 63 65 73 20 74 68 61 74 20 77 65 72  sources that wer
e340: 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73  e allocated by s
e350: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
e360: 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f  e()..** These ro
e370: 75 74 69 6e 65 73 20 61 72 65 20 64 65 73 69 67  utines are desig
e380: 6e 65 64 20 74 6f 20 61 69 64 20 69 6e 20 70 72  ned to aid in pr
e390: 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61  ocess initializa
e3a0: 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74  tion and.** shut
e3b0: 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64  down on embedded
e3c0: 20 73 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73   systems.  Works
e3d0: 74 61 74 69 6f 6e 20 61 70 70 6c 69 63 61 74 69  tation applicati
e3e0: 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c  ons using.** SQL
e3f0: 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20  ite normally do 
e400: 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f  not need to invo
e410: 6b 65 20 65 69 74 68 65 72 20 6f 66 20 74 68 65  ke either of the
e420: 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  se routines..**.
e430: 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ** A call to sql
e440: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
e450: 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69  ) is an "effecti
e460: 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69  ve" call if it i
e470: 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74  s.** the first t
e480: 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ime sqlite3_init
e490: 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
e4a0: 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c  ked during the l
e4b0: 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68  ifetime of.** th
e4c0: 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66  e process, or if
e4d0: 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74   it is the first
e4e0: 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e   time sqlite3_in
e4f0: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e  itialize() is in
e500: 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  voked.** followi
e510: 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ng a call to sql
e520: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
e530: 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65    ^(Only an effe
e540: 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66  ctive call.** of
e550: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
e560: 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69  ize() does any i
e570: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20  nitialization.  
e580: 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a  All other calls.
e590: 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20  ** are harmless 
e5a0: 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  no-ops.)^.**.** 
e5b0: 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
e5c0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20  3_shutdown() is 
e5d0: 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63  an "effective" c
e5e0: 61 6c 6c 20 69 66 20 69 74 20 69 73 20 74 68 65  all if it is the
e5f0: 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74   first.** call t
e600: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
e610: 77 6e 28 29 20 73 69 6e 63 65 20 74 68 65 20 6c  wn() since the l
e620: 61 73 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ast sqlite3_init
e630: 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c  ialize().  ^(Onl
e640: 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 76  y.** an effectiv
e650: 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  e call to sqlite
e660: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 64 6f 65  3_shutdown() doe
e670: 73 20 61 6e 79 20 64 65 69 6e 69 74 69 61 6c 69  s any deinitiali
e680: 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f  zation..** All o
e690: 74 68 65 72 20 76 61 6c 69 64 20 63 61 6c 6c 73  ther valid calls
e6a0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
e6b0: 64 6f 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c  down() are harml
e6c0: 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a  ess no-ops.)^.**
e6d0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
e6e0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 6e 74  initialize() int
e6f0: 65 72 66 61 63 65 20 69 73 20 74 68 72 65 61 64  erface is thread
e700: 73 61 66 65 2c 20 62 75 74 20 73 71 6c 69 74 65  safe, but sqlite
e710: 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20  3_shutdown().** 
e720: 69 73 20 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c  is not.  The sql
e730: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
e740: 69 6e 74 65 72 66 61 63 65 20 6d 75 73 74 20 6f  interface must o
e750: 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 66 72  nly be called fr
e760: 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74  om a.** single t
e770: 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e  hread.  All open
e780: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
e790: 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20  ctions] must be 
e7a0: 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a  closed and all.*
e7b0: 2a 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 72  * other SQLite r
e7c0: 65 73 6f 75 72 63 65 73 20 6d 75 73 74 20 62 65  esources must be
e7d0: 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 70 72 69   deallocated pri
e7e0: 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a  or to invoking.*
e7f0: 2a 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  * sqlite3_shutdo
e800: 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e  wn()..**.** Amon
e810: 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20  g other things, 
e820: 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  ^sqlite3_initial
e830: 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b  ize() will invok
e840: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f  e.** sqlite3_os_
e850: 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72  init().  Similar
e860: 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68 75  ly, ^sqlite3_shu
e870: 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20  tdown().** will 
e880: 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f  invoke sqlite3_o
e890: 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  s_end()..**.** ^
e8a0: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
e8b0: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
e8c0: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
e8d0: 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e  _OK] on success.
e8e0: 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65  .** ^If for some
e8f0: 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33   reason, sqlite3
e900: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
e910: 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69   unable to initi
e920: 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62  alize.** the lib
e930: 72 61 72 79 20 28 70 65 72 68 61 70 73 20 69 74  rary (perhaps it
e940: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
e950: 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65 64 20  locate a needed 
e960: 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a  resource such.**
e970: 20 61 73 20 61 20 6d 75 74 65 78 29 20 69 74 20   as a mutex) it 
e980: 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f  returns an [erro
e990: 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68  r code] other th
e9a0: 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  an [SQLITE_OK]..
e9b0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
e9c0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
e9d0: 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
e9e0: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20  d internally by 
e9f0: 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51  many other.** SQ
ea00: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20  Lite interfaces 
ea10: 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69  so that an appli
ea20: 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64  cation usually d
ea30: 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a  oes not need to.
ea40: 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ** invoke sqlite
ea50: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64  3_initialize() d
ea60: 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78  irectly.  For ex
ea70: 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f  ample, [sqlite3_
ea80: 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73  open()].** calls
ea90: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
eaa0: 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c  ize() so the SQL
eab0: 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c  ite library will
eac0: 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   be automaticall
ead0: 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64  y.** initialized
eae0: 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f   when [sqlite3_o
eaf0: 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  pen()] is called
eb00: 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62   if it has not b
eb10: 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a  e initialized.**
eb20: 20 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77 65   already.  ^Howe
eb30: 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69  ver, if SQLite i
eb40: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
eb50: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  the [SQLITE_OMIT
eb60: 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f  _AUTOINIT].** co
eb70: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
eb80: 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f  n, then the auto
eb90: 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73  matic calls to s
eba0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
ebb0: 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74  e().** are omitt
ebc0: 65 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69  ed and the appli
ebd0: 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c  cation must call
ebe0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
ebf0: 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a  ize() directly.*
ec00: 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67  * prior to using
ec10: 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74   any other SQLit
ec20: 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f  e interface.  Fo
ec30: 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62  r maximum portab
ec40: 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20  ility,.** it is 
ec50: 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
ec60: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c   applications al
ec70: 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69  ways invoke sqli
ec80: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
ec90: 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69  .** directly pri
eca0: 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20  or to using any 
ecb0: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
ecc0: 65 72 66 61 63 65 2e 20 20 46 75 74 75 72 65 20  erface.  Future 
ecd0: 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53  releases.** of S
ece0: 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75 69 72  QLite may requir
ecf0: 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65  e this.  In othe
ed00: 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68  r words, the beh
ed10: 61 76 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a  avior exhibited.
ed20: 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  ** when SQLite i
ed30: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
ed40: 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54  [SQLITE_OMIT_AUT
ed50: 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63  OINIT] might bec
ed60: 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75  ome the.** defau
ed70: 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73  lt behavior in s
ed80: 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61  ome future relea
ed90: 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  se of SQLite..**
eda0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
edb0: 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e  os_init() routin
edc0: 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67  e does operating
edd0: 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63  -system specific
ede0: 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  .** initializati
edf0: 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65  on of the SQLite
ee00: 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 73   library.  The s
ee10: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a  qlite3_os_end().
ee20: 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65  ** routine undoe
ee30: 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 20  s the effect of 
ee40: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
ee50: 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b  ).  Typical task
ee60: 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62  s.** performed b
ee70: 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  y these routines
ee80: 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74   include allocat
ee90: 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74  ion or deallocat
eea0: 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63  ion.** of static
eeb0: 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74   resources, init
eec0: 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c  ialization of gl
eed0: 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a  obal variables,.
eee0: 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20 61 20  ** setting up a 
eef0: 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
ef00: 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72  _vfs] module, or
ef10: 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61   setting up.** a
ef20: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
ef30: 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71  ration using [sq
ef40: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e  lite3_config()].
ef50: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  .**.** The appli
ef60: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65  cation should ne
ef70: 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65  ver invoke eithe
ef80: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  r sqlite3_os_ini
ef90: 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  t().** or sqlite
efa0: 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63  3_os_end() direc
efb0: 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63  tly.  The applic
efc0: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c  ation should onl
efd0: 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69  y invoke.** sqli
efe0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
eff0: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75   and sqlite3_shu
f000: 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71  tdown().  The sq
f010: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a  lite3_os_init().
f020: 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
f030: 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63  called automatic
f040: 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ally by sqlite3_
f050: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64  initialize() and
f060: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  .** sqlite3_os_e
f070: 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62  nd() is called b
f080: 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  y sqlite3_shutdo
f090: 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61  wn().  Appropria
f0a0: 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  te.** implementa
f0b0: 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65  tions for sqlite
f0c0: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20  3_os_init() and 
f0d0: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
f0e0: 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e  .** are built in
f0f0: 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69  to SQLite when i
f100: 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f  t is compiled fo
f110: 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c  r Unix, Windows,
f120: 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65   or OS/2..** Whe
f130: 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64 73  n [custom builds
f140: 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68   | built for oth
f150: 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a  er platforms].**
f160: 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c   (using the [SQL
f170: 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20  ITE_OS_OTHER=1] 
f180: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20  compile-time.** 
f190: 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c  option) the appl
f1a0: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70  ication must sup
f1b0: 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65 20 69  ply a suitable i
f1c0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  mplementation fo
f1d0: 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f  r.** sqlite3_os_
f1e0: 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74  init() and sqlit
f1f0: 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e  e3_os_end().  An
f200: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70   application-sup
f210: 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65  plied.** impleme
f220: 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74  ntation of sqlit
f230: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20  e3_os_init() or 
f240: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
f250: 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20  .** must return 
f260: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
f270: 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20  uccess and some 
f280: 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64  other [error cod
f290: 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75  e] upon.** failu
f2a0: 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  re..*/.int sqlit
f2b0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f  e3_initialize(vo
f2c0: 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  id);.int sqlite3
f2d0: 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b  _shutdown(void);
f2e0: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f  .int sqlite3_os_
f2f0: 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20  init(void);.int 
f300: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76  sqlite3_os_end(v
f310: 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  oid);../*.** CAP
f320: 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69  I3REF: Configuri
f330: 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69  ng The SQLite Li
f340: 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20  brary.**.** The 
f350: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
f360: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
f370: 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61  ed to make globa
f380: 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a  l configuration.
f390: 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51  ** changes to SQ
f3a0: 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  Lite in order to
f3b0: 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20   tune SQLite to 
f3c0: 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 65  the specific nee
f3d0: 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70  ds of.** the app
f3e0: 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64  lication.  The d
f3f0: 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61  efault configura
f400: 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e  tion is recommen
f410: 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20  ded for most.** 
f420: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64  applications and
f430: 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   so this routine
f440: 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20   is usually not 
f450: 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74 20 69  necessary.  It i
f460: 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f  s.** provided to
f470: 20 73 75 70 70 6f 72 74 20 72 61 72 65 20 61 70   support rare ap
f480: 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20  plications with 
f490: 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a  unusual needs..*
f4a0: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
f4b0: 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
f4c0: 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61  ace is not threa
f4d0: 64 73 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c  dsafe.  The appl
f4e0: 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20  ication.** must 
f4f0: 69 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f  insure that no o
f500: 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
f510: 72 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b  rfaces are invok
f520: 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74  ed by other.** t
f530: 68 72 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c  hreads while sql
f540: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73  ite3_config() is
f550: 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68   running.  Furth
f560: 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f  ermore, sqlite3_
f570: 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20  config().** may 
f580: 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20  only be invoked 
f590: 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79  prior to library
f5a0: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
f5b0: 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
f5c0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
f5d0: 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 6f 77  or after shutdow
f5e0: 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68  n by [sqlite3_sh
f5f0: 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49  utdown()]..** ^I
f600: 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  f sqlite3_config
f610: 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74  () is called aft
f620: 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  er [sqlite3_init
f630: 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65  ialize()] and be
f640: 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  fore.** [sqlite3
f650: 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65  _shutdown()] the
f660: 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e  n it will return
f670: 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a   SQLITE_MISUSE..
f680: 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72  ** Note, however
f690: 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f  , that ^sqlite3_
f6a0: 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20  config() can be 
f6b0: 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f  called as part o
f6c0: 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  f the.** impleme
f6d0: 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70  ntation of an ap
f6e0: 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
f6f0: 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  d [sqlite3_os_in
f700: 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  it()]..**.** The
f710: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
f720: 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  to sqlite3_confi
f730: 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65  g() is an intege
f740: 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74  r.** [configurat
f750: 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74  ion option] that
f760: 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77   determines.** w
f770: 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20  hat property of 
f780: 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20  SQLite is to be 
f790: 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62  configured.  Sub
f7a0: 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74  sequent argument
f7b0: 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64  s.** vary depend
f7c0: 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66  ing on the [conf
f7d0: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
f7e0: 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73  ].** in the firs
f7f0: 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  t argument..**.*
f800: 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67  * ^When a config
f810: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69  uration option i
f820: 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63  s set, sqlite3_c
f830: 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 20  onfig() returns 
f840: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20  [SQLITE_OK]..** 
f850: 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69  ^If the option i
f860: 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c  s unknown or SQL
f870: 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ite is unable to
f880: 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a   set the option.
f890: 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75  ** then this rou
f8a0: 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e  tine returns a n
f8b0: 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
f8c0: 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ode]..*/.int sql
f8d0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c  ite3_config(int,
f8e0: 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
f8f0: 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
f900: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
f910: 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ctions.**.** The
f920: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
f930: 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ig() interface i
f940: 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 63  s used to make c
f950: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20  onfiguration.** 
f960: 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 61  changes to a [da
f970: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
f980: 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61  n].  The interfa
f990: 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f  ce is similar to
f9a0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
f9b0: 66 69 67 28 29 5d 20 65 78 63 65 70 74 20 74 68  fig()] except th
f9c0: 61 74 20 74 68 65 20 63 68 61 6e 67 65 73 20 61  at the changes a
f9d0: 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c 65  pply to a single
f9e0: 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
f9f0: 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 69  nnection] (speci
fa00: 66 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73  fied in the firs
fa10: 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a  t argument)..**.
fa20: 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  ** The second ar
fa30: 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
fa40: 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c  3_db_config(D,V,
fa50: 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20  ...)  is the.** 
fa60: 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  [SQLITE_DBCONFIG
fa70: 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f 6e  _LOOKASIDE | con
fa80: 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 5d  figuration verb]
fa90: 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f   - an integer co
faa0: 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69  de .** that indi
fab0: 63 61 74 65 73 20 77 68 61 74 20 61 73 70 65 63  cates what aspec
fac0: 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61  t of the [databa
fad0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69  se connection] i
fae0: 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72  s being configur
faf0: 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e  ed..** Subsequen
fb00: 74 20 61 72 67 75 6d 65 6e 74 73 20 76 61 72 79  t arguments vary
fb10: 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
fb20: 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  e configuration 
fb30: 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  verb..**.** ^Cal
fb40: 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62  ls to sqlite3_db
fb50: 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e  _config() return
fb60: 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e   SQLITE_OK if an
fb70: 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65  d only if.** the
fb80: 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65   call is conside
fb90: 72 65 64 20 73 75 63 63 65 73 73 66 75 6c 2e 0a  red successful..
fba0: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64  */.int sqlite3_d
fbb0: 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33  b_config(sqlite3
fbc0: 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b  *, int op, ...);
fbd0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
fbe0: 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
fbf0: 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a  ion Routines.**.
fc00: 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
fc10: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65  f this object de
fc20: 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66  fines the interf
fc30: 61 63 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69  ace between SQLi
fc40: 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65  te.** and low-le
fc50: 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  vel memory alloc
fc60: 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a  ation routines..
fc70: 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63  **.** This objec
fc80: 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c  t is used in onl
fc90: 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74  y one place in t
fca0: 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  he SQLite interf
fcb0: 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65  ace..** A pointe
fcc0: 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
fcd0: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
fce0: 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  is the argument 
fcf0: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
fd00: 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68  onfig()] when th
fd10: 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  e configuration 
fd20: 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51  option is.** [SQ
fd30: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
fd40: 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  OC] or [SQLITE_C
fd50: 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d  ONFIG_GETMALLOC]
fd60: 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 69  .  .** By creati
fd70: 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ng an instance o
fd80: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a  f this object.**
fd90: 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20   and passing it 
fda0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  to [sqlite3_conf
fdb0: 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ig]([SQLITE_CONF
fdc0: 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64  IG_MALLOC]).** d
fdd0: 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  uring configurat
fde0: 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  ion, an applicat
fdf0: 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20  ion can specify 
fe00: 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a  an alternative.*
fe10: 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
fe20: 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 66 6f  ion subsystem fo
fe30: 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20  r SQLite to use 
fe40: 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a  for all of its.*
fe50: 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79  * dynamic memory
fe60: 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f   needs..**.** No
fe70: 74 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  te that SQLite c
fe80: 6f 6d 65 73 20 77 69 74 68 20 73 65 76 65 72 61  omes with severa
fe90: 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f  l [built-in memo
fea0: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a  ry allocators].*
feb0: 2a 20 74 68 61 74 20 61 72 65 20 70 65 72 66 65  * that are perfe
fec0: 63 74 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f  ctly adequate fo
fed0: 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69  r the overwhelmi
fee0: 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61  ng majority of a
fef0: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61  pplications.** a
ff00: 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a  nd that this obj
ff10: 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66  ect is only usef
ff20: 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e  ul to a tiny min
ff30: 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61  ority of applica
ff40: 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70  tions.** with sp
ff50: 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79  ecialized memory
ff60: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75   allocation requ
ff70: 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20  irements.  This 
ff80: 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73  object is.** als
ff90: 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65  o used during te
ffa0: 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20  sting of SQLite 
ffb0: 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63  in order to spec
ffc0: 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69  ify an alternati
ffd0: 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c  ve.** memory all
ffe0: 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75  ocator that simu
fff0: 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74  lates memory out
10000 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69  -of-memory condi
10010 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65  tions in.** orde
10020 72 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 74  r to verify that
10030 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73   SQLite recovers
10040 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d   gracefully from
10050 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69   such.** conditi
10060 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ons..**.** The x
10070 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63  Malloc, xRealloc
10080 2c 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68  , and xFree meth
10090 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69  ods must work li
100a0 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63  ke the.** malloc
100b0 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e  (), realloc() an
100c0 64 20 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f  d free() functio
100d0 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e  ns from the stan
100e0 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a  dard C library..
100f0 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61  ** ^SQLite guara
10100 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 73  ntees that the s
10110 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
10120 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73  o.** xRealloc is
10130 20 61 6c 77 61 79 73 20 61 20 76 61 6c 75 65 20   always a value 
10140 72 65 74 75 72 6e 65 64 20 62 79 20 61 20 70 72  returned by a pr
10150 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75  ior call to xRou
10160 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a  ndup..**.** xSiz
10170 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20  e should return 
10180 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69  the allocated si
10190 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61  ze of a memory a
101a0 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65  llocation.** pre
101b0 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64  viously obtained
101c0 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72   from xMalloc or
101d0 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20   xRealloc.  The 
101e0 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a  allocated size.*
101f0 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c  * is always at l
10200 65 61 73 74 20 61 73 20 62 69 67 20 61 73 20 74  east as big as t
10210 68 65 20 72 65 71 75 65 73 74 65 64 20 73 69 7a  he requested siz
10220 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72  e but may be lar
10230 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ger..**.** The x
10240 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72  Roundup method r
10250 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c  eturns what woul
10260 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74  d be the allocat
10270 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20  ed size of.** a 
10280 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
10290 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74 69 63  n given a partic
102a0 75 6c 61 72 20 72 65 71 75 65 73 74 65 64 20 73  ular requested s
102b0 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72  ize.  Most memor
102c0 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20  y.** allocators 
102d0 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20  round up memory 
102e0 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c  allocations at l
102f0 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74  east to the next
10300 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20   multiple.** of 
10310 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74  8.  Some allocat
10320 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20  ors round up to 
10330 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c  a larger multipl
10340 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20  e or to a power 
10350 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d  of 2..** Every m
10360 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
10370 20 72 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20   request coming 
10380 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69  in through [sqli
10390 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  te3_malloc()].**
103a0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
103b0 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61  lloc()] first ca
103c0 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49  lls xRoundup.  I
103d0 66 20 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72  f xRoundup retur
103e0 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63  ns 0, .** that c
103f0 61 75 73 65 73 20 74 68 65 20 63 6f 72 72 65 73  auses the corres
10400 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61  ponding memory a
10410 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69  llocation to fai
10420 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e  l..**.** The xIn
10430 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61  it method initia
10440 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79  lizes the memory
10450 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 28 46 6f   allocator.  (Fo
10460 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74  r example,.** it
10470 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20   might allocate 
10480 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74 65  any require mute
10490 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a  xes or initializ
104a0 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a  e internal data.
104b0 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20 20  ** structures.  
104c0 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65  The xShutdown me
104d0 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20  thod is invoked 
104e0 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a  (indirectly) by.
104f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  ** [sqlite3_shut
10500 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75  down()] and shou
10510 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e  ld deallocate an
10520 79 20 72 65 73 6f 75 72 63 65 73 20 61 63 71 75  y resources acqu
10530 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74  ired.** by xInit
10540 2e 20 20 54 68 65 20 70 41 70 70 44 61 74 61 20  .  The pAppData 
10550 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64 20  pointer is used 
10560 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61  as the only para
10570 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69  meter to.** xIni
10580 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e  t and xShutdown.
10590 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f  .**.** SQLite ho
105a0 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  lds the [SQLITE_
105b0 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53  MUTEX_STATIC_MAS
105c0 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20  TER] mutex when 
105d0 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68  it invokes.** th
105e0 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20  e xInit method, 
105f0 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74  so the xInit met
10600 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20  hod need not be 
10610 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65  threadsafe.  The
10620 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65  .** xShutdown me
10630 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c  thod is only cal
10640 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  led from [sqlite
10650 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f  3_shutdown()] so
10660 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20   it does.** not 
10670 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72 65 61  need to be threa
10680 64 73 61 66 65 20 65 69 74 68 65 72 2e 20 20 46  dsafe either.  F
10690 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74  or all other met
106a0 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  hods, SQLite.** 
106b0 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54  holds the [SQLIT
106c0 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
106d0 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e  EM] mutex as lon
106e0 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  g as the.** [SQL
106f0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
10700 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74  ATUS] configurat
10710 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75  ion option is tu
10720 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a  rned on (which.*
10730 2a 20 69 74 20 69 73 20 62 79 20 64 65 66 61 75  * it is by defau
10740 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d  lt) and so the m
10750 65 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d  ethods are autom
10760 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69  atically seriali
10770 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c  zed..** However,
10780 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   if [SQLITE_CONF
10790 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73  IG_MEMSTATUS] is
107a0 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20   disabled, then 
107b0 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74  the other.** met
107c0 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68 72  hods must be thr
107d0 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20  eadsafe or else 
107e0 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61  make their own a
107f0 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a  rrangements for.
10800 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e  ** serialization
10810 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77  ..**.** SQLite w
10820 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65  ill never invoke
10830 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68   xInit() more th
10840 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20  an once without 
10850 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a  an intervening.*
10860 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64  * call to xShutd
10870 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65  own()..*/.typede
10880 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
10890 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c  _mem_methods sql
108a0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
108b0 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
108c0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20  _mem_methods {. 
108d0 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63   void *(*xMalloc
108e0 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20  )(int);         
108f0 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  /* Memory alloca
10900 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f  tion function */
10910 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29  .  void (*xFree)
10920 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
10930 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f    /* Free a prio
10940 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  r allocation */.
10950 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c    void *(*xReall
10960 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20  oc)(void*,int); 
10970 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c   /* Resize an al
10980 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e  location */.  in
10990 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a  t (*xSize)(void*
109a0 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  );           /* 
109b0 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20  Return the size 
109c0 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e  of an allocation
109d0 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75   */.  int (*xRou
109e0 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20  ndup)(int);     
109f0 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70       /* Round up
10a00 20 72 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f   request size to
10a10 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
10a20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69   */.  int (*xIni
10a30 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  t)(void*);      
10a40 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69       /* Initiali
10a50 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  ze the memory al
10a60 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69  locator */.  voi
10a70 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76  d (*xShutdown)(v
10a80 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44  oid*);      /* D
10a90 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20  einitialize the 
10aa0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
10ab0 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70   */.  void *pApp
10ac0 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 20  Data;           
10ad0 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74       /* Argument
10ae0 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20   to xInit() and 
10af0 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d  xShutdown() */.}
10b00 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
10b10 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e  F: Configuration
10b20 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57   Options.** KEYW
10b30 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61  ORDS: {configura
10b40 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a  tion option}.**.
10b50 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
10b60 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c  ts are the avail
10b70 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  able integer con
10b80 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
10b90 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62  ns that.** can b
10ba0 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
10bb0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
10bc0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
10bd0 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
10be0 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f  ce..**.** New co
10bf0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
10c00 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ons may be added
10c10 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
10c20 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
10c30 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69  * Existing confi
10c40 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
10c50 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e   might be discon
10c60 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61  tinued.  Applica
10c70 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20  tions.** should 
10c80 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e  check the return
10c90 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69   code from [sqli
10ca0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f  te3_config()] to
10cb0 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a   make sure that.
10cc0 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b  ** the call work
10cd0 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ed.  The [sqlite
10ce0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  3_config()] inte
10cf0 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72  rface will retur
10d00 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20  n a.** non-zero 
10d10 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20  [error code] if 
10d20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f  a discontinued o
10d30 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f  r unsupported co
10d40 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
10d50 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64  on.** is invoked
10d60 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
10d70 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
10d80 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c  SINGLETHREAD]] <
10d90 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
10da0 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64  _SINGLETHREAD</d
10db0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20  t>.** <dd>There 
10dc0 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73  are no arguments
10dd0 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e   to this option.
10de0 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73    ^This option s
10df0 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65  ets the.** [thre
10e00 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53  ading mode] to S
10e10 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49  ingle-thread.  I
10e20 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
10e30 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c  t disables.** al
10e40 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70  l mutexing and p
10e50 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20  uts SQLite into 
10e60 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20  a mode where it 
10e70 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  can only be used
10e80 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20  .** by a single 
10e90 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51  thread.   ^If SQ
10ea0 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
10eb0 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
10ec0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
10ed0 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
10ee0 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
10ef0 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
10f00 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
10f10 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20  sible to change 
10f20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  the [threading m
10f30 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65  ode] from its de
10f40 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f  fault.** value o
10f50 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20  f Single-thread 
10f60 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f  and so [sqlite3_
10f70 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72  config()] will r
10f80 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54  eturn .** [SQLIT
10f90 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
10fa0 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  ed with the SQLI
10fb0 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
10fc0 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67  THREAD.** config
10fd0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c  uration option.<
10fe0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
10ff0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
11000 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c  THREAD]] <dt>SQL
11010 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
11020 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  THREAD</dt>.** <
11030 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
11040 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
11050 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73  s option.  ^This
11060 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65   option sets the
11070 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  .** [threading m
11080 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68  ode] to Multi-th
11090 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20  read.  In other 
110a0 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c  words, it disabl
110b0 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f  es.** mutexing o
110c0 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
110d0 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65  ection] and [pre
110e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
110f0 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65   objects..** The
11100 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20   application is 
11110 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
11120 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65  serializing acce
11130 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61  ss to.** [databa
11140 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
11150 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
11160 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20  atements].  But 
11170 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a  other mutexes.**
11180 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20   are enabled so 
11190 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
111a0 20 62 65 20 73 61 66 65 20 74 6f 20 75 73 65 20   be safe to use 
111b0 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61  in a multi-threa
111c0 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65  ded.** environme
111d0 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f  nt as long as no
111e0 20 74 77 6f 20 74 68 72 65 61 64 73 20 61 74 74   two threads att
111f0 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 20  empt to use the 
11200 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73  same.** [databas
11210 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74  e connection] at
11220 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20   the same time. 
11230 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
11240 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
11250 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
11260 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
11270 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
11280 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
11290 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20  n then.** it is 
112a0 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
112b0 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68  set the Multi-th
112c0 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20  read [threading 
112d0 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  mode] and.** [sq
112e0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
112f0 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
11300 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61  ITE_ERROR] if ca
11310 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  lled with the.**
11320 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
11330 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69  ULTITHREAD confi
11340 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
11350 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
11360 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
11370 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c  ALIZED]] <dt>SQL
11380 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
11390 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  LIZED</dt>.** <d
113a0 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61  d>There are no a
113b0 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
113c0 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20   option.  ^This 
113d0 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a  option sets the.
113e0 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ** [threading mo
113f0 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65  de] to Serialize
11400 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  d. In other word
11410 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65  s, this option e
11420 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75  nables.** all mu
11430 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20  texes including 
11440 74 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a  the recursive.**
11450 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74   mutexes on [dat
11460 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
11470 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
11480 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63  statement] objec
11490 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d  ts..** In this m
114a0 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 74 68  ode (which is th
114b0 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53  e default when S
114c0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
114d0 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54  d with.** [SQLIT
114e0 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29  E_THREADSAFE=1])
114f0 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
11500 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20  ary will itself 
11510 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73  serialize access
11520 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65  .** to [database
11530 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e   connections] an
11540 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
11550 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20  ements] so that 
11560 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  the.** applicati
11570 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75 73  on is free to us
11580 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  e the same [data
11590 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
115a0 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20   or the.** same 
115b0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
115c0 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e  ent] in differen
115d0 74 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65  t threads at the
115e0 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e   same time..** ^
115f0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
11600 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
11610 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
11620 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
11630 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
11640 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
11650 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
11660 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65  t possible to se
11670 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64  t the Serialized
11680 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
11690 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
116a0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
116b0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
116c0 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64  ERROR] if called
116d0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c   with the.** SQL
116e0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
116f0 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74  LIZED configurat
11700 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
11710 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
11720 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20  CONFIG_MALLOC]] 
11730 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
11740 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a  G_MALLOC</dt>.**
11750 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
11760 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
11770 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
11780 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
11790 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
117a0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
117b0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
117c0 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72  ructure.  The ar
117d0 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73  gument specifies
117e0 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20  .** alternative 
117f0 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
11800 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
11810 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20  ines to be used 
11820 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74  in place of.** t
11830 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
11840 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75  tion routines bu
11850 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
11860 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  )^ ^SQLite makes
11870 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76  .** its own priv
11880 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
11890 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b  content of the [
118a0 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
118b0 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a  ods] structure.*
118c0 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71  * before the [sq
118d0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
118e0 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64  call returns.</d
118f0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
11900 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
11910 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OC]] <dt>SQLITE_
11920 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
11930 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
11940 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
11950 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
11960 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
11970 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
11980 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
11990 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
119a0 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
119b0 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d    The [sqlite3_m
119c0 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73  em_methods].** s
119d0 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c  tructure is fill
119e0 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72  ed with the curr
119f0 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65  ently defined me
11a00 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
11a10 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54  routines.)^.** T
11a20 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62  his option can b
11a30 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f  e used to overlo
11a40 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  ad the default m
11a50 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
11a60 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74  .** routines wit
11a70 68 20 61 20 77 72 61 70 70 65 72 20 74 68 61 74  h a wrapper that
11a80 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d   simulations mem
11a90 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
11aa0 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61  ailure or.** tra
11ab0 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65  cks memory usage
11ac0 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c  , for example. <
11ad0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
11ae0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
11af0 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  ATUS]] <dt>SQLIT
11b00 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
11b10 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  US</dt>.** <dd> 
11b20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  ^This option tak
11b30 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65  es single argume
11b40 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 20  nt of type int, 
11b50 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
11b60 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 68   .** boolean, wh
11b70 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  ich enables or d
11b80 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c  isables the coll
11b90 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79  ection of memory
11ba0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20   allocation .** 
11bb0 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68  statistics. ^(Wh
11bc0 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  en memory alloca
11bd0 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20  tion statistics 
11be0 61 72 65 20 64 69 73 61 62 6c 65 64 2c 20 74 68  are disabled, th
11bf0 65 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  e .** following 
11c00 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
11c10 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65  s become non-ope
11c20 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c  rational:.**   <
11c30 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ul>.**   <li> [s
11c40 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
11c50 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20  ed()].**   <li> 
11c60 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
11c70 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20  highwater()].** 
11c80 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
11c90 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36  soft_heap_limit6
11ca0 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  4()].**   <li> [
11cb0 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29  sqlite3_status()
11cc0 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a  ].**   </ul>)^.*
11cd0 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  * ^Memory alloca
11ce0 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20  tion statistics 
11cf0 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64  are enabled by d
11d00 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51  efault unless SQ
11d10 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69  Lite is.** compi
11d20 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45  led with [SQLITE
11d30 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54  _DEFAULT_MEMSTAT
11d40 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63  US]=0 in which c
11d50 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ase memory.** al
11d60 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74  location statist
11d70 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64  ics are disabled
11d80 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20   by default..** 
11d90 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
11da0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
11db0 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  TCH]] <dt>SQLITE
11dc0 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c  _CONFIG_SCRATCH<
11dd0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
11de0 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  is option specif
11df0 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
11e00 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20  ory buffer that 
11e10 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66  SQLite can use f
11e20 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65  or.** scratch me
11e30 6d 6f 72 79 2e 20 20 54 68 65 72 65 20 61 72 65  mory.  There are
11e40 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73   three arguments
11e50 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 61 6e 20  :  A pointer an 
11e60 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65  8-byte.** aligne
11e70 64 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  d memory buffer 
11e80 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 73  from which the s
11e90 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f  cratch allocatio
11ea0 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72  ns will be.** dr
11eb0 61 77 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f 66  awn, the size of
11ec0 20 65 61 63 68 20 73 63 72 61 74 63 68 20 61 6c   each scratch al
11ed0 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a  location (sz),.*
11ee0 2a 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75  * and the maximu
11ef0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73 63 72 61  m number of scra
11f00 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  tch allocations 
11f10 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20  (N).  The sz.** 
11f20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
11f30 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31   a multiple of 1
11f40 36 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  6..** The first 
11f50 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
11f60 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
11f70 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20   8-byte aligned 
11f80 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20  buffer.** of at 
11f90 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73  least sz*N bytes
11fa0 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e   of memory..** ^
11fb0 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
11fc0 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20 74 77 6f  no more than two
11fd0 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 73   scratch buffers
11fe0 20 70 65 72 20 74 68 72 65 61 64 2e 20 20 53 6f   per thread.  So
11ff0 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65 20  .** N should be 
12000 73 65 74 20 74 6f 20 74 77 69 63 65 20 74 68 65  set to twice the
12010 20 65 78 70 65 63 74 65 64 20 6d 61 78 69 6d 75   expected maximu
12020 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65  m number of thre
12030 61 64 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ads..** ^SQLite 
12040 77 69 6c 6c 20 6e 65 76 65 72 20 72 65 71 75 69  will never requi
12050 72 65 20 61 20 73 63 72 61 74 63 68 20 62 75 66  re a scratch buf
12060 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65  fer that is more
12070 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73   than 6.** times
12080 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61   the database pa
12090 67 65 20 73 69 7a 65 2e 20 5e 49 66 20 53 51 4c  ge size. ^If SQL
120a0 69 74 65 20 6e 65 65 64 73 20 6e 65 65 64 73 20  ite needs needs 
120b0 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63  additional.** sc
120c0 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 62 65 79  ratch memory bey
120d0 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76  ond what is prov
120e0 69 64 65 64 20 62 79 20 74 68 69 73 20 63 6f 6e  ided by this con
120f0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
12100 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c  n, then .** [sql
12110 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77  ite3_malloc()] w
12120 69 6c 6c 20 62 65 20 75 73 65 64 20 74 6f 20 6f  ill be used to o
12130 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79  btain the memory
12140 20 6e 65 65 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a   needed.</dd>.**
12150 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
12160 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 5d 20  FIG_PAGECACHE]] 
12170 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
12180 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e  G_PAGECACHE</dt>
12190 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
121a0 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
121b0 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20  a static memory 
121c0 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69  buffer that SQLi
121d0 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a  te can use for.*
121e0 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70  * the database p
121f0 61 67 65 20 63 61 63 68 65 20 77 69 74 68 20 74  age cache with t
12200 68 65 20 64 65 66 61 75 6c 74 20 70 61 67 65 20  he default page 
12210 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
12220 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20  tion.  .** This 
12230 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 73 68  configuration sh
12240 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64  ould not be used
12250 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   if an applicati
12260 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a  on-define page.*
12270 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  * cache implemen
12280 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64  tation is loaded
12290 20 75 73 69 6e 67 20 74 68 65 20 53 51 4c 49 54   using the SQLIT
122a0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
122b0 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72   option..** Ther
122c0 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
122d0 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
122e0 74 69 6f 6e 3a 20 41 20 70 6f 69 6e 74 65 72 20  tion: A pointer 
122f0 74 6f 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  to 8-byte aligne
12300 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65  d.** memory, the
12310 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61   size of each pa
12320 67 65 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20  ge buffer (sz), 
12330 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  and the number o
12340 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20  f pages (N)..** 
12350 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20  The sz argument 
12360 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69  should be the si
12370 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73  ze of the larges
12380 74 20 64 61 74 61 62 61 73 65 20 70 61 67 65 0a  t database page.
12390 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74  ** (a power of t
123a0 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20 61  wo between 512 a
123b0 6e 64 20 33 32 37 36 38 29 20 70 6c 75 73 20 61  nd 32768) plus a
123c0 20 6c 69 74 74 6c 65 20 65 78 74 72 61 20 66 6f   little extra fo
123d0 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68  r each.** page h
123e0 65 61 64 65 72 2e 20 20 5e 54 68 65 20 70 61 67  eader.  ^The pag
123f0 65 20 68 65 61 64 65 72 20 73 69 7a 65 20 69 73  e header size is
12400 20 32 30 20 74 6f 20 34 30 20 62 79 74 65 73 20   20 to 40 bytes 
12410 64 65 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20  depending on.** 
12420 74 68 65 20 68 6f 73 74 20 61 72 63 68 69 74 65  the host archite
12430 63 74 75 72 65 2e 20 20 5e 49 74 20 69 73 20 68  cture.  ^It is h
12440 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66  armless, apart f
12450 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d  rom the wasted m
12460 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b  emory,.** to mak
12470 65 20 73 7a 20 61 20 6c 69 74 74 6c 65 20 74 6f  e sz a little to
12480 6f 20 6c 61 72 67 65 2e 20 20 54 68 65 20 66 69  o large.  The fi
12490 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  rst.** argument 
124a0 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20  should point to 
124b0 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66  an allocation of
124c0 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62   at least sz*N b
124d0 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a  ytes of memory..
124e0 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
124f0 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70  use the memory p
12500 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 66  rovided by the f
12510 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
12520 20 73 61 74 69 73 66 79 20 69 74 73 0a 2a 2a 20   satisfy its.** 
12530 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f 72  memory needs for
12540 20 74 68 65 20 66 69 72 73 74 20 4e 20 70 61 67   the first N pag
12550 65 73 20 74 68 61 74 20 69 74 20 61 64 64 73 20  es that it adds 
12560 74 6f 20 63 61 63 68 65 2e 20 20 5e 49 66 20 61  to cache.  ^If a
12570 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67  dditional.** pag
12580 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69  e cache memory i
12590 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20  s needed beyond 
125a0 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64  what is provided
125b0 20 62 79 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c   by this option,
125c0 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20   then.** SQLite 
125d0 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  goes to [sqlite3
125e0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74  _malloc()] for t
125f0 68 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74  he additional st
12600 6f 72 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20  orage space..** 
12610 54 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 74  The pointer in t
12620 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
12630 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c 69  t must.** be ali
12640 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74  gned to an 8-byt
12650 65 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75  e boundary or su
12660 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f  bsequent behavio
12670 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77  r of SQLite.** w
12680 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64  ill be undefined
12690 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
126a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
126b0 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  P]] <dt>SQLITE_C
126c0 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a  ONFIG_HEAP</dt>.
126d0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
126e0 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
126f0 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62   static memory b
12700 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74  uffer that SQLit
12710 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f  e will use.** fo
12720 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e  r all of its dyn
12730 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  amic memory allo
12740 63 61 74 69 6f 6e 20 6e 65 65 64 73 20 62 65 79  cation needs bey
12750 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64  ond those provid
12760 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20 5b 53 51  ed.** for by [SQ
12770 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
12780 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45  TCH] and [SQLITE
12790 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
127a0 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  E]..** There are
127b0 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73   three arguments
127c0 3a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67  : An 8-byte alig
127d0 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  ned pointer to t
127e0 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68  he memory,.** th
127f0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
12800 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20  s in the memory 
12810 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20  buffer, and the 
12820 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69  minimum allocati
12830 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20  on size..** ^If 
12840 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65  the first pointe
12850 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f  r (the memory po
12860 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20  inter) is NULL, 
12870 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65  then SQLite reve
12880 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20  rts.** to using 
12890 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f  its default memo
128a0 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68  ry allocator (th
128b0 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28  e system malloc(
128c0 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  ) implementation
128d0 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e  ),.** undoing an
128e0 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69  y prior invocati
128f0 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f  on of [SQLITE_CO
12900 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e  NFIG_MALLOC].  ^
12910 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79  If the.** memory
12920 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
12930 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68 65 72 20  NULL and either 
12940 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d  [SQLITE_ENABLE_M
12950 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53  EMSYS3] or.** [S
12960 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
12970 53 59 53 35 5d 20 61 72 65 20 64 65 66 69 6e 65  SYS5] are define
12980 64 2c 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65  d, then the alte
12990 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a  rnative memory.*
129a0 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65  * allocator is e
129b0 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65  ngaged to handle
129c0 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20   all of SQLites 
129d0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
129e0 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20  n needs..** The 
129f0 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74  first pointer (t
12a00 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  he memory pointe
12a10 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e  r) must be align
12a20 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a  ed to an 8-byte.
12a30 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73  ** boundary or s
12a40 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69  ubsequent behavi
12a50 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c  or of SQLite wil
12a60 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a  l be undefined..
12a70 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61  ** The minimum a
12a80 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 69  llocation size i
12a90 73 20 63 61 70 70 65 64 20 61 74 20 32 2a 2a 31  s capped at 2**1
12aa0 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20 76 61  2. Reasonable va
12ab0 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20  lues.** for the 
12ac0 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69  minimum allocati
12ad0 6f 6e 20 73 69 7a 65 20 61 72 65 20 32 2a 2a 35  on size are 2**5
12ae0 20 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f   through 2**8.</
12af0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
12b00 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d  TE_CONFIG_MUTEX]
12b10 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
12b20 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a  FIG_MUTEX</dt>.*
12b30 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70  * <dd> ^(This op
12b40 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
12b50 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
12b60 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ch is a pointer 
12b70 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63  to an.** instanc
12b80 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
12b90 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
12ba0 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
12bb0 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66   argument specif
12bc0 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69  ies.** alternati
12bd0 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74  ve low-level mut
12be0 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62  ex routines to b
12bf0 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 0a  e used in place.
12c00 2a 2a 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75  ** the mutex rou
12c10 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f  tines built into
12c20 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c   SQLite.)^  ^SQL
12c30 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ite makes a copy
12c40 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6e 74 65   of the.** conte
12c50 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  nt of the [sqlit
12c60 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
12c70 5d 20 73 74 72 75 63 74 75 72 65 20 62 65 66 6f  ] structure befo
12c80 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a  re the call to.*
12c90 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
12ca0 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49  g()] returns. ^I
12cb0 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
12cc0 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
12cd0 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
12ce0 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
12cf0 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
12d00 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
12d10 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72  hen.** the entir
12d20 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79  e mutexing subsy
12d30 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20  stem is omitted 
12d40 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61  from the build a
12d50 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74  nd hence calls t
12d60 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
12d70 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65  nfig()] with the
12d80 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
12d90 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69  UTEX configurati
12da0 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a  on option will.*
12db0 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
12dc0 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a  _ERROR].</dd>.**
12dd0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
12de0 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c  FIG_GETMUTEX]] <
12df0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
12e00 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a  _GETMUTEX</dt>.*
12e10 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70  * <dd> ^(This op
12e20 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
12e30 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
12e40 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ch is a pointer 
12e50 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63  to an.** instanc
12e60 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
12e70 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
12e80 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
12e90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  .** [sqlite3_mut
12ea0 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73  ex_methods].** s
12eb0 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c  tructure is fill
12ec0 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72  ed with the curr
12ed0 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75  ently defined mu
12ee0 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a  tex routines.)^.
12ef0 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63  ** This option c
12f00 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76  an be used to ov
12f10 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75  erload the defau
12f20 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74  lt mutex allocat
12f30 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ion.** routines 
12f40 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 75  with a wrapper u
12f50 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74  sed to track mut
12f60 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 72  ex usage for per
12f70 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66  formance.** prof
12f80 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67  iling or testing
12f90 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20  , for example.  
12fa0 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
12fb0 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
12fc0 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
12fd0 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
12fe0 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
12ff0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
13000 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e  n then.** the en
13010 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75  tire mutexing su
13020 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74  bsystem is omitt
13030 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c  ed from the buil
13040 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c  d and hence call
13050 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
13060 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20  _config()] with 
13070 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
13080 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69  G_GETMUTEX confi
13090 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
130a0 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  will.** return [
130b0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f  SQLITE_ERROR].</
130c0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
130d0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
130e0 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  IDE]] <dt>SQLITE
130f0 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
13100 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
13110 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
13120 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  es two arguments
13130 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20   that determine 
13140 74 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d  the default.** m
13150 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13160 20 66 6f 72 20 74 68 65 20 6c 6f 6f 6b 61 73 69   for the lookasi
13170 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  de memory alloca
13180 74 6f 72 20 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b  tor on each.** [
13190 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
131a0 69 6f 6e 5d 2e 20 20 54 68 65 20 66 69 72 73 74  ion].  The first
131b0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
131c0 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68  .** size of each
131d0 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
131e0 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73  r slot and the s
131f0 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d  econd is the num
13200 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20  ber of.** slots 
13210 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63  allocated to eac
13220 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  h database conne
13230 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 54 68 69 73  ction.)^  ^(This
13240 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65   option sets the
13250 0a 2a 2a 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f  .** <i>default</
13260 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a  i> lookaside siz
13270 65 2e 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44  e. The [SQLITE_D
13280 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
13290 45 5d 0a 2a 2a 20 76 65 72 62 20 74 6f 20 5b 73  E].** verb to [s
132a0 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
132b0 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20  ()] can be used 
132c0 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f  to change the lo
132d0 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69  okaside.** confi
132e0 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69  guration on indi
132f0 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f  vidual connectio
13300 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ns.)^ </dd>.**.*
13310 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
13320 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e  G_PCACHE2]] <dt>
13330 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
13340 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHE2</dt>.** <d
13350 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
13360 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
13370 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
13380 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a  s a pointer to.*
13390 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63  * an [sqlite3_pc
133a0 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f  ache_methods2] o
133b0 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a  bject.  This obj
133c0 65 63 74 20 73 70 65 63 69 66 69 65 73 20 74 68  ect specifies th
133d0 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74  e interface.** t
133e0 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20  o a custom page 
133f0 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
13400 74 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 65  tion.)^  ^SQLite
13410 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
13420 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61   the.** object a
13430 6e 64 20 75 73 65 73 20 69 74 20 66 6f 72 20 70  nd uses it for p
13440 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79  age cache memory
13450 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64   allocations.</d
13460 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
13470 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
13480 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  HE2]] <dt>SQLITE
13490 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
134a0 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  E2</dt>.** <dd> 
134b0 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
134c0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
134d0 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
134e0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
134f0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  * [sqlite3_pcach
13500 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65  e_methods2] obje
13510 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69  ct.  SQLite copi
13520 65 73 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  es of the curren
13530 74 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20  t.** page cache 
13540 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
13550 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e  nto that object.
13560 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  )^ </dd>.**.** [
13570 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  [SQLITE_CONFIG_L
13580 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OG]] <dt>SQLITE_
13590 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a  CONFIG_LOG</dt>.
135a0 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49  ** <dd> The SQLI
135b0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70  TE_CONFIG_LOG op
135c0 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
135d0 63 6f 6e 66 69 67 75 72 65 20 74 68 65 20 53 51  configure the SQ
135e0 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b  Lite.** global [
135f0 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28  error log]..** (
13600 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
13610 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61  IG_LOG option ta
13620 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  kes two argument
13630 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  s: a pointer to 
13640 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69  a.** function wi
13650 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74  th a call signat
13660 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76  ure of void(*)(v
13670 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  oid*,int,const c
13680 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61  har*), .** and a
13690 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64   pointer to void
136a0 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69  . ^If the functi
136b0 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  on pointer is no
136c0 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a  t NULL, it is.**
136d0 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c   invoked by [sql
136e0 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70  ite3_log()] to p
136f0 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67  rocess each logg
13700 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20  ing event.  ^If 
13710 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  the.** function 
13720 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c  pointer is NULL,
13730 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f   the [sqlite3_lo
13740 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62  g()] interface b
13750 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a  ecomes a no-op..
13760 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69  ** ^The void poi
13770 6e 74 65 72 20 74 68 61 74 20 69 73 20 74 68 65  nter that is the
13780 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
13790 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49   to SQLITE_CONFI
137a0 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73  G_LOG is.** pass
137b0 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68  ed through as th
137c0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
137d0 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  r to the applica
137e0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67  tion-defined log
137f0 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ger.** function 
13800 77 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 75  whenever that fu
13810 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65  nction is invoke
13820 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  d.  ^The second 
13830 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
13840 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74  the logger funct
13850 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ion is a copy of
13860 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
13870 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72  eter to the corr
13880 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71  esponding.** [sq
13890 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c  lite3_log()] cal
138a0 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65  l and is intende
138b0 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c  d to be a [resul
138c0 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a  t code] or an.**
138d0 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
138e0 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74  t code].  ^The t
138f0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 70  hird parameter p
13900 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67  assed to the log
13910 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65  ger is.** log me
13920 73 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d  ssage after form
13930 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69  atting via [sqli
13940 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e  te3_snprintf()].
13950 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c  .** The SQLite l
13960 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65  ogging interface
13970 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e   is not reentran
13980 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75  t; the logger fu
13990 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69  nction.** suppli
139a0 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ed by the applic
139b0 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69  ation must not i
139c0 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65  nvoke any SQLite
139d0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49   interface..** I
139e0 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  n a multi-thread
139f0 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20  ed application, 
13a00 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
13a10 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a  defined logger.*
13a20 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  * function must 
13a30 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c  be threadsafe. <
13a40 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
13a50 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d  ITE_CONFIG_URI]]
13a60 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
13a70 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28  IG_URI.** <dd>^(
13a80 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
13a90 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
13aa0 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e  ent of type int.
13ab0 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68   If non-zero, th
13ac0 65 6e 0a 2a 2a 20 55 52 49 20 68 61 6e 64 6c 69  en.** URI handli
13ad0 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65  ng is globally e
13ae0 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70  nabled. If the p
13af0 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f  arameter is zero
13b00 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c  , then URI handl
13b10 69 6e 67 0a 2a 2a 20 69 73 20 67 6c 6f 62 61 6c  ing.** is global
13b20 6c 79 20 64 69 73 61 62 6c 65 64 2e 29 5e 20 5e  ly disabled.)^ ^
13b30 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  If URI handling 
13b40 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62  is globally enab
13b50 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d  led, all filenam
13b60 65 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 6f 20  es.** passed to 
13b70 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
13b80 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  , [sqlite3_open_
13b90 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v2()], [sqlite3_
13ba0 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20  open16()] or.** 
13bb0 73 70 65 63 69 66 69 65 64 20 61 73 20 70 61 72  specified as par
13bc0 74 20 6f 66 20 5b 41 54 54 41 43 48 5d 20 63 6f  t of [ATTACH] co
13bd0 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e 74 65 72  mmands are inter
13be0 70 72 65 74 65 64 20 61 73 20 55 52 49 73 2c 20  preted as URIs, 
13bf0 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66  regardless.** of
13c00 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
13c10 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
13c20 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 20 73 65  _URI] flag is se
13c30 74 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62  t when the datab
13c40 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
13c50 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 49 66  n is opened. ^If
13c60 20 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20   it is globally 
13c70 64 69 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61  disabled, filena
13c80 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20  mes are.** only 
13c90 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
13ca0 52 49 73 20 69 66 20 74 68 65 20 53 51 4c 49 54  RIs if the SQLIT
13cb0 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67 20  E_OPEN_URI flag 
13cc0 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 0a  is set when the.
13cd0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
13ce0 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64  ection is opened
13cf0 2e 20 5e 28 42 79 20 64 65 66 61 75 6c 74 2c 20  . ^(By default, 
13d00 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20  URI handling is 
13d10 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61  globally.** disa
13d20 62 6c 65 64 2e 20 54 68 65 20 64 65 66 61 75 6c  bled. The defaul
13d30 74 20 76 61 6c 75 65 20 6d 61 79 20 62 65 20 63  t value may be c
13d40 68 61 6e 67 65 64 20 62 79 20 63 6f 6d 70 69 6c  hanged by compil
13d50 69 6e 67 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  ing with the.** 
13d60 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d  [SQLITE_USE_URI]
13d70 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e   symbol defined.
13d80 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
13d90 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e  E_CONFIG_COVERIN
13da0 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d 20 3c  G_INDEX_SCAN]] <
13db0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
13dc0 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f  _COVERING_INDEX_
13dd0 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 68 69  SCAN.** <dd>^Thi
13de0 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
13df0 20 73 69 6e 67 6c 65 20 69 6e 74 65 67 65 72 20   single integer 
13e00 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
13e10 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
13e20 0a 2a 2a 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e  .** a boolean in
13e30 20 6f 72 64 65 72 20 74 6f 20 65 6e 61 62 6c 65   order to enable
13e40 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20   or disable the 
13e50 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20  use of covering 
13e60 69 6e 64 69 63 65 73 20 66 6f 72 0a 2a 2a 20 66  indices for.** f
13e70 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 20  ull table scans 
13e80 69 6e 20 74 68 65 20 71 75 65 72 79 20 6f 70 74  in the query opt
13e90 69 6d 69 7a 65 72 2e 20 20 5e 54 68 65 20 64 65  imizer.  ^The de
13ea0 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 69 73  fault setting is
13eb0 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a 20 62   determined.** b
13ec0 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 41 4c  y the [SQLITE_AL
13ed0 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  LOW_COVERING_IND
13ee0 45 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69 6c 65  EX_SCAN] compile
13ef0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 6f 72  -time option, or
13f00 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66 20 74   is "on".** if t
13f10 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  hat compile-time
13f20 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74   option is omitt
13f30 65 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69 6c 69  ed..** The abili
13f40 74 79 20 74 6f 20 64 69 73 61 62 6c 65 20 74 68  ty to disable th
13f50 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e  e use of coverin
13f60 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75  g indices for fu
13f70 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 0a 2a  ll table scans.*
13f80 2a 20 69 73 20 62 65 63 61 75 73 65 20 73 6f 6d  * is because som
13f90 65 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 63 6f  e incorrectly co
13fa0 64 65 64 20 6c 65 67 61 63 79 20 61 70 70 6c 69  ded legacy appli
13fb0 63 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6d 61  cations might ma
13fc0 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 68 65  lfunction.** whe
13fd0 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69  n the optimizati
13fe0 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 20 20  on is enabled.  
13ff0 50 72 6f 76 69 64 69 6e 67 20 74 68 65 20 61 62  Providing the ab
14000 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69 73 61  ility to.** disa
14010 62 6c 65 20 74 68 65 20 6f 70 74 69 6d 69 7a 61  ble the optimiza
14020 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 65 20  tion allows the 
14030 6f 6c 64 65 72 2c 20 62 75 67 67 79 20 61 70 70  older, buggy app
14040 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 74 6f  lication code to
14050 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f 75 74   work.** without
14060 20 63 68 61 6e 67 65 20 65 76 65 6e 20 77 69 74   change even wit
14070 68 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73  h newer versions
14080 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
14090 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
140a0 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c  G_PCACHE]] [[SQL
140b0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
140c0 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  ACHE]].** <dt>SQ
140d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
140e0 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f  HE and SQLITE_CO
140f0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 0a 2a  NFIG_GETPCACHE.*
14100 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f 70 74  * <dd> These opt
14110 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65 74  ions are obsolet
14120 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74  e and should not
14130 20 62 65 20 75 73 65 64 20 62 79 20 6e 65 77 20   be used by new 
14140 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72  code..** They ar
14150 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20 62  e retained for b
14160 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
14170 62 69 6c 69 74 79 20 62 75 74 20 61 72 65 20 6e  bility but are n
14180 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f  ow no-ops..** </
14190 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
141a0 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47  TE_CONFIG_SQLLOG
141b0 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
141c0 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a  _CONFIG_SQLLOG.*
141d0 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f  * <dd>This optio
141e0 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61  n is only availa
141f0 62 6c 65 20 69 66 20 73 71 6c 69 74 65 20 69 73  ble if sqlite is
14200 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
14210 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  he.** [SQLITE_EN
14220 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70 72 65  ABLE_SQLLOG] pre
14230 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  -processor macro
14240 20 64 65 66 69 6e 65 64 2e 20 54 68 65 20 66 69   defined. The fi
14250 72 73 74 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  rst argument sho
14260 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f 69 6e  uld.** be a poin
14270 74 65 72 20 74 6f 20 61 20 66 75 6e 63 74 69 6f  ter to a functio
14280 6e 20 6f 66 20 74 79 70 65 20 76 6f 69 64 28 2a  n of type void(*
14290 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a  )(void*,sqlite3*
142a0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e  ,const char*, in
142b0 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  t)..** The secon
142c0 64 20 73 68 6f 75 6c 64 20 62 65 20 6f 66 20 74  d should be of t
142d0 79 70 65 20 28 76 6f 69 64 2a 29 2e 20 54 68 65  ype (void*). The
142e0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
142f0 6f 6b 65 64 20 62 79 20 74 68 65 20 6c 69 62 72  oked by the libr
14300 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65 65 20  ary.** in three 
14310 73 65 70 61 72 61 74 65 20 63 69 72 63 75 6d 73  separate circums
14320 74 61 6e 63 65 73 2c 20 69 64 65 6e 74 69 66 69  tances, identifi
14330 65 64 20 62 79 20 74 68 65 20 76 61 6c 75 65 20  ed by the value 
14340 70 61 73 73 65 64 20 61 73 20 74 68 65 0a 2a 2a  passed as the.**
14350 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
14360 72 2e 20 49 66 20 74 68 65 20 66 6f 75 72 74 68  r. If the fourth
14370 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 30 2c   parameter is 0,
14380 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
14390 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
143a0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73   passed as the s
143b0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 68  econd argument h
143c0 61 73 20 6a 75 73 74 20 62 65 65 6e 20 6f 70 65  as just been ope
143d0 6e 65 64 2e 20 54 68 65 20 74 68 69 72 64 20 61  ned. The third a
143e0 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74  rgument.** point
143f0 73 20 74 6f 20 61 20 62 75 66 66 65 72 20 63 6f  s to a buffer co
14400 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 61 6d  ntaining the nam
14410 65 20 6f 66 20 74 68 65 20 6d 61 69 6e 20 64 61  e of the main da
14420 74 61 62 61 73 65 20 66 69 6c 65 2e 20 49 66 20  tabase file. If 
14430 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61  the.** fourth pa
14440 72 61 6d 65 74 65 72 20 69 73 20 31 2c 20 74 68  rameter is 1, th
14450 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  en the SQL state
14460 6d 65 6e 74 20 74 68 61 74 20 74 68 65 20 74 68  ment that the th
14470 69 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  ird parameter.**
14480 20 70 6f 69 6e 74 73 20 74 6f 20 68 61 73 20 6a   points to has j
14490 75 73 74 20 62 65 65 6e 20 65 78 65 63 75 74 65  ust been execute
144a0 64 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 66 6f  d. Or, if the fo
144b0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
144c0 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65  s 2, then.** the
144d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 69 6e   connection bein
144e0 67 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  g passed as the 
144f0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
14500 20 69 73 20 62 65 69 6e 67 20 63 6c 6f 73 65 64   is being closed
14510 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 70  . The.** third p
14520 61 72 61 6d 65 74 65 72 20 69 73 20 70 61 73 73  arameter is pass
14530 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69 73 20  ed NULL In this 
14540 63 61 73 65 2e 20 20 41 6e 20 65 78 61 6d 70 6c  case.  An exampl
14550 65 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73 0a  e of using this.
14560 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
14570 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 73   option can be s
14580 65 65 6e 20 69 6e 20 74 68 65 20 22 74 65 73 74  een in the "test
14590 5f 73 71 6c 6c 6f 67 2e 63 22 20 73 6f 75 72 63  _sqllog.c" sourc
145a0 65 20 66 69 6c 65 20 69 6e 0a 2a 2a 20 74 68 65  e file in.** the
145b0 20 63 61 6e 6f 6e 69 63 61 6c 20 53 51 4c 69 74   canonical SQLit
145c0 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e 3c 2f  e source tree.</
145d0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
145e0 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53  TE_CONFIG_MMAP_S
145f0 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  IZE]].** <dt>SQL
14600 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f  ITE_CONFIG_MMAP_
14610 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53 51 4c  SIZE.** <dd>^SQL
14620 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f  ITE_CONFIG_MMAP_
14630 53 49 5a 45 20 74 61 6b 65 73 20 74 77 6f 20 36  SIZE takes two 6
14640 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 28 73  4-bit integer (s
14650 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 20 76 61  qlite3_int64) va
14660 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  lues.** that are
14670 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 6d 61   the default mma
14680 70 20 73 69 7a 65 20 6c 69 6d 69 74 20 28 74 68  p size limit (th
14690 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e  e default settin
146a0 67 20 66 6f 72 0a 2a 2a 20 5b 50 52 41 47 4d 41  g for.** [PRAGMA
146b0 20 6d 6d 61 70 5f 73 69 7a 65 5d 29 20 61 6e 64   mmap_size]) and
146c0 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c   the maximum all
146d0 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 20 6c  owed mmap size l
146e0 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 64 65  imit..** ^The de
146f0 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 63 61  fault setting ca
14700 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e 20  n be overridden 
14710 62 79 20 65 61 63 68 20 64 61 74 61 62 61 73 65  by each database
14720 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e   connection usin
14730 67 0a 2a 2a 20 65 69 74 68 65 72 20 74 68 65 20  g.** either the 
14740 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a  [PRAGMA mmap_siz
14750 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62  e] command, or b
14760 79 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  y using the.** [
14770 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41  SQLITE_FCNTL_MMA
14780 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e  P_SIZE] file con
14790 74 72 6f 6c 2e 20 20 5e 28 54 68 65 20 6d 61 78  trol.  ^(The max
147a0 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61  imum allowed mma
147b0 70 20 73 69 7a 65 0a 2a 2a 20 63 61 6e 6e 6f 74  p size.** cannot
147c0 20 62 65 20 63 68 61 6e 67 65 64 20 61 74 20 72   be changed at r
147d0 75 6e 2d 74 69 6d 65 2e 20 20 4e 6f 72 20 6d 61  un-time.  Nor ma
147e0 79 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c  y the maximum al
147f0 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a  lowed mmap size.
14800 2a 2a 20 65 78 63 65 65 64 20 74 68 65 20 63 6f  ** exceed the co
14810 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d  mpile-time maxim
14820 75 6d 20 6d 6d 61 70 20 73 69 7a 65 20 73 65 74  um mmap size set
14830 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   by the.** [SQLI
14840 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45  TE_MAX_MMAP_SIZE
14850 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
14860 70 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20  ption.)^.** ^If 
14870 65 69 74 68 65 72 20 61 72 67 75 6d 65 6e 74 20  either argument 
14880 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69  to this option i
14890 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
148a0 20 74 68 61 74 20 61 72 67 75 6d 65 6e 74 20 69   that argument i
148b0 73 0a 2a 2a 20 63 68 61 6e 67 65 64 20 74 6f 20  s.** changed to 
148c0 69 74 73 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  its compile-time
148d0 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64   default..** </d
148e0 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
148f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
14900 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20  LETHREAD  1  /* 
14910 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
14920 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
14930 54 49 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a  TITHREAD   2  /*
14940 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
14950 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
14960 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f  RIALIZED    3  /
14970 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
14980 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
14990 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20  ALLOC        4  
149a0 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  /* sqlite3_mem_m
149b0 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
149c0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
149d0 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35  _GETMALLOC     5
149e0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d    /* sqlite3_mem
149f0 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
14a00 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
14a10 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 20 20  IG_SCRATCH      
14a20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   6  /* void*, in
14a30 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23  t sz, int N */.#
14a40 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
14a50 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 20  NFIG_PAGECACHE  
14a60 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     7  /* void*, 
14a70 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f  int sz, int N */
14a80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
14a90 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20  CONFIG_HEAP     
14aa0 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a       8  /* void*
14ab0 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74  , int nByte, int
14ac0 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20   min */.#define 
14ad0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
14ae0 4d 53 54 41 54 55 53 20 20 20 20 20 39 20 20 2f  MSTATUS     9  /
14af0 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65  * boolean */.#de
14b00 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
14b10 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20  IG_MUTEX        
14b20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d  10  /* sqlite3_m
14b30 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  utex_methods* */
14b40 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
14b50 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20  CONFIG_GETMUTEX 
14b60 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74      11  /* sqlit
14b70 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
14b80 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73  * */./* previous
14b90 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ly SQLITE_CONFIG
14ba0 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77  _CHUNKALLOC 12 w
14bb0 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73  hich is now unus
14bc0 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20  ed. */ .#define 
14bd0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
14be0 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20 20 2f  OKASIDE    13  /
14bf0 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65  * int int */.#de
14c00 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
14c10 49 47 5f 50 43 41 43 48 45 20 20 20 20 20 20 20  IG_PCACHE       
14c20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a  14  /* no-op */.
14c30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
14c40 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 20  ONFIG_GETPCACHE 
14c50 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20     15  /* no-op 
14c60 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
14c70 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20  E_CONFIG_LOG    
14c80 20 20 20 20 20 20 31 36 20 20 2f 2a 20 78 46 75        16  /* xFu
14c90 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65  nc, void* */.#de
14ca0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
14cb0 49 47 5f 55 52 49 20 20 20 20 20 20 20 20 20 20  IG_URI          
14cc0 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64  17  /* int */.#d
14cd0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
14ce0 46 49 47 5f 50 43 41 43 48 45 32 20 20 20 20 20  FIG_PCACHE2     
14cf0 20 31 38 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   18  /* sqlite3_
14d00 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a  pcache_methods2*
14d10 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
14d20 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
14d30 43 48 45 32 20 20 20 31 39 20 20 2f 2a 20 73 71  CHE2   19  /* sq
14d40 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
14d50 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e  hods2* */.#defin
14d60 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14d70 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
14d80 43 41 4e 20 32 30 20 20 2f 2a 20 69 6e 74 20 2a  CAN 20  /* int *
14d90 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
14da0 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 20 20  _CONFIG_SQLLOG  
14db0 20 20 20 20 20 32 31 20 20 2f 2a 20 78 53 71 6c       21  /* xSql
14dc0 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64  log, void* */.#d
14dd0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
14de0 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20  FIG_MMAP_SIZE   
14df0 20 32 32 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   22  /* sqlite3_
14e00 69 6e 74 36 34 2c 20 73 71 6c 69 74 65 33 5f 69  int64, sqlite3_i
14e10 6e 74 36 34 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  nt64 */../*.** C
14e20 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73  API3REF: Databas
14e30 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e  e Connection Con
14e40 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f  figuration Optio
14e50 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  ns.**.** These c
14e60 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65  onstants are the
14e70 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67   available integ
14e80 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  er configuration
14e90 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a   options that.**
14ea0 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61   can be passed a
14eb0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
14ec0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71  ument to the [sq
14ed0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
14ee0 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
14ef0 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72  .** New configur
14f00 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61  ation options ma
14f10 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
14f20 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
14f30 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73   SQLite..** Exis
14f40 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ting configurati
14f50 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74  on options might
14f60 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64   be discontinued
14f70 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a  .  Applications.
14f80 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20  ** should check 
14f90 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20  the return code 
14fa0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62  from [sqlite3_db
14fb0 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61  _config()] to ma
14fc0 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20  ke sure that.** 
14fd0 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e  the call worked.
14fe0 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f    ^The [sqlite3_
14ff0 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  db_config()] int
15000 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75  erface will retu
15010 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f  rn a.** non-zero
15020 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66   [error code] if
15030 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20   a discontinued 
15040 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63  or unsupported c
15050 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
15060 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65  ion.** is invoke
15070 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  d..**.** <dl>.**
15080 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
15090 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f  NFIG_LOOKASIDE</
150a0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
150b0 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  s option takes t
150c0 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20  hree additional 
150d0 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64  arguments that d
150e0 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a  etermine the .**
150f0 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f   [lookaside memo
15100 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f  ry allocator] co
15110 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20  nfiguration for 
15120 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
15130 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54  nnection]..** ^T
15140 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
15150 74 20 28 74 68 65 20 74 68 69 72 64 20 70 61 72  t (the third par
15160 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
15170 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
15180 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  is a.** pointer 
15190 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75 66 66  to a memory buff
151a0 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f  er to use for lo
151b0 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a  okaside memory..
151c0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
151d0 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74 68 65  gument after the
151e0 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
151f0 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72 62 0a  _LOOKASIDE verb.
15200 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69  ** may be NULL i
15210 6e 20 77 68 69 63 68 20 63 61 73 65 20 53 51 4c  n which case SQL
15220 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74  ite will allocat
15230 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69  e the.** lookasi
15240 64 65 20 62 75 66 66 65 72 20 69 74 73 65 6c 66  de buffer itself
15250 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
15260 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20  malloc()]. ^The 
15270 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
15280 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f  is the.** size o
15290 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65  f each lookaside
152a0 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e   buffer slot.  ^
152b0 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
152c0 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  nt is the number
152d0 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54   of.** slots.  T
152e0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62  he size of the b
152f0 75 66 66 65 72 20 69 6e 20 74 68 65 20 66 69 72  uffer in the fir
15300 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  st argument must
15310 20 62 65 20 67 72 65 61 74 65 72 20 74 68 61 6e   be greater than
15320 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  .** or equal to 
15330 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74  the product of t
15340 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68  he second and th
15350 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 20 20  ird arguments.  
15360 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75  The buffer.** mu
15370 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f  st be aligned to
15380 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64   an 8-byte bound
15390 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20 73 65  ary.  ^If the se
153a0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
153b0 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  .** SQLITE_DBCON
153c0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73  FIG_LOOKASIDE is
153d0 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65 20   not a multiple 
153e0 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e 74 65  of 8, it is inte
153f0 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65  rnally.** rounde
15400 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65  d down to the ne
15410 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69  xt smaller multi
15420 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54 68 65  ple of 8.  ^(The
15430 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
15440 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  y.** configurati
15450 6f 6e 20 66 6f 72 20 61 20 64 61 74 61 62 61 73  on for a databas
15460 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e  e connection can
15470 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67 65 64   only be changed
15480 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f   when that.** co
15490 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20  nnection is not 
154a0 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e 67 20  currently using 
154b0 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
154c0 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72 20 77 6f  , or in other wo
154d0 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20  rds.** when the 
154e0 22 63 75 72 72 65 6e 74 20 76 61 6c 75 65 22 20  "current value" 
154f0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
15500 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75  sqlite3_db_statu
15510 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e  s](D,[SQLITE_CON
15520 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e  FIG_LOOKASIDE],.
15530 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20  ..) is zero..** 
15540 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63  Any attempt to c
15550 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73  hange the lookas
15560 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69  ide memory confi
15570 67 75 72 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f  guration when lo
15580 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72  okaside.** memor
15590 79 20 69 73 20 69 6e 20 75 73 65 20 6c 65 61 76  y is in use leav
155a0 65 73 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  es the configura
155b0 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64 20 61  tion unchanged a
155c0 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b  nd returns .** [
155d0 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c  SQLITE_BUSY].)^<
155e0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
155f0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
15600 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a  NABLE_FKEY</dt>.
15610 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
15620 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
15630 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
15640 65 20 74 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e  e the enforcemen
15650 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e  t of.** [foreign
15660 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73   key constraints
15670 5d 2e 20 20 54 68 65 72 65 20 73 68 6f 75 6c 64  ].  There should
15680 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e   be two addition
15690 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  al arguments..**
156a0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
156b0 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ent is an intege
156c0 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20  r which is 0 to 
156d0 64 69 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72  disable FK enfor
156e0 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74  cement,.** posit
156f0 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b  ive to enable FK
15700 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20   enforcement or 
15710 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76  negative to leav
15720 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
15730 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20 20  .** unchanged.  
15740 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
15750 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65  eter is a pointe
15760 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
15770 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73  into which.** is
15780 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20   written 0 or 1 
15790 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74  to indicate whet
157a0 68 65 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  her FK enforceme
157b0 6e 74 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a  nt is off or on.
157c0 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69  ** following thi
157d0 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63  s call.  The sec
157e0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61  ond parameter ma
157f0 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  y be a NULL poin
15800 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68  ter, in.** which
15810 20 63 61 73 65 20 74 68 65 20 46 4b 20 65 6e 66   case the FK enf
15820 6f 72 63 65 6d 65 6e 74 20 73 65 74 74 69 6e 67  orcement setting
15830 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64   is not reported
15840 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a   back. </dd>.**.
15850 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
15860 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52  CONFIG_ENABLE_TR
15870 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  IGGER</dt>.** <d
15880 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
15890 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c  is used to enabl
158a0 65 20 6f 72 20 64 69 73 61 62 6c 65 20 5b 43 52  e or disable [CR
158b0 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74  EATE TRIGGER | t
158c0 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65  riggers]..** The
158d0 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f  re should be two
158e0 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
158f0 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69  ments..** The fi
15900 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
15910 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  an integer which
15920 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
15930 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f   triggers,.** po
15940 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65  sitive to enable
15950 20 74 72 69 67 67 65 72 73 20 6f 72 20 6e 65 67   triggers or neg
15960 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74  ative to leave t
15970 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61  he setting uncha
15980 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63  nged..** The sec
15990 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
159a0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
159b0 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68   integer into wh
159c0 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65  ich.** is writte
159d0 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  n 0 or 1 to indi
159e0 63 61 74 65 20 77 68 65 74 68 65 72 20 74 72 69  cate whether tri
159f0 67 67 65 72 73 20 61 72 65 20 64 69 73 61 62 6c  ggers are disabl
15a00 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a  ed or enabled.**
15a10 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20   following this 
15a20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e  call.  The secon
15a30 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  d parameter may 
15a40 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  be a NULL pointe
15a50 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63  r, in.** which c
15a60 61 73 65 20 74 68 65 20 74 72 69 67 67 65 72 20  ase the trigger 
15a70 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72  setting is not r
15a80 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f  eported back. </
15a90 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a  dd>.**.** </dl>.
15aa0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
15ab0 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
15ac0 53 49 44 45 20 20 20 20 20 20 20 31 30 30 31 20  SIDE       1001 
15ad0 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e   /* void* int in
15ae0 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
15af0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
15b00 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 31 30 30  BLE_FKEY     100
15b10 32 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  2  /* int int* *
15b20 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15b30 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
15b40 5f 54 52 49 47 47 45 52 20 20 31 30 30 33 20 20  _TRIGGER  1003  
15b50 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a  /* int int* */..
15b60 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
15b70 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62   Enable Or Disab
15b80 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  le Extended Resu
15b90 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e  lt Codes.**.** ^
15ba0 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
15bb0 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
15bc0 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62  s() routine enab
15bd0 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
15be0 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64  the.** [extended
15bf0 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66   result codes] f
15c00 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65  eature of SQLite
15c10 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20  . ^The extended 
15c20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20  result.** codes 
15c30 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20  are disabled by 
15c40 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74  default for hist
15c50 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69  orical compatibi
15c60 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  lity..*/.int sql
15c70 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
15c80 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74  sult_codes(sqlit
15c90 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b  e3*, int onoff);
15ca0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
15cb0 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f  : Last Insert Ro
15cc0 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20  wid.**.** ^Each 
15cd0 65 6e 74 72 79 20 69 6e 20 61 6e 20 53 51 4c 69  entry in an SQLi
15ce0 74 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 75  te table has a u
15cf0 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 69 67  nique 64-bit sig
15d00 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b  ned.** integer k
15d10 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52  ey called the [R
15d20 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e  OWID | "rowid"].
15d30 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20 61   ^The rowid is a
15d40 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a  lways available.
15d50 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61  ** as an undecla
15d60 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64  red column named
15d70 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20   ROWID, OID, or 
15d80 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20  _ROWID_ as long 
15d90 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65  as those.** name
15da0 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75  s are not also u
15db0 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c  sed by explicitl
15dc0 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  y declared colum
15dd0 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74  ns. ^If.** the t
15de0 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d  able has a colum
15df0 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47  n of type [INTEG
15e00 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20  ER PRIMARY KEY] 
15e10 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e  then that column
15e20 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61  .** is another a
15e30 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77  lias for the row
15e40 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  id..**.** ^This 
15e50 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
15e60 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74  the [rowid] of t
15e70 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a  he most recent.*
15e80 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  * successful [IN
15e90 53 45 52 54 5d 20 69 6e 74 6f 20 74 68 65 20 64  SERT] into the d
15ea0 61 74 61 62 61 73 65 20 66 72 6f 6d 20 74 68 65  atabase from the
15eb0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
15ec0 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65  ction].** in the
15ed0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
15ee0 20 20 5e 41 73 20 6f 66 20 53 51 4c 69 74 65 20    ^As of SQLite 
15ef0 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 74  version 3.7.7, t
15f00 68 69 73 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  his routines.** 
15f10 72 65 63 6f 72 64 73 20 74 68 65 20 6c 61 73 74  records the last
15f20 20 69 6e 73 65 72 74 20 72 6f 77 69 64 20 6f 66   insert rowid of
15f30 20 62 6f 74 68 20 6f 72 64 69 6e 61 72 79 20 74   both ordinary t
15f40 61 62 6c 65 73 20 61 6e 64 20 5b 76 69 72 74 75  ables and [virtu
15f50 61 6c 20 74 61 62 6c 65 73 5d 2e 0a 2a 2a 20 5e  al tables]..** ^
15f60 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c  If no successful
15f70 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a 20 68 61   [INSERT]s.** ha
15f80 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65 64  ve ever occurred
15f90 20 6f 6e 20 74 68 61 74 20 64 61 74 61 62 61 73   on that databas
15fa0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65  e connection, ze
15fb0 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  ro is returned..
15fc0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49  **.** ^(If an [I
15fd0 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69  NSERT] occurs wi
15fe0 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 6f  thin a trigger o
15ff0 72 20 77 69 74 68 69 6e 20 61 20 5b 76 69 72 74  r within a [virt
16000 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65  ual table].** me
16010 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 69 73 20  thod, then this 
16020 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 65 74  routine will ret
16030 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20  urn the [rowid] 
16040 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a  of the inserted.
16050 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61  ** row as long a
16060 73 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72  s the trigger or
16070 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d   virtual table m
16080 65 74 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e 67  ethod is running
16090 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68  ..** But once th
160a0 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72  e trigger or vir
160b0 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f  tual table metho
160c0 64 20 65 6e 64 73 2c 20 74 68 65 20 76 61 6c 75  d ends, the valu
160d0 65 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62  e returned .** b
160e0 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  y this routine r
160f0 65 76 65 72 74 73 20 74 6f 20 77 68 61 74 20 69  everts to what i
16100 74 20 77 61 73 20 62 65 66 6f 72 65 20 74 68 65  t was before the
16110 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74   trigger or virt
16120 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65 74  ual.** table met
16130 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a  hod began.)^.**.
16140 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20  ** ^An [INSERT] 
16150 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74  that fails due t
16160 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  o a constraint v
16170 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20  iolation is not 
16180 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20  a.** successful 
16190 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65  [INSERT] and doe
161a0 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
161b0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
161c0 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  by this.** routi
161d0 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52  ne.  ^Thus INSER
161e0 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52  T OR FAIL, INSER
161f0 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53  T OR IGNORE, INS
16200 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c  ERT OR ROLLBACK,
16210 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f  .** and INSERT O
16220 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20  R ABORT make no 
16230 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72  changes to the r
16240 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
16250 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77  his.** routine w
16260 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74  hen their insert
16270 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68  ion fails.  ^(Wh
16280 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50  en INSERT OR REP
16290 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65  LACE.** encounte
162a0 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20  rs a constraint 
162b0 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f  violation, it do
162c0 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68  es not fail.  Th
162d0 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74  e.** INSERT cont
162e0 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74  inues to complet
162f0 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69  ion after deleti
16300 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75  ng rows that cau
16310 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74  sed.** the const
16320 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f  raint problem so
16330 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41   INSERT OR REPLA
16340 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63  CE will always c
16350 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74  hange.** the ret
16360 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
16370 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a  s interface.)^.*
16380 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75  *.** ^For the pu
16390 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72  rposes of this r
163a0 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45  outine, an [INSE
163b0 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65  RT] is considere
163c0 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65  d to.** be succe
163d0 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74  ssful even if it
163e0 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79   is subsequently
163f0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a   rolled back..**
16400 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
16410 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 20  n is accessible 
16420 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  to SQL statement
16430 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61  s via the.** [la
16440 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
16450 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
16460 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
16470 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66  rate thread perf
16480 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45  orms a new [INSE
16490 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a  RT] on the same.
164a0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
164b0 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65  ection while the
164c0 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
164d0 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a  nsert_rowid()].*
164e0 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  * function is ru
164f0 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63  nning and thus c
16500 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20  hanges the last 
16510 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a  insert [rowid],.
16520 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ** then the valu
16530 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  e returned by [s
16540 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
16550 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a  rt_rowid()] is.*
16560 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  * unpredictable 
16570 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71  and might not eq
16580 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f  ual either the o
16590 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a  ld or the new.**
165a0 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f   last insert [ro
165b0 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  wid]..*/.sqlite3
165c0 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c  _int64 sqlite3_l
165d0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
165e0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
165f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75  ** CAPI3REF: Cou
16600 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66  nt The Number Of
16610 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a   Rows Modified.*
16620 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
16630 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
16640 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61  number of databa
16650 73 65 20 72 6f 77 73 20 74 68 61 74 20 77 65 72  se rows that wer
16660 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20  e changed.** or 
16670 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65  inserted or dele
16680 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20  ted by the most 
16690 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74  recently complet
166a0 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
166b0 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74 61  .** on the [data
166c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
166d0 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
166e0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
166f0 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61  r..** ^(Only cha
16700 6e 67 65 73 20 74 68 61 74 20 61 72 65 20 64 69  nges that are di
16710 72 65 63 74 6c 79 20 73 70 65 63 69 66 69 65 64  rectly specified
16720 20 62 79 20 74 68 65 20 5b 49 4e 53 45 52 54 5d   by the [INSERT]
16730 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f  , [UPDATE],.** o
16740 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65  r [DELETE] state
16750 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64  ment are counted
16760 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63 68 61  .  Auxiliary cha
16770 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a  nges caused by.*
16780 2a 20 74 72 69 67 67 65 72 73 20 6f 72 20 5b 66  * triggers or [f
16790 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f  oreign key actio
167a0 6e 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e  ns] are not coun
167b0 74 65 64 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a  ted.)^ Use the.*
167c0 2a 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  * [sqlite3_total
167d0 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63  _changes()] func
167e0 74 69 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68 65  tion to find the
167f0 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66   total number of
16800 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c   changes.** incl
16810 75 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61  uding changes ca
16820 75 73 65 64 20 62 79 20 74 72 69 67 67 65 72 73  used by triggers
16830 20 61 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65 79   and foreign key
16840 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20   actions..**.** 
16850 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69  ^Changes to a vi
16860 65 77 20 74 68 61 74 20 61 72 65 20 73 69 6d 75  ew that are simu
16870 6c 61 74 65 64 20 62 79 20 61 6e 20 5b 49 4e 53  lated by an [INS
16880 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d  TEAD OF trigger]
16890 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e  .** are not coun
168a0 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20  ted.  Only real 
168b0 74 61 62 6c 65 20 63 68 61 6e 67 65 73 20 61 72  table changes ar
168c0 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a  e counted..**.**
168d0 20 5e 28 41 20 22 72 6f 77 20 63 68 61 6e 67 65   ^(A "row change
168e0 22 20 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f  " is a change to
168f0 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66   a single row of
16900 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a   a single table.
16910 2a 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e 20  ** caused by an 
16920 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20  INSERT, DELETE, 
16930 6f 72 20 55 50 44 41 54 45 20 73 74 61 74 65 6d  or UPDATE statem
16940 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a  ent.  Rows that.
16950 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20 61  ** are changed a
16960 73 20 73 69 64 65 20 65 66 66 65 63 74 73 20 6f  s side effects o
16970 66 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73  f [REPLACE] cons
16980 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f  traint resolutio
16990 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20  n,.** rollback, 
169a0 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67  ABORT processing
169b0 2c 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20  , [DROP TABLE], 
169c0 6f 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a  or by any other.
169d0 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f  ** mechanisms do
169e0 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69   not count as di
169f0 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73  rect row changes
16a00 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69  .)^.**.** A "tri
16a10 67 67 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73  gger context" is
16a20 20 61 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63   a scope of exec
16a30 75 74 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e  ution that begin
16a40 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69  s and.** ends wi
16a50 74 68 20 74 68 65 20 73 63 72 69 70 74 20 6f 66  th the script of
16a60 20 61 20 5b 43 52 45 41 54 45 20 54 52 49 47 47   a [CREATE TRIGG
16a70 45 52 20 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a  ER | trigger]. .
16a80 2a 2a 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74  ** Most SQL stat
16a90 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76  ements are.** ev
16aa0 61 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65 20  aluated outside 
16ab0 6f 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20  of any trigger. 
16ac0 20 54 68 69 73 20 69 73 20 74 68 65 20 22 74 6f   This is the "to
16ad0 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67  p level".** trig
16ae0 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66  ger context.  If
16af0 20 61 20 74 72 69 67 67 65 72 20 66 69 72 65 73   a trigger fires
16b00 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65   from the top le
16b10 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72  vel, a.** new tr
16b20 69 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73  igger context is
16b30 20 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65   entered for the
16b40 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61   duration of tha
16b50 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72  t one.** trigger
16b60 2e 20 20 53 75 62 74 72 69 67 67 65 72 73 20 63  .  Subtriggers c
16b70 72 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74  reate subcontext
16b80 73 20 66 6f 72 20 74 68 65 69 72 20 64 75 72 61  s for their dura
16b90 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  tion..**.** ^Cal
16ba0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78  ling [sqlite3_ex
16bb0 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ec()] or [sqlite
16bc0 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72 73  3_step()] recurs
16bd0 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f  ively does.** no
16be0 74 20 63 72 65 61 74 65 20 61 20 6e 65 77 20 74  t create a new t
16bf0 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a  rigger context..
16c00 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
16c10 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
16c20 20 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63   number of direc
16c30 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e  t row changes in
16c40 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63   the.** most rec
16c50 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ent INSERT, UPDA
16c60 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74  TE, or DELETE st
16c70 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74  atement within t
16c80 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67  he same.** trigg
16c90 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a  er context..**.*
16ca0 2a 20 5e 54 68 75 73 2c 20 77 68 65 6e 20 63 61  * ^Thus, when ca
16cb0 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f  lled from the to
16cc0 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75  p level, this fu
16cd0 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
16ce0 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
16cf0 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d  changes in the m
16d00 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52  ost recent INSER
16d10 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
16d20 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73  LETE.** that als
16d30 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20 74 68  o occurred at th
16d40 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28  e top level.  ^(
16d50 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20  Within the body 
16d60 6f 66 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a  of a trigger,.**
16d70 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61   the sqlite3_cha
16d80 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61 63 65  nges() interface
16d90 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74   can be called t
16da0 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65  o find the numbe
16db0 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20  r of.** changes 
16dc0 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  in the most rece
16dd0 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49  ntly completed I
16de0 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
16df0 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74  r DELETE.** stat
16e00 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65  ement within the
16e10 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d   body of the sam
16e20 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f  e trigger..** Ho
16e30 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65  wever, the numbe
16e40 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20  r returned does 
16e50 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e  not include chan
16e60 67 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79  ges.** caused by
16e70 20 73 75 62 74 72 69 67 67 65 72 73 20 73 69 6e   subtriggers sin
16e80 63 65 20 74 68 6f 73 65 20 68 61 76 65 20 74 68  ce those have th
16e90 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e  eir own context.
16ea0 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )^.**.** See als
16eb0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74  o the [sqlite3_t
16ec0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
16ed0 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a  interface, the.*
16ee0 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73  * [count_changes
16ef0 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68   pragma], and th
16f00 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c  e [changes() SQL
16f10 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a   function]..**.*
16f20 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
16f30 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
16f40 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
16f50 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
16f60 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73  tion.** while [s
16f70 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
16f80 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  ] is running the
16f90 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
16fa0 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65  rned.** is unpre
16fb0 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74  dictable and not
16fc0 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a   meaningful..*/.
16fd0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  int sqlite3_chan
16fe0 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
16ff0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
17000 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20  Total Number Of 
17010 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a  Rows Modified.**
17020 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
17030 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
17040 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61  umber of row cha
17050 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b  nges caused by [
17060 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44  INSERT],.** [UPD
17070 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d  ATE] or [DELETE]
17080 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63   statements sinc
17090 65 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  e the [database 
170a0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20  connection] was 
170b0 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65  opened..** ^(The
170c0 20 63 6f 75 6e 74 20 72 65 74 75 72 6e 65 64 20   count returned 
170d0 62 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  by sqlite3_total
170e0 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 63 6c 75  _changes() inclu
170f0 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a  des all changes.
17100 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45  ** from all [CRE
17110 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72  ATE TRIGGER | tr
17120 69 67 67 65 72 5d 20 63 6f 6e 74 65 78 74 73 20  igger] contexts 
17130 61 6e 64 20 63 68 61 6e 67 65 73 20 6d 61 64 65  and changes made
17140 20 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20   by.** [foreign 
17150 6b 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f  key actions]. Ho
17160 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f  wever,.** the co
17170 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  unt does not inc
17180 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75 73 65  lude changes use
17190 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b  d to implement [
171a0 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61  REPLACE] constra
171b0 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c  ints,.** do roll
171c0 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70  backs or ABORT p
171d0 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44  rocessing, or [D
171e0 52 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f 63 65  ROP TABLE] proce
171f0 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63  ssing.  The.** c
17200 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e  ount does not in
17210 63 6c 75 64 65 20 72 6f 77 73 20 6f 66 20 76 69  clude rows of vi
17220 65 77 73 20 74 68 61 74 20 66 69 72 65 20 61 6e  ews that fire an
17230 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69   [INSTEAD OF tri
17240 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68  gger],.** though
17250 20 69 66 20 74 68 65 20 49 4e 53 54 45 41 44 20   if the INSTEAD 
17260 4f 46 20 74 72 69 67 67 65 72 20 6d 61 6b 65 73  OF trigger makes
17270 20 63 68 61 6e 67 65 73 20 6f 66 20 69 74 73 20   changes of its 
17280 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e 67  own, those chang
17290 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74  es .** are count
172a0 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71  ed.)^.** ^The sq
172b0 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
172c0 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 63  ges() function c
172d0 6f 75 6e 74 73 20 74 68 65 20 63 68 61 6e 67 65  ounts the change
172e0 73 20 61 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20  s as soon as.** 
172f0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68  the statement th
17300 61 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73  at makes them is
17310 20 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e   completed (when
17320 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
17330 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73  andle.** is pass
17340 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ed to [sqlite3_r
17350 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
17360 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29  te3_finalize()])
17370 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
17380 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68   the [sqlite3_ch
17390 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61  anges()] interfa
173a0 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e  ce, the.** [coun
173b0 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61  t_changes pragma
173c0 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61  ], and the [tota
173d0 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20  l_changes() SQL 
173e0 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
173f0 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
17400 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
17410 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
17420 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
17430 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71  ion.** while [sq
17440 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
17450 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
17460 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
17470 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20  .** returned is 
17480 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
17490 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
174a0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
174b0 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73  _total_changes(s
174c0 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
174d0 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72   CAPI3REF: Inter
174e0 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e  rupt A Long-Runn
174f0 69 6e 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20  ing Query.**.** 
17500 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63  ^This function c
17510 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e  auses any pendin
17520 67 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61  g database opera
17530 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e  tion to abort an
17540 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69  d.** return at i
17550 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f  ts earliest oppo
17560 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f  rtunity. This ro
17570 75 74 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c  utine is typical
17580 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20  ly.** called in 
17590 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73  response to a us
175a0 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61  er action such a
175b0 73 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63  s pressing "Canc
175c0 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43  el".** or Ctrl-C
175d0 20 77 68 65 72 65 20 74 68 65 20 75 73 65 72 20   where the user 
175e0 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65  wants a long que
175f0 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20  ry operation to 
17600 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74  halt.** immediat
17610 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69  ely..**.** ^It i
17620 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74  s safe to call t
17630 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d  his routine from
17640 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65 72   a thread differ
17650 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20  ent from the.** 
17660 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20 63  thread that is c
17670 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67  urrently running
17680 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 70   the database op
17690 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74  eration.  But it
176a0 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20  .** is not safe 
176b0 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75  to call this rou
176c0 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74  tine with a [dat
176d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
176e0 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f  ] that.** is clo
176f0 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f  sed or might clo
17700 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65  se before sqlite
17710 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65  3_interrupt() re
17720 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  turns..**.** ^If
17730 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f   an SQL operatio
17740 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79  n is very nearly
17750 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65   finished at the
17760 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71   time when.** sq
17770 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
17780 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65  ) is called, the
17790 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68  n it might not h
177a0 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69  ave an opportuni
177b0 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65  ty.** to be inte
177c0 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68  rrupted and migh
177d0 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f  t continue to co
177e0 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  mpletion..**.** 
177f0 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f  ^An SQL operatio
17800 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72  n that is interr
17810 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72  upted will retur
17820 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  n [SQLITE_INTERR
17830 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  UPT]..** ^If the
17840 20 69 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c   interrupted SQL
17850 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e   operation is an
17860 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
17870 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68   or DELETE.** th
17880 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20  at is inside an 
17890 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
178a0 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65  tion, then the e
178b0 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f  ntire transactio
178c0 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c  n.** will be rol
178d0 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74  led back automat
178e0 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ically..**.** ^T
178f0 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
17900 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20  rupt(D) call is 
17910 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20  in effect until 
17920 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75  all currently ru
17930 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61  nning.** SQL sta
17940 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61  tements on [data
17950 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
17960 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41   D complete.  ^A
17970 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65  ny new SQL state
17980 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
17990 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
179a0 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
179b0 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64  rrupt() call and
179c0 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20   before the .** 
179d0 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e  running statemen
179e0 74 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20  ts reaches zero 
179f0 61 72 65 20 69 6e 74 65 72 72 75 70 74 65 64 20  are interrupted 
17a00 61 73 20 69 66 20 74 68 65 79 20 68 61 64 20 62  as if they had b
17a10 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70  een.** running p
17a20 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69  rior to the sqli
17a30 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
17a40 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20  call.  ^New SQL 
17a50 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
17a60 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
17a70 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67  fter the running
17a80 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74   statement count
17a90 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72   reaches zero ar
17aa0 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65  e.** not effecte
17ab0 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33  d by the sqlite3
17ac0 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a  _interrupt()..**
17ad0 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69   ^A call to sqli
17ae0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29  te3_interrupt(D)
17af0 20 74 68 61 74 20 6f 63 63 75 72 73 20 77 68 65   that occurs whe
17b00 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72  n there are no r
17b10 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74  unning.** SQL st
17b20 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f  atements is a no
17b30 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65  -op and has no e
17b40 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61  ffect on SQL sta
17b50 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20  tements.** that 
17b60 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65  are started afte
17b70 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  r the sqlite3_in
17b80 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72  terrupt() call r
17b90 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66  eturns..**.** If
17ba0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
17bb0 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20  nnection closes 
17bc0 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69  while [sqlite3_i
17bd0 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69  nterrupt()].** i
17be0 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62  s running then b
17bf0 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c  ad things will l
17c00 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f  ikely happen..*/
17c10 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e  .void sqlite3_in
17c20 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a  terrupt(sqlite3*
17c30 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
17c40 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
17c50 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
17c60 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a  t Is Complete.**
17c70 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
17c80 65 73 20 61 72 65 20 75 73 65 66 75 6c 20 64 75  es are useful du
17c90 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e  ring command-lin
17ca0 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72  e input to deter
17cb0 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63  mine if the.** c
17cc0 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64  urrently entered
17cd0 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66   text seems to f
17ce0 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53  orm a complete S
17cf0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a  QL statement or.
17d00 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c  ** if additional
17d10 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64   input is needed
17d20 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20   before sending 
17d30 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a  the text into.**
17d40 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73   SQLite for pars
17d50 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75  ing.  ^These rou
17d60 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69  tines return 1 i
17d70 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  f the input stri
17d80 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f  ng.** appears to
17d90 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53   be a complete S
17da0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  QL statement.  ^
17db0 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a  A statement is j
17dc0 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63  udged to be.** c
17dd0 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e  omplete if it en
17de0 64 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f  ds with a semico
17df0 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73  lon token and is
17e00 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66   not a prefix of
17e10 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65   a.** well-forme
17e20 64 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52  d CREATE TRIGGER
17e30 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65   statement.  ^Se
17e40 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72  micolons that ar
17e50 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69  e embedded withi
17e60 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65  n.** string lite
17e70 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69  rals or quoted i
17e80 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20  dentifier names 
17e90 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20  or comments are 
17ea0 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65  not.** independe
17eb0 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20  nt tokens (they 
17ec0 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20  are part of the 
17ed0 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74  token in which t
17ee0 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64  hey are.** embed
17ef0 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f  ded) and thus do
17f00 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20   not count as a 
17f10 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e  statement termin
17f20 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61  ator.  ^Whitespa
17f30 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e  ce.** and commen
17f40 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74  ts that follow t
17f50 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c  he final semicol
17f60 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a  on are ignored..
17f70 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
17f80 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69  tines return 0 i
17f90 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
17fa0 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20  is incomplete.  
17fb0 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ^If a.** memory 
17fc0 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73  allocation fails
17fd0 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f  , then SQLITE_NO
17fe0 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  MEM is returned.
17ff0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
18000 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61  utines do not pa
18010 72 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74  rse the SQL stat
18020 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77  ements thus.** w
18030 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73  ill not detect s
18040 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63  yntactically inc
18050 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a  orrect SQL..**.*
18060 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61  * ^(If SQLite ha
18070 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69  s not been initi
18080 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71  alized using [sq
18090 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
180a0 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f  ()] prior .** to
180b0 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65   invoking sqlite
180c0 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74  3_complete16() t
180d0 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  hen sqlite3_init
180e0 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
180f0 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63  ked.** automatic
18100 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ally by sqlite3_
18110 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49  complete16().  I
18120 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a  f that initializ
18130 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20  ation fails,.** 
18140 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20  then the return 
18150 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
18160 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20  e3_complete16() 
18170 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f  will be non-zero
18180 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f  .** regardless o
18190 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
181a0 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69   the input SQL i
181b0 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a  s complete.)^.**
181c0 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f  .** The input to
181d0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
181e0 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20  te()] must be a 
181f0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
18200 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e  ** UTF-8 string.
18210 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74  .**.** The input
18220 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d   to [sqlite3_com
18230 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20  plete16()] must 
18240 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  be a zero-termin
18250 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73  ated.** UTF-16 s
18260 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20  tring in native 
18270 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69  byte order..*/.i
18280 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  nt sqlite3_compl
18290 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ete(const char *
182a0 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  sql);.int sqlite
182b0 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e  3_complete16(con
182c0 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a  st void *sql);..
182d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
182e0 52 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62  Register A Callb
182f0 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51  ack To Handle SQ
18300 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73  LITE_BUSY Errors
18310 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
18320 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c  tine sets a call
18330 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68  back function th
18340 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f  at might be invo
18350 6b 65 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20  ked whenever.** 
18360 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61  an attempt is ma
18370 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74  de to open a dat
18380 61 62 61 73 65 20 74 61 62 6c 65 20 74 68 61 74  abase table that
18390 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a   another thread.
183a0 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61  ** or process ha
183b0 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20  s locked..**.** 
183c0 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c  ^If the busy cal
183d0 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74  lback is NULL, t
183e0 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  hen [SQLITE_BUSY
183f0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  ] or [SQLITE_IOE
18400 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69  RR_BLOCKED].** i
18410 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64  s returned immed
18420 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f  iately upon enco
18430 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63  untering the loc
18440 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79  k.  ^If the busy
18450 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20   callback.** is 
18460 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74  not NULL, then t
18470 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68  he callback migh
18480 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74  t be invoked wit
18490 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e  h two arguments.
184a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
184b0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
184c0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  e busy handler i
184d0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
184e0 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68  void* pointer wh
184f0 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68  ich.** is the th
18500 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ird argument to 
18510 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
18520 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65  dler().  ^The se
18530 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
18540 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e  .** the busy han
18550 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  dler callback is
18560 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74   the number of t
18570 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75  imes that the bu
18580 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a  sy handler has.*
18590 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66  * been invoked f
185a0 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20  or this locking 
185b0 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a  event.  ^If the.
185c0 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  ** busy callback
185d0 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e   returns 0, then
185e0 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61   no additional a
185f0 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65  ttempts are made
18600 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68   to.** access th
18610 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b  e database and [
18620 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20  SQLITE_BUSY] or 
18630 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
18640 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e  OCKED] is return
18650 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63  ed..** ^If the c
18660 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
18670 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61  non-zero, then a
18680 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a  nother attempt.*
18690 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65  * is made to ope
186a0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
186b0 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74  or reading and t
186c0 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73  he cycle repeats
186d0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73  ..**.** The pres
186e0 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68  ence of a busy h
186f0 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20  andler does not 
18700 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69  guarantee that i
18710 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65  t will be invoke
18720 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20  d.** when there 
18730 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69  is lock contenti
18740 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64  on. ^If SQLite d
18750 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69  etermines that i
18760 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79  nvoking the busy
18770 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c  .** handler coul
18780 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65  d result in a de
18790 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20  adlock, it will 
187a0 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74  go ahead and ret
187b0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  urn [SQLITE_BUSY
187c0 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ].** or [SQLITE_
187d0 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69  IOERR_BLOCKED] i
187e0 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69  nstead of invoki
187f0 6e 67 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ng the busy hand
18800 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72  ler..** Consider
18810 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72   a scenario wher
18820 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73  e one process is
18830 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20   holding a read 
18840 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20  lock that.** it 
18850 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f  is trying to pro
18860 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76  mote to a reserv
18870 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61  ed lock and.** a
18880 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
18890 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73  is holding a res
188a0 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20  erved lock that 
188b0 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20  it is trying.** 
188c0 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e  to promote to an
188d0 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e   exclusive lock.
188e0 20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63    The first proc
188f0 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65  ess cannot proce
18900 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74  ed.** because it
18910 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74   is blocked by t
18920 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68  he second and th
18930 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  e second process
18940 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65   cannot.** proce
18950 65 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73  ed because it is
18960 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20   blocked by the 
18970 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20  first.  If both 
18980 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76  processes.** inv
18990 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e  oke the busy han
189a0 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77  dlers, neither w
189b0 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f  ill make any pro
189c0 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72  gress.  Therefor
189d0 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74  e,.** SQLite ret
189e0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53  urns [SQLITE_BUS
189f0 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  Y] for the first
18a00 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67   process, hoping
18a10 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69   that this.** wi
18a20 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69  ll induce the fi
18a30 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72  rst process to r
18a40 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20  elease its read 
18a50 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a  lock and allow.*
18a60 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f  * the second pro
18a70 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e  cess to proceed.
18a80 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61  .**.** ^The defa
18a90 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63  ult busy callbac
18aa0 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  k is NULL..**.**
18ab0 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55   ^The [SQLITE_BU
18ac0 53 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e  SY] error is con
18ad0 76 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54  verted to [SQLIT
18ae0 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
18af0 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20  .** when SQLite 
18b00 69 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65  is in the middle
18b10 20 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e   of a large tran
18b20 73 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c  saction where al
18b30 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73  l the.** changes
18b40 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e   will not fit in
18b50 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79  to the in-memory
18b60 20 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20   cache.  SQLite 
18b70 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20  will.** already 
18b80 68 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44 20  hold a RESERVED 
18b90 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61  lock on the data
18ba0 62 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69  base file, but i
18bb0 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72  t needs.** to pr
18bc0 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20  omote this lock 
18bd0 74 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20  to EXCLUSIVE so 
18be0 74 68 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c  that it can spil
18bf0 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73  l cache.** pages
18c00 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61   into the databa
18c10 73 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20  se file without 
18c20 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65  harm to concurre
18c30 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20  nt.** readers.  
18c40 5e 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65  ^If it is unable
18c50 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20   to promote the 
18c60 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69  lock, then the i
18c70 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68  n-memory.** cach
18c80 65 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69  e will be left i
18c90 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e  n an inconsisten
18ca0 74 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74  t state and so t
18cb0 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65  he error.** code
18cc0 20 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f   is promoted fro
18cd0 6d 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79  m the relatively
18ce0 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f   benign [SQLITE_
18cf0 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20  BUSY] to.** the 
18d00 6d 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c  more severe [SQL
18d10 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
18d20 44 5d 2e 20 20 5e 54 68 69 73 20 65 72 72 6f 72  D].  ^This error
18d30 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a   code promotion.
18d40 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74  ** forces an aut
18d50 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20  omatic rollback 
18d60 6f 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20  of the changes. 
18d70 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68   See the.** <a h
18d80 72 65 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 69  ref="/cvstrac/wi
18d90 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46  ki?p=CorruptionF
18da0 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f  ollowingBusyErro
18db0 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f  r">.** Corruptio
18dc0 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72  nFollowingBusyEr
18dd0 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67  ror</a> wiki pag
18de0 65 20 66 6f 72 20 61 20 64 69 73 63 75 73 73 69  e for a discussi
18df0 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69  on of why.** thi
18e00 73 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a  s is important..
18e10 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61  **.** ^(There ca
18e20 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67  n only be a sing
18e30 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
18e40 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68  defined for each
18e50 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
18e60 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74  nnection].  Sett
18e70 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68  ing a new busy h
18e80 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e  andler clears an
18e90 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  y.** previously 
18ea0 73 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20  set handler.)^  
18eb0 5e 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69  ^Note that calli
18ec0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ng [sqlite3_busy
18ed0 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77  _timeout()].** w
18ee0 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20  ill also set or 
18ef0 63 6c 65 61 72 20 74 68 65 20 62 75 73 79 20 68  clear the busy h
18f00 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  andler..**.** Th
18f10 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  e busy callback 
18f20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20  should not take 
18f30 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63  any actions whic
18f40 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20  h modify the.** 
18f50 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
18f60 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
18f70 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
18f80 72 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74  r.  Any such act
18f90 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69  ions.** result i
18fa0 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61  n undefined beha
18fb0 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62  vior..** .** A b
18fc0 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74  usy handler must
18fd0 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64   not close the d
18fe0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
18ff0 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72  on.** or [prepar
19000 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
19010 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62  at invoked the b
19020 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a  usy handler..*/.
19030 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
19040 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
19050 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c  *, int(*)(void*,
19060 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  int), void*);../
19070 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
19080 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75  et A Busy Timeou
19090 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  t.**.** ^This ro
190a0 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71  utine sets a [sq
190b0 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
190c0 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65  er | busy handle
190d0 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a  r] that sleeps.*
190e0 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65  * for a specifie
190f0 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65  d amount of time
19100 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73   when a table is
19110 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68   locked.  ^The h
19120 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73  andler.** will s
19130 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69  leep multiple ti
19140 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61  mes until at lea
19150 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63  st "ms" millisec
19160 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67  onds of sleeping
19170 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c  .** have accumul
19180 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74  ated.  ^After at
19190 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c   least "ms" mill
191a0 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
191b0 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e  ping,.** the han
191c0 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77  dler returns 0 w
191d0 68 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c  hich causes [sql
191e0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20  ite3_step()] to 
191f0 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54  return.** [SQLIT
19200 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49  E_BUSY] or [SQLI
19210 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
19220 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  ]..**.** ^Callin
19230 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  g this routine w
19240 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20  ith an argument 
19250 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75  less than or equ
19260 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75  al to zero.** tu
19270 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79  rns off all busy
19280 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a   handlers..**.**
19290 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c   ^(There can onl
192a0 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75  y be a single bu
192b0 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61  sy handler for a
192c0 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b   particular.** [
192d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
192e0 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69 76  ion] any any giv
192f0 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61  en moment.  If a
19300 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64  nother busy hand
19310 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e  ler.** was defin
19320 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69  ed  (using [sqli
19330 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
19340 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61  ()]) prior to ca
19350 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f  lling.** this ro
19360 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65  utine, that othe
19370 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  r busy handler i
19380 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a  s cleared.)^.*/.
19390 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
193a0 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33  _timeout(sqlite3
193b0 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a  *, int ms);../*.
193c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
193d0 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65  venience Routine
193e0 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75  s For Running Qu
193f0 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73  eries.**.** This
19400 20 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74   is a legacy int
19410 65 72 66 61 63 65 20 74 68 61 74 20 69 73 20 70  erface that is p
19420 72 65 73 65 72 76 65 64 20 66 6f 72 20 62 61 63  reserved for bac
19430 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
19440 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20  lity..** Use of 
19450 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69  this interface i
19460 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65  s not recommende
19470 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74  d..**.** Definit
19480 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74  ion: A <b>result
19490 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65   table</b> is me
194a0 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74  mory data struct
194b0 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74  ure created by t
194c0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67  he.** [sqlite3_g
194d0 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65  et_table()] inte
194e0 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74  rface.  A result
194f0 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74   table records t
19500 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71  he.** complete q
19510 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f  uery results fro
19520 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75  m one or more qu
19530 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  eries..**.** The
19540 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61   table conceptua
19550 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72  lly has a number
19560 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c   of rows and col
19570 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68  umns.  But.** th
19580 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20  ese numbers are 
19590 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20  not part of the 
195a0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73  result table its
195b0 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e  elf.  These.** n
195c0 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69  umbers are obtai
195d0 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20  ned separately. 
195e0 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75   Let N be the nu
195f0 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20  mber of rows.** 
19600 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d  and M be the num
19610 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a  ber of columns..
19620 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  **.** A result t
19630 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79  able is an array
19640 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20   of pointers to 
19650 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
19660 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a  UTF-8 strings..*
19670 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31  * There are (N+1
19680 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20  )*M elements in 
19690 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20  the array.  The 
196a0 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73  first M pointers
196b0 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72   point.** to zer
196c0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
196d0 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61  ings that  conta
196e0 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20  in the names of 
196f0 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20  the columns..** 
19700 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e  The remaining en
19710 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20  tries all point 
19720 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  to query results
19730 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72  .  NULL values r
19740 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c  esult.** in NULL
19750 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20   pointers.  All 
19760 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65  other values are
19770 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20   in their UTF-8 
19780 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
19790 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73  ** string repres
197a0 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75  entation as retu
197b0 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
197c0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e  _column_text()].
197d0 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  .**.** A result 
197e0 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73  table might cons
197f0 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f  ist of one or mo
19800 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  re memory alloca
19810 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20  tions..** It is 
19820 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73  not safe to pass
19830 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   a result table 
19840 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c  directly to [sql
19850 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
19860 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
19870 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f  should be deallo
19880 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  cated using [sql
19890 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
198a0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61  )]..**.** ^(As a
198b0 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65  n example of the
198c0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f   result table fo
198d0 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20  rmat, suppose a 
198e0 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20  query result.** 
198f0 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  is as follows:.*
19900 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
19910 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20  ><pre>.**       
19920 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41   Name        | A
19930 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d  ge.**        ---
19940 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
19950 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41  ----.**        A
19960 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a  lice       | 43.
19970 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20  **        Bob   
19980 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20        | 28.**   
19990 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20       Cindy      
199a0 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c   | 21.** </pre><
199b0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
199c0 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f  ** There are two
199d0 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61   column (M==2) a
199e0 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e  nd three rows (N
199f0 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a  ==3).  Thus the.
19a00 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  ** result table 
19a10 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20  has 8 entries.  
19a20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75  Suppose the resu
19a30 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72  lt table is stor
19a40 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61  ed.** in an arra
19a50 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74  y names azResult
19a60 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74  .  Then azResult
19a70 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74   holds this cont
19a80 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ent:.**.** <bloc
19a90 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
19aa0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
19ab0 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b  #91;0] = "Name";
19ac0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
19ad0 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67  ult&#91;1] = "Ag
19ae0 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
19af0 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20  Result&#91;2] = 
19b00 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20  "Alice";.**     
19b10 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
19b20 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20  3] = "43";.**   
19b30 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
19b40 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a  1;4] = "Bob";.**
19b50 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
19b60 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a  &#91;5] = "28";.
19b70 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
19b80 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e  lt&#91;6] = "Cin
19b90 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  dy";.**        a
19ba0 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d  zResult&#91;7] =
19bb0 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e   "21";.** </pre>
19bc0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
19bd0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
19be0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66  e3_get_table() f
19bf0 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65  unction evaluate
19c00 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a  s one or more.**
19c10 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72   semicolon-separ
19c20 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  ated SQL stateme
19c30 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d  nts in the zero-
19c40 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
19c50 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74  .** string of it
19c60 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  s 2nd parameter 
19c70 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72 65  and returns a re
19c80 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68  sult table to th
19c90 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76  e.** pointer giv
19ca0 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61  en in its 3rd pa
19cb0 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41  rameter..**.** A
19cc0 66 74 65 72 20 74 68 65 20 61 70 70 6c 69 63 61  fter the applica
19cd0 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65  tion has finishe
19ce0 64 20 77 69 74 68 20 74 68 65 20 72 65 73 75 6c  d with the resul
19cf0 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67  t from sqlite3_g
19d00 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69  et_table(),.** i
19d10 74 20 6d 75 73 74 20 70 61 73 73 20 74 68 65 20  t must pass the 
19d20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69  result table poi
19d30 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  nter to sqlite3_
19d40 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20  free_table() in 
19d50 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65  order to.** rele
19d60 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74  ase the memory t
19d70 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64  hat was malloced
19d80 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68  .  Because of th
19d90 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71  e way the.** [sq
19da0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
19db0 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73  happens within s
19dc0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
19dd0 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a  (), the calling.
19de0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ** function must
19df0 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c   not try to call
19e00 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
19e10 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c  ] directly.  Onl
19e20 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  y.** [sqlite3_fr
19e30 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61  ee_table()] is a
19e40 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74  ble to release t
19e50 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72  he memory proper
19e60 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a  ly and safely..*
19e70 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
19e80 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74  _get_table() int
19e90 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d  erface is implem
19ea0 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70  ented as a wrapp
19eb0 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71  er around.** [sq
19ec0 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20  lite3_exec()].  
19ed0 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
19ee0 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20  table() routine 
19ef0 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63  does not have ac
19f00 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69  cess.** to any i
19f10 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72  nternal data str
19f20 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74  uctures of SQLit
19f30 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79  e.  It uses only
19f40 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69   the public.** i
19f50 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64  nterface defined
19f60 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e   here.  As a con
19f70 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73  sequence, errors
19f80 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74   that occur in t
19f90 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61  he.** wrapper la
19fa0 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74  yer outside of t
19fb0 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c  he internal [sql
19fc0 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c  ite3_exec()] cal
19fd0 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66  l are not.** ref
19fe0 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71  lected in subseq
19ff0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73  uent calls to [s
1a000 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
1a010 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
1a020 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69  _errmsg()]..*/.i
1a030 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  nt sqlite3_get_t
1a040 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20  able(.  sqlite3 
1a050 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a  *db,          /*
1a060 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
1a070 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
1a080 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20  r *zSql,     /* 
1a090 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61  SQL to be evalua
1a0a0 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ted */.  char **
1a0b0 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f  *pazResult,    /
1a0c0 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65  * Results of the
1a0d0 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20   query */.  int 
1a0e0 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20  *pnRow,         
1a0f0 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72    /* Number of r
1a100 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74  esult rows writt
1a110 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74  en here */.  int
1a120 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20   *pnColumn,     
1a130 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
1a140 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77  result columns w
1a150 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20  ritten here */. 
1a160 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67   char **pzErrmsg
1a170 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20         /* Error 
1a180 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65  msg written here
1a190 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69   */.);.void sqli
1a1a0 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63  te3_free_table(c
1a1b0 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a  har **result);..
1a1c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1a1d0 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67  Formatted String
1a1e0 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69   Printing Functi
1a1f0 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
1a200 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72  routines are wor
1a210 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20  k-alikes of the 
1a220 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c  "printf()" famil
1a230 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  y of functions.*
1a240 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  * from the stand
1a250 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a  ard C library..*
1a260 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1a270 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20  3_mprintf() and 
1a280 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
1a290 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74  () routines writ
1a2a0 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c  e their.** resul
1a2b0 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  ts into memory o
1a2c0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
1a2d0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
1a2e0 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20  .** The strings 
1a2f0 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73  returned by thes
1a300 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73  e two routines s
1a310 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65  hould be.** rele
1a320 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ased by [sqlite3
1a330 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68  _free()].  ^Both
1a340 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
1a350 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
1a360 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d  er if [sqlite3_m
1a370 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62  alloc()] is unab
1a380 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65  le to allocate e
1a390 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20  nough.** memory 
1a3a0 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75  to hold the resu
1a3b0 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a  lting string..**
1a3c0 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
1a3d0 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75  3_snprintf() rou
1a3e0 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20  tine is similar 
1a3f0 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20  to "snprintf()" 
1a400 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e  from.** the stan
1a410 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20  dard C library. 
1a420 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77   The result is w
1a430 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a  ritten into the.
1a440 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69  ** buffer suppli
1a450 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
1a460 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65   parameter whose
1a470 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62   size is given b
1a480 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70  y.** the first p
1a490 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74  arameter. Note t
1a4a0 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66  hat the order of
1a4b0 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77   the.** first tw
1a4c0 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20  o parameters is 
1a4d0 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e  reversed from sn
1a4e0 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69  printf().)^  Thi
1a4f0 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f  s is an.** histo
1a500 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74  rical accident t
1a510 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69  hat cannot be fi
1a520 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61  xed without brea
1a530 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64  king.** backward
1a540 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  s compatibility.
1a550 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68    ^(Note also th
1a560 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  at sqlite3_snpri
1a570 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73  ntf().** returns
1a580 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74   a pointer to it
1a590 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64  s buffer instead
1a5a0 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
1a5b0 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  f.** characters 
1a5c0 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e  actually written
1a5d0 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72   into the buffer
1a5e0 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68  .)^  We admit th
1a5f0 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  at.** the number
1a600 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77   of characters w
1a610 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20  ritten would be 
1a620 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65  a more useful re
1a630 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75  turn.** value bu
1a640 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e  t we cannot chan
1a650 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ge the implement
1a660 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
1a670 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e  _snprintf().** n
1a680 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ow without break
1a690 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  ing compatibilit
1a6a0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e  y..**.** ^As lon
1a6b0 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20  g as the buffer 
1a6c0 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20  size is greater 
1a6d0 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74  than zero, sqlit
1a6e0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
1a6f0 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
1a700 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61   the buffer is a
1a710 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69  lways zero-termi
1a720 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72  nated.  ^The fir
1a730 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  st.** parameter 
1a740 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c  "n" is the total
1a750 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66   size of the buf
1a760 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73  fer, including s
1a770 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  pace for.** the 
1a780 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
1a790 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74    So the longest
1a7a0 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e   string that can
1a7b0 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a   be completely.*
1a7c0 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62  * written will b
1a7d0 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73  e n-1 characters
1a7e0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1a7f0 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29  ite3_vsnprintf()
1a800 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61   routine is a va
1a810 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66  rargs version of
1a820 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1a830 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  f()..**.** These
1a840 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d   routines all im
1a850 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64  plement some add
1a860 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69  itional formatti
1a870 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68  ng.** options th
1a880 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f  at are useful fo
1a890 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53  r constructing S
1a8a0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
1a8b0 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75  * All of the usu
1a8c0 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d  al printf() form
1a8d0 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61  atting options a
1a8e0 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69  pply.  In additi
1a8f0 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20  on, there.** is 
1a900 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20  are "%q", "%Q", 
1a910 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73  and "%z" options
1a920 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71  ..**.** ^(The %q
1a930 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
1a940 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74  ke %s in that it
1a950 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e   substitutes a n
1a960 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ul-terminated.**
1a970 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65   string from the
1a980 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20   argument list. 
1a990 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75   But %q also dou
1a9a0 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20  bles every '\'' 
1a9b0 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71  character..** %q
1a9c0 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72   is designed for
1a9d0 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74   use inside a st
1a9e0 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20  ring literal.)^ 
1a9f0 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63   By doubling eac
1aa00 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63  h '\''.** charac
1aa10 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74  ter it escapes t
1aa20 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e  hat character an
1aa30 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62  d allows it to b
1aa40 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a  e inserted into.
1aa50 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a  ** the string..*
1aa60 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65  *.** For example
1aa70 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72  , assume the str
1aa80 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65  ing variable zTe
1aa90 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74  xt contains text
1aaa0 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
1aab0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1aac0 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
1aad0 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68  Text = "It's a h
1aae0 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c  appy day!";.** <
1aaf0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1ab00 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e  e>.**.** One can
1ab10 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69   use this text i
1ab20 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
1ab30 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  nt as follows:.*
1ab40 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1ab50 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
1ab60 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f  *zSQL = sqlite3_
1ab70 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20  mprintf("INSERT 
1ab80 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45  INTO table VALUE
1ab90 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29  S('%q')", zText)
1aba0 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78  ;.**  sqlite3_ex
1abb0 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20  ec(db, zSQL, 0, 
1abc0 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  0, 0);.**  sqlit
1abd0 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a  e3_free(zSQL);.*
1abe0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1abf0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61  uote>.**.** Beca
1ac00 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61  use the %q forma
1ac10 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64  t string is used
1ac20 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61  , the '\'' chara
1ac30 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a  cter in zText.**
1ac40 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20   is escaped and 
1ac50 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65  the SQL generate
1ac60 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  d is as follows:
1ac70 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1ac80 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
1ac90 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
1aca0 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20  VALUES('It''s a 
1acb0 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20  happy day!').** 
1acc0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1acd0 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  te>.**.** This i
1ace0 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20  s correct.  Had 
1acf0 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65  we used %s inste
1ad00 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65  ad of %q, the ge
1ad10 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77  nerated SQL.** w
1ad20 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64  ould have looked
1ad30 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
1ad40 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1ad50 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49  re>.**  INSERT I
1ad60 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45  NTO table1 VALUE
1ad70 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20  S('It's a happy 
1ad80 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65  day!');.** </pre
1ad90 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1ada0 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64  *.** This second
1adb0 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53   example is an S
1adc0 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e  QL syntax error.
1add0 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72    As a general r
1ade0 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a  ule you should.*
1adf0 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20  * always use %q 
1ae00 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68  instead of %s wh
1ae10 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78  en inserting tex
1ae20 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20  t into a string 
1ae30 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  literal..**.** ^
1ae40 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77  (The %Q option w
1ae50 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63  orks like %q exc
1ae60 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73  ept it also adds
1ae70 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61   single quotes a
1ae80 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74  round.** the out
1ae90 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61  side of the tota
1aea0 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74  l string.  Addit
1aeb0 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20  ionally, if the 
1aec0 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65  parameter in the
1aed0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73  .** argument lis
1aee0 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t is a NULL poin
1aef0 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75  ter, %Q substitu
1af00 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55  tes the text "NU
1af10 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20  LL" (without.** 
1af20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29  single quotes).)
1af30 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70  ^  So, for examp
1af40 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61  le, one could sa
1af50 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  y:.**.** <blockq
1af60 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
1af70 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69  har *zSQL = sqli
1af80 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53  te3_mprintf("INS
1af90 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56  ERT INTO table V
1afa0 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78  ALUES(%Q)", zTex
1afb0 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  t);.**  sqlite3_
1afc0 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30  exec(db, zSQL, 0
1afd0 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c  , 0, 0);.**  sql
1afe0 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b  ite3_free(zSQL);
1aff0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1b000 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
1b010 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c  e code above wil
1b020 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65  l render a corre
1b030 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ct SQL statement
1b040 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20   in the zSQL.** 
1b050 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66  variable even if
1b060 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61   the zText varia
1b070 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ble is a NULL po
1b080 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  inter..**.** ^(T
1b090 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69  he "%z" formatti
1b0a0 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  ng option works 
1b0b0 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69  like "%s" but wi
1b0c0 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69  th the.** additi
1b0d0 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68  on that after th
1b0e0 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65  e string has bee
1b0f0 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65  n read and copie
1b100 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65  d into.** the re
1b110 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66  sult, [sqlite3_f
1b120 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ree()] is called
1b130 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   on the input st
1b140 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20  ring.)^.*/.char 
1b150 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  *sqlite3_mprintf
1b160 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e  (const char*,...
1b170 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
1b180 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20  _vmprintf(const 
1b190 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b  char*, va_list);
1b1a0 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73  .char *sqlite3_s
1b1b0 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72  nprintf(int,char
1b1c0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e  *,const char*, .
1b1d0 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  ..);.char *sqlit
1b1e0 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74  e3_vsnprintf(int
1b1f0 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61  ,char*,const cha
1b200 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f  r*, va_list);../
1b210 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
1b220 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e  emory Allocation
1b230 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a   Subsystem.**.**
1b240 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
1b250 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65   uses these thre
1b260 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61  e routines for a
1b270 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a  ll of its own.**
1b280 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79   internal memory
1b290 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
1b2a0 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65  s. "Core" in the
1b2b0 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e   previous senten
1b2c0 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69  ce.** does not i
1b2d0 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67  nclude operating
1b2e0 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63  -system specific
1b2f0 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
1b300 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e  ion.  The.** Win
1b310 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61  dows VFS uses na
1b320 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  tive malloc() an
1b330 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d  d free() for som
1b340 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a  e operations..**
1b350 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1b360 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e  _malloc() routin
1b370 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
1b380 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a  ter to a block.*
1b390 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c  * of memory at l
1b3a0 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
1b3b0 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20  length, where N 
1b3c0 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  is the parameter
1b3d0 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
1b3e0 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61  _malloc() is una
1b3f0 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75  ble to obtain su
1b400 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a  fficient free.**
1b410 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75   memory, it retu
1b420 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
1b430 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72  er.  ^If the par
1b440 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73  ameter N to.** s
1b450 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1b460 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74  is zero or negat
1b470 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ive then sqlite3
1b480 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  _malloc() return
1b490 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s.** a NULL poin
1b4a0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  ter..**.** ^Call
1b4b0 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65  ing sqlite3_free
1b4c0 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65  () with a pointe
1b4d0 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74  r previously ret
1b4e0 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69  urned.** by sqli
1b4f0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20  te3_malloc() or 
1b500 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1b510 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20  ) releases that 
1b520 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61  memory so.** tha
1b530 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65  t it might be re
1b540 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69  used.  ^The sqli
1b550 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69  te3_free() routi
1b560 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70  ne is.** a no-op
1b570 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69   if is called wi
1b580 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
1b590 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55  r.  Passing a NU
1b5a0 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f  LL pointer.** to
1b5b0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
1b5c0 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66  is harmless.  Af
1b5d0 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c  ter being freed,
1b5e0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c   memory.** shoul
1b5f0 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61  d neither be rea
1b600 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20  d nor written.  
1b610 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65  Even reading pre
1b620 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a  viously freed.**
1b630 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65   memory might re
1b640 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e  sult in a segmen
1b650 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20  tation fault or 
1b660 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72  other severe err
1b670 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f  or..** Memory co
1b680 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d  rruption, a segm
1b690 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20  entation fault, 
1b6a0 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20  or other severe 
1b6b0 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72  error.** might r
1b6c0 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33  esult if sqlite3
1b6d0 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65  _free() is calle
1b6e0 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c  d with a non-NUL
1b6f0 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a  L pointer that.*
1b700 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e  * was not obtain
1b710 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ed from sqlite3_
1b720 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69  malloc() or sqli
1b730 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a  te3_realloc()..*
1b740 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74  *.** ^(The sqlit
1b750 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74  e3_realloc() int
1b760 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
1b770 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70  to resize a.** p
1b780 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  rior memory allo
1b790 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20  cation to be at 
1b7a0 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77  least N bytes, w
1b7b0 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a  here N is the.**
1b7c0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1b7d0 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61  r.  The memory a
1b7e0 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20  llocation to be 
1b7f0 72 65 73 69 7a 65 64 20 69 73 20 74 68 65 20 66  resized is the f
1b800 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  irst.** paramete
1b810 72 2e 29 5e 20 5e 20 49 66 20 74 68 65 20 66 69  r.)^ ^ If the fi
1b820 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
1b830 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1b840 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20  ().** is a NULL 
1b850 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73  pointer then its
1b860 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65   behavior is ide
1b870 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e  ntical to callin
1b880 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  g.** sqlite3_mal
1b890 6c 6f 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69  loc(N) where N i
1b8a0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
1b8b0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1b8c0 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20  3_realloc()..** 
1b8d0 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70  ^If the second p
1b8e0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1b8f0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73  te3_realloc() is
1b900 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61   zero or.** nega
1b910 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65  tive then the be
1b920 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c  havior is exactl
1b930 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61  y the same as ca
1b940 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  lling.** sqlite3
1b950 5f 66 72 65 65 28 50 29 20 77 68 65 72 65 20 50  _free(P) where P
1b960 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61   is the first pa
1b970 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
1b980 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
1b990 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   ^sqlite3_reallo
1b9a0 63 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f  c() returns a po
1b9b0 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72  inter to a memor
1b9c0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
1b9d0 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  of at least N by
1b9e0 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e  tes in size or N
1b9f0 55 4c 4c 20 69 66 20 73 75 66 66 69 63 69 65 6e  ULL if sufficien
1ba00 74 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 76  t memory is unav
1ba10 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20  ailable..** ^If 
1ba20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66  M is the size of
1ba30 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
1ba40 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28  ation, then min(
1ba50 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66  N,M) bytes.** of
1ba60 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
1ba70 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64  ation are copied
1ba80 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e   into the beginn
1ba90 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65  ing of buffer re
1baa0 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c  turned.** by sql
1bab0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61  ite3_realloc() a
1bac0 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  nd the prior all
1bad0 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64  ocation is freed
1bae0 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
1baf0 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  _realloc() retur
1bb00 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68  ns NULL, then th
1bb10 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
1bb20 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65  on.** is not fre
1bb30 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d  ed..**.** ^The m
1bb40 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62  emory returned b
1bb50 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  y sqlite3_malloc
1bb60 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  () and sqlite3_r
1bb70 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61  ealloc().** is a
1bb80 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f  lways aligned to
1bb90 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62   at least an 8 b
1bba0 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72  yte boundary, or
1bbb0 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20   to a.** 4 byte 
1bbc0 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65 20  boundary if the 
1bbd0 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41  [SQLITE_4_BYTE_A
1bbe0 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63  LIGNED_MALLOC] c
1bbf0 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f  ompile-time.** o
1bc00 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a  ption is used..*
1bc10 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76  *.** In SQLite v
1bc20 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64  ersion 3.5.0 and
1bc30 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70   3.5.1, it was p
1bc40 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e  ossible to defin
1bc50 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f  e.** the SQLITE_
1bc60 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f  OMIT_MEMORY_ALLO
1bc70 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75  CATION which wou
1bc80 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69  ld cause the bui
1bc90 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65  lt-in.** impleme
1bca0 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65  ntation of these
1bcb0 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
1bcc0 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63  omitted.  That c
1bcd0 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20  apability.** is 
1bce0 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64  no longer provid
1bcf0 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d  ed.  Only built-
1bd00 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
1bd10 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64  tors can be used
1bd20 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f  ..**.** Prior to
1bd30 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
1bd40 33 2e 37 2e 31 30 2c 20 74 68 65 20 57 69 6e 64  3.7.10, the Wind
1bd50 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65  ows OS interface
1bd60 20 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a   layer called.**
1bd70 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c   the system mall
1bd80 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
1bd90 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f  directly when co
1bda0 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65  nverting.** file
1bdb0 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68  names between th
1bdc0 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  e UTF-8 encoding
1bdd0 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a   used by SQLite.
1bde0 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20  ** and whatever 
1bdf0 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e  filename encodin
1be00 67 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65  g is used by the
1be10 20 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64   particular Wind
1be20 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74  ows.** installat
1be30 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c  ion.  Memory all
1be40 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 77  ocation errors w
1be50 65 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75  ere detected, bu
1be60 74 0a 2a 2a 20 74 68 65 79 20 77 65 72 65 20 72  t.** they were r
1be70 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20  eported back as 
1be80 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  [SQLITE_CANTOPEN
1be90 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
1bea0 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68  IOERR] rather th
1beb0 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  an [SQLITE_NOMEM
1bec0 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69  ]..**.** The poi
1bed0 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74  nter arguments t
1bee0 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
1bef0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1bf00 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75  realloc()].** mu
1bf10 73 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c  st be either NUL
1bf20 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65  L or else pointe
1bf30 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  rs obtained from
1bf40 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f   a prior.** invo
1bf50 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  cation of [sqlit
1bf60 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20  e3_malloc()] or 
1bf70 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
1bf80 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a  ()] that have.**
1bf90 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65   not yet been re
1bfa0 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  leased..**.** Th
1bfb0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
1bfc0 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77  st not read or w
1bfd0 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66  rite any part of
1bfe0 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d  .** a block of m
1bff0 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68  emory after it h
1c000 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64  as been released
1c010 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
1c020 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73  e3_free()] or [s
1c030 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1c040 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  ]..*/.void *sqli
1c050 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b  te3_malloc(int);
1c060 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72  .void *sqlite3_r
1c070 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e  ealloc(void*, in
1c080 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
1c090 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f  _free(void*);../
1c0a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
1c0b0 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20  emory Allocator 
1c0c0 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a  Statistics.**.**
1c0d0 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73   SQLite provides
1c0e0 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72   these two inter
1c0f0 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74  faces for report
1c100 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75  ing on the statu
1c110 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  s.** of the [sql
1c120 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20  ite3_malloc()], 
1c130 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1c140 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  , and [sqlite3_r
1c150 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75  ealloc()].** rou
1c160 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72  tines, which for
1c170 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d  m the built-in m
1c180 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1c190 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a   subsystem..**.*
1c1a0 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
1c1b0 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72  memory_used()] r
1c1c0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
1c1d0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
1c1e0 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20  es.** of memory 
1c1f0 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61  currently outsta
1c200 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20  nding (malloced 
1c210 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a  but not freed)..
1c220 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
1c230 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
1c240 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74  r()] routine ret
1c250 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  urns the maximum
1c260 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71  .** value of [sq
1c270 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
1c280 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68  d()] since the h
1c290 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a  igh-water mark.*
1c2a0 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 74  * was last reset
1c2b0 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72  .  ^The values r
1c2c0 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
1c2d0 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
1c2e0 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
1c2f0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
1c300 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61  ter()] include a
1c310 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61  ny overhead.** a
1c320 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69  dded by SQLite i
1c330 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61  n its implementa
1c340 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
1c350 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62  _malloc()],.** b
1c360 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20  ut not overhead 
1c370 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79  added by the any
1c380 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74   underlying syst
1c390 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f  em library.** ro
1c3a0 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c  utines that [sql
1c3b0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d  ite3_malloc()] m
1c3c0 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  ay call..**.** ^
1c3d0 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d  The memory high-
1c3e0 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65  water mark is re
1c3f0 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65  set to the curre
1c400 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b  nt value of.** [
1c410 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
1c420 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e  sed()] if and on
1c430 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  ly if the parame
1c440 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ter to.** [sqlit
1c450 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
1c460 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20  ter()] is true. 
1c470 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75   ^The value retu
1c480 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69  rned.** by [sqli
1c490 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1c4a0 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20  ater(1)] is the 
1c4b0 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a  high-water mark.
1c4c0 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20  ** prior to the 
1c4d0 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65  reset..*/.sqlite
1c4e0 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
1c4f0 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64  memory_used(void
1c500 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
1c510 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
1c520 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 65  highwater(int re
1c530 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a  setFlag);../*.**
1c540 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 75 64   CAPI3REF: Pseud
1c550 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20  o-Random Number 
1c560 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20  Generator.**.** 
1c570 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20  SQLite contains 
1c580 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70  a high-quality p
1c590 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d  seudo-random num
1c5a0 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50  ber generator (P
1c5b0 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20  RNG) used to.** 
1c5c0 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52  select random [R
1c5d0 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77  OWID | ROWIDs] w
1c5e0 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65  hen inserting ne
1c5f0 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61  w records into a
1c600 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61   table that.** a
1c610 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65 20  lready uses the 
1c620 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65  largest possible
1c630 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50   [ROWID].  The P
1c640 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64  RNG is also used
1c650 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c   for.** the buil
1c660 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e  d-in random() an
1c670 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53  d randomblob() S
1c680 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54  QL functions.  T
1c690 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c  his interface al
1c6a0 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74  lows.** applicat
1c6b0 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74  ions to access t
1c6c0 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72  he same PRNG for
1c6d0 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e   other purposes.
1c6e0 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74  .**.** ^A call t
1c6f0 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73  o this routine s
1c700 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66  tores N bytes of
1c710 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f   randomness into
1c720 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a   buffer P..**.**
1c730 20 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65   ^The first time
1c740 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
1c750 20 69 6e 76 6f 6b 65 64 20 28 65 69 74 68 65 72   invoked (either
1c760 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62   internally or b
1c770 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  y.** the applica
1c780 74 69 6f 6e 29 20 74 68 65 20 50 52 4e 47 20 69  tion) the PRNG i
1c790 73 20 73 65 65 64 65 64 20 75 73 69 6e 67 20 72  s seeded using r
1c7a0 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e  andomness obtain
1c7b0 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78  ed.** from the x
1c7c0 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f  Randomness metho
1c7d0 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74  d of the default
1c7e0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
1c7f0 62 6a 65 63 74 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c  bject..** ^On al
1c800 6c 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76  l subsequent inv
1c810 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65 20 70 73  ocations, the ps
1c820 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20  eudo-randomness 
1c830 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20  is generated.** 
1c840 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77  internally and w
1c850 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20  ithout recourse 
1c860 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
1c870 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73  vfs] xRandomness
1c880 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76  .** method..*/.v
1c890 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64  oid sqlite3_rand
1c8a0 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f  omness(int N, vo
1c8b0 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  id *P);../*.** C
1c8c0 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65  API3REF: Compile
1c8d0 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74  -Time Authorizat
1c8e0 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ion Callbacks.**
1c8f0 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
1c900 65 20 72 65 67 69 73 74 65 72 73 20 61 6e 20 61  e registers an a
1c910 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1c920 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 63  ck with a partic
1c930 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ular.** [databas
1c940 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73  e connection], s
1c950 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66  upplied in the f
1c960 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
1c970 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65  * ^The authorize
1c980 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
1c990 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61  voked as SQL sta
1c9a0 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e  tements are bein
1c9b0 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79  g compiled.** by
1c9c0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1c9d0 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  e()] or its vari
1c9e0 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72  ants [sqlite3_pr
1c9f0 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20  epare_v2()],.** 
1ca00 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1ca10 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  16()] and [sqlit
1ca20 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
1ca30 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73  )].  ^At various
1ca40 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e  .** points durin
1ca50 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f  g the compilatio
1ca60 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f  n process, as lo
1ca70 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65  gic is being cre
1ca80 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f  ated.** to perfo
1ca90 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f  rm various actio
1caa0 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ns, the authoriz
1cab0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
1cac0 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65  nvoked to.** see
1cad0 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e   if those action
1cae0 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20  s are allowed.  
1caf0 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ^The authorizer 
1cb00 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a  callback should.
1cb10 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
1cb20 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74  E_OK] to allow t
1cb30 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49  he action, [SQLI
1cb40 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69  TE_IGNORE] to di
1cb50 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70  sallow the.** sp
1cb60 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75  ecific action bu
1cb70 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20  t allow the SQL 
1cb80 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e  statement to con
1cb90 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63  tinue to be.** c
1cba0 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c  ompiled, or [SQL
1cbb0 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75  ITE_DENY] to cau
1cbc0 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 51  se the entire SQ
1cbd0 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62  L statement to b
1cbe0 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69  e.** rejected wi
1cbf0 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49  th an error.  ^I
1cc00 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  f the authorizer
1cc10 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1cc20 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f  s.** any value o
1cc30 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
1cc40 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49  E_IGNORE], [SQLI
1cc50 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49  TE_OK], or [SQLI
1cc60 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e  TE_DENY].** then
1cc70 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   the [sqlite3_pr
1cc80 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65  epare_v2()] or e
1cc90 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74  quivalent call t
1cca0 68 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a  hat triggered.**
1ccb0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1ccc0 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61  will fail with a
1ccd0 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  n error message.
1cce0 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
1ccf0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1cd00 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68   [SQLITE_OK], th
1cd10 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65  at means the ope
1cd20 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73  ration.** reques
1cd30 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65  ted is ok.  ^Whe
1cd40 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  n the callback r
1cd50 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44  eturns [SQLITE_D
1cd60 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71  ENY], the.** [sq
1cd70 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1cd80 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e  ()] or equivalen
1cd90 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  t call that trig
1cda0 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74  gered the.** aut
1cdb0 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69  horizer will fai
1cdc0 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  l with an error 
1cdd0 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69  message explaini
1cde0 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73  ng that.** acces
1cdf0 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a  s is denied. .**
1ce00 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70  .** ^The first p
1ce10 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
1ce20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1ce30 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ack is a copy of
1ce40 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61   the third.** pa
1ce50 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
1ce60 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
1ce70 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63  rizer() interfac
1ce80 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  e. ^The second p
1ce90 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74  arameter.** to t
1cea0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  he callback is a
1ceb0 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54  n integer [SQLIT
1cec0 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20  E_COPY | action 
1ced0 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69  code] that speci
1cee0 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74  fies.** the part
1cef0 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f  icular action to
1cf00 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20   be authorized. 
1cf10 5e 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75  ^The third throu
1cf20 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74  gh sixth paramet
1cf30 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61  ers.** to the ca
1cf40 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d  llback are zero-
1cf50 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
1cf60 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20  gs that contain 
1cf70 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65  additional.** de
1cf80 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20  tails about the 
1cf90 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74  action to be aut
1cfa0 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  horized..**.** ^
1cfb0 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f  If the action co
1cfc0 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45  de is [SQLITE_RE
1cfd0 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63  AD].** and the c
1cfe0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
1cff0 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
1d000 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65  then the.** [pre
1d010 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1d020 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f   statement is co
1d030 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 62  nstructed to sub
1d040 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c  stitute.** a NUL
1d050 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65  L value in place
1d060 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f   of the table co
1d070 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20  lumn that would 
1d080 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61  have.** been rea
1d090 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  d if [SQLITE_OK]
1d0a0 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e   had been return
1d0b0 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  ed.  The [SQLITE
1d0c0 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75  _IGNORE].** retu
1d0d0 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  rn can be used t
1d0e0 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73  o deny an untrus
1d0f0 74 65 64 20 75 73 65 72 20 61 63 63 65 73 73 20  ted user access 
1d100 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a  to individual.**
1d110 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61   columns of a ta
1d120 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ble..** ^If the 
1d130 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b  action code is [
1d140 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61  SQLITE_DELETE] a
1d150 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  nd the callback 
1d160 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49  returns.** [SQLI
1d170 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20  TE_IGNORE] then 
1d180 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65  the [DELETE] ope
1d190 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20  ration proceeds 
1d1a0 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e  but the.** [trun
1d1b0 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f  cate optimizatio
1d1c0 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20 61  n] is disabled a
1d1d0 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20  nd all rows are 
1d1e0 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75  deleted individu
1d1f0 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61  ally..**.** An a
1d200 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65  uthorizer is use
1d210 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  d when [sqlite3_
1d220 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72  prepare | prepar
1d230 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ing].** SQL stat
1d240 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75  ements from an u
1d250 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c  ntrusted source,
1d260 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20   to ensure that 
1d270 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
1d280 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79  ts.** do not try
1d290 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 20   to access data 
1d2a0 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c  they are not all
1d2b0 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20  owed to see, or 
1d2c0 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74  that they do not
1d2d0 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75  .** try to execu
1d2e0 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61  te malicious sta
1d2f0 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d  tements that dam
1d300 61 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  age the database
1d310 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c  .  For.** exampl
1d320 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  e, an applicatio
1d330 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73  n may allow a us
1d340 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69  er to enter arbi
1d350 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65  trary.** SQL que
1d360 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74  ries for evaluat
1d370 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73  ion by a databas
1d380 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c  e.  But the appl
1d390 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20  ication does.** 
1d3a0 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65  not want the use
1d3b0 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20  r to be able to 
1d3c0 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63  make arbitrary c
1d3d0 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a  hanges to the.**
1d3e0 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61   database.  An a
1d3f0 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20  uthorizer could 
1d400 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70  then be put in p
1d410 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a  lace while the.*
1d420 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53  * user-entered S
1d430 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c  QL is being [sql
1d440 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70  ite3_prepare | p
1d450 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a  repared] that.**
1d460 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79   disallows every
1d470 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45  thing except [SE
1d480 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73  LECT] statements
1d490 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ..**.** Applicat
1d4a0 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74  ions that need t
1d4b0 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72  o process SQL fr
1d4c0 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75  om untrusted sou
1d4d0 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c  rces.** might al
1d4e0 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65  so consider lowe
1d4f0 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69  ring resource li
1d500 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69  mits using [sqli
1d510 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20  te3_limit()].** 
1d520 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74  and limiting dat
1d530 61 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67  abase size using
1d540 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63   the [max_page_c
1d550 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a  ount] [PRAGMA].*
1d560 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f  * in addition to
1d570 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72   using an author
1d580 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e  izer..**.** ^(On
1d590 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68  ly a single auth
1d5a0 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e  orizer can be in
1d5b0 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61   place on a data
1d5c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
1d5d0 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45  ** at a time.  E
1d5e0 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ach call to sqli
1d5f0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1d600 65 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65  er overrides the
1d610 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c  .** previous cal
1d620 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74  l.)^  ^Disable t
1d630 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79  he authorizer by
1d640 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55   installing a NU
1d650 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  LL callback..** 
1d660 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69  The authorizer i
1d670 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  s disabled by de
1d680 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  fault..**.** The
1d690 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1d6a0 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f  back must not do
1d6b0 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77   anything that w
1d6c0 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68  ill modify.** th
1d6d0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1d6e0 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
1d6f0 65 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ed the authorize
1d700 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e  r callback..** N
1d710 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65  ote that [sqlite
1d720 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1d730 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  and [sqlite3_ste
1d740 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79  p()] both modify
1d750 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61   their.** databa
1d760 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66  se connections f
1d770 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f  or the meaning o
1d780 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68  f "modify" in th
1d790 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a  is paragraph..**
1d7a0 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74  .** ^When [sqlit
1d7b0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1d7c0 20 69 73 20 75 73 65 64 20 74 6f 20 70 72 65 70   is used to prep
1d7d0 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c  are a statement,
1d7e0 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   the.** statemen
1d7f0 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72  t might be re-pr
1d800 65 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73  epared during [s
1d810 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64  qlite3_step()] d
1d820 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65  ue to a .** sche
1d830 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63  ma change.  Henc
1d840 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  e, the applicati
1d850 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65  on should ensure
1d860 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72   that the.** cor
1d870 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20  rect authorizer 
1d880 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73  callback remains
1d890 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67   in place during
1d8a0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
1d8b0 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f  ep()]..**.** ^No
1d8c0 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68  te that the auth
1d8d0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1d8e0 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20  is invoked only 
1d8f0 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74  during.** [sqlit
1d900 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
1d910 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20   its variants.  
1d920 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73  Authorization is
1d930 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65   not.** performe
1d940 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65  d during stateme
1d950 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e  nt evaluation in
1d960 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1d970 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20  ], unless.** as 
1d980 73 74 61 74 65 64 20 69 6e 20 74 68 65 20 70 72  stated in the pr
1d990 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68  evious paragraph
1d9a0 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  , sqlite3_step()
1d9b0 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69   invokes.** sqli
1d9c0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1d9d0 20 74 6f 20 72 65 70 72 65 70 61 72 65 20 61 20   to reprepare a 
1d9e0 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20  statement after 
1d9f0 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e  a schema change.
1da00 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1da10 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a  set_authorizer(.
1da20 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e    sqlite3*,.  in
1da30 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a  t (*xAuth)(void*
1da40 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a  ,int,const char*
1da50 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
1da60 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
1da70 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70  har*),.  void *p
1da80 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a  UserData.);../*.
1da90 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74  ** CAPI3REF: Aut
1daa0 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43  horizer Return C
1dab0 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  odes.**.** The [
1dac0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1dad0 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69  orizer | authori
1dae0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  zer callback fun
1daf0 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72  ction] must.** r
1db00 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51  eturn either [SQ
1db10 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20  LITE_OK] or one 
1db20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e  of these two con
1db30 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a  stants in order.
1db40 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c  ** to signal SQL
1db50 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e  ite whether or n
1db60 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73  ot the action is
1db70 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65   permitted.  See
1db80 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
1db90 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
1dba0 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63  | authorizer doc
1dbb0 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20  umentation] for 
1dbc0 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e  additional.** in
1dbd0 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
1dbe0 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49 54   Note that SQLIT
1dbf0 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f  E_IGNORE is also
1dc00 20 75 73 65 64 20 61 73 20 61 20 5b 53 51 4c 49   used as a [SQLI
1dc10 54 45 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 65  TE_ROLLBACK | re
1dc20 74 75 72 6e 20 63 6f 64 65 5d 0a 2a 2a 20 66 72  turn code].** fr
1dc30 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  om the [sqlite3_
1dc40 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74  vtab_on_conflict
1dc50 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
1dc60 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1dc70 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41  _DENY   1   /* A
1dc80 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61  bort the SQL sta
1dc90 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65  tement with an e
1dca0 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
1dcb0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20  SQLITE_IGNORE 2 
1dcc0 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77    /* Don't allow
1dcd0 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e   access, but don
1dce0 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65  't generate an e
1dcf0 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  rror */../*.** C
1dd00 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
1dd10 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73  zer Action Codes
1dd20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
1dd30 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1dd40 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  er()] interface 
1dd50 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
1dd60 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  back function.**
1dd70 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64   that is invoked
1dd80 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65   to authorize ce
1dd90 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d  rtain SQL statem
1dda0 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68  ent actions.  Th
1ddb0 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
1ddc0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c  meter to the cal
1ddd0 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65  lback is an inte
1dde0 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70  ger code that sp
1ddf0 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20  ecifies.** what 
1de00 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20  action is being 
1de10 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65  authorized.  The
1de20 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67  se are the integ
1de30 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20  er action codes 
1de40 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68  that.** the auth
1de50 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1de60 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a  may be passed..*
1de70 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f  *.** These actio
1de80 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69  n code values si
1de90 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20  gnify what kind 
1dea0 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  of operation is 
1deb0 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69  to be.** authori
1dec0 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e  zed.  The 3rd an
1ded0 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73  d 4th parameters
1dee0 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
1def0 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63  ation.** callbac
1df00 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20  k function will 
1df10 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72  be parameters or
1df20 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20   NULL depending 
1df30 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73  on which of thes
1df40 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73  e.** codes is us
1df50 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
1df60 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54   parameter.  ^(T
1df70 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
1df80 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f   to the.** autho
1df90 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
1dfa0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
1dfb0 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69  e database ("mai
1dfc0 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65  n", "temp",.** e
1dfd0 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62  tc.) if applicab
1dfe0 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20  le.)^  ^The 6th 
1dff0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1e000 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1e010 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e  back.** is the n
1e020 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72  ame of the inner
1e030 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72  -most trigger or
1e040 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65   view that is re
1e050 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a  sponsible for.**
1e060 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65   the access atte
1e070 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  mpt or NULL if t
1e080 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d  his access attem
1e090 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66  pt is directly f
1e0a0 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c  rom.** top-level
1e0b0 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a   SQL code..*/./*
1e0c0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1e0d0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1e0e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a  ********** 3rd *
1e0f0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20  *********** 4th 
1e100 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65  ***********/.#de
1e110 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1e120 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  TE_INDEX        
1e130 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e    1   /* Index N
1e140 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
1e150 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1e160 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1e170 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  E_TABLE         
1e180 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   2   /* Table Na
1e190 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1e1a0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1e1b0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1e1c0 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
1e1d0 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  3   /* Index Nam
1e1e0 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
1e1f0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1e200 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1e210 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34  TEMP_TABLE     4
1e220 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1e230 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1e240 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1e250 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1e260 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20  EMP_TRIGGER   5 
1e270 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
1e280 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
1e290 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1e2a0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
1e2b0 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20  MP_VIEW      6  
1e2c0 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
1e2d0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1e2e0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1e2f0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49  QLITE_CREATE_TRI
1e300 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20  GGER        7   
1e310 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
1e320 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1e330 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1e340 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57  LITE_CREATE_VIEW
1e350 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f             8   /
1e360 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
1e370 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1e380 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1e390 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20  ITE_DELETE      
1e3a0 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a            9   /*
1e3b0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1e3c0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1e3d0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1e3e0 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20  TE_DROP_INDEX   
1e3f0 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20          10   /* 
1e400 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
1e410 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1e420 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1e430 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20  E_DROP_TABLE    
1e440 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54         11   /* T
1e450 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1e460 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1e470 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1e480 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58  _DROP_TEMP_INDEX
1e490 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e        12   /* In
1e4a0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
1e4b0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1e4c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1e4d0 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20  DROP_TEMP_TABLE 
1e4e0 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62       13   /* Tab
1e4f0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1e500 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1e510 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1e520 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52  ROP_TEMP_TRIGGER
1e530 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67      14   /* Trig
1e540 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
1e550 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1e560 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1e570 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20  OP_TEMP_VIEW    
1e580 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20     15   /* View 
1e590 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
1e5a0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1e5b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1e5c0 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  P_TRIGGER       
1e5d0 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65    16   /* Trigge
1e5e0 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
1e5f0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1e600 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1e610 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20  _VIEW           
1e620 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   17   /* View Na
1e630 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
1e640 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1e650 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52  ine SQLITE_INSER
1e660 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
1e670 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  18   /* Table Na
1e680 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1e690 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1e6a0 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41  ne SQLITE_PRAGMA
1e6b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
1e6c0 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61  9   /* Pragma Na
1e6d0 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f  me     1st arg o
1e6e0 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e  r NULL */.#defin
1e6f0 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20  e SQLITE_READ   
1e700 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30                20
1e710 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1e720 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
1e730 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
1e740 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20   SQLITE_SELECT  
1e750 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20               21 
1e760 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
1e770 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1e780 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1e790 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49  SQLITE_TRANSACTI
1e7a0 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20  ON          22  
1e7b0 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20   /* Operation   
1e7c0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1e7d0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1e7e0 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20  QLITE_UPDATE    
1e7f0 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20             23   
1e800 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1e810 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20     Column Name  
1e820 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1e830 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20  LITE_ATTACH     
1e840 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f            24   /
1e850 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20  * Filename      
1e860 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1e870 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1e880 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20  ITE_DETACH      
1e890 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a           25   /*
1e8a0 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20   Database Name  
1e8b0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1e8c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1e8d0 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20  TE_ALTER_TABLE  
1e8e0 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20          26   /* 
1e8f0 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20  Database Name   
1e900 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1e910 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1e920 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20  E_REINDEX       
1e930 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49         27   /* I
1e940 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e  ndex Name      N
1e950 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1e960 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1e970 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20  _ANALYZE        
1e980 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61        28   /* Ta
1e990 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
1e9a0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1e9b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1e9c0 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20  CREATE_VTABLE   
1e9d0 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62       29   /* Tab
1e9e0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64  le Name      Mod
1e9f0 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  ule Name     */.
1ea00 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1ea10 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20  ROP_VTABLE      
1ea20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c      30   /* Tabl
1ea30 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75  e Name      Modu
1ea40 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  le Name     */.#
1ea50 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55  define SQLITE_FU
1ea60 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20  NCTION          
1ea70 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20     31   /* NULL 
1ea80 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63 74             Funct
1ea90 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64  ion Name   */.#d
1eaa0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56  efine SQLITE_SAV
1eab0 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20  EPOINT          
1eac0 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74    32   /* Operat
1ead0 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f  ion       Savepo
1eae0 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65  int Name  */.#de
1eaf0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59  fine SQLITE_COPY
1eb00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1eb10 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67    0   /* No long
1eb20 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a  er used */../*.*
1eb30 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63  * CAPI3REF: Trac
1eb40 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e  ing And Profilin
1eb50 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  g Functions.**.*
1eb60 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1eb70 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61   register callba
1eb80 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61  ck functions tha
1eb90 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f  t can be used fo
1eba0 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64  r.** tracing and
1ebb0 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65   profiling the e
1ebc0 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20  xecution of SQL 
1ebd0 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
1ebe0 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  * ^The callback 
1ebf0 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65  function registe
1ec00 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74  red by sqlite3_t
1ec10 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  race() is invoke
1ec20 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20  d at.** various 
1ec30 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51  times when an SQ
1ec40 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62  L statement is b
1ec50 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c  eing run by [sql
1ec60 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a  ite3_step()]..**
1ec70 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72   ^The sqlite3_tr
1ec80 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69  ace() callback i
1ec90 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61  s invoked with a
1eca0 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67   UTF-8 rendering
1ecb0 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73   of the.** SQL s
1ecc0 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73  tatement text as
1ecd0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66   the statement f
1ece0 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 65 63  irst begins exec
1ecf0 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69  uting..** ^(Addi
1ed00 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74  tional sqlite3_t
1ed10 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73  race() callbacks
1ed20 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20   might occur.** 
1ed30 61 73 20 65 61 63 68 20 74 72 69 67 67 65 72 65  as each triggere
1ed40 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20  d subprogram is 
1ed50 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63 61  entered.  The ca
1ed60 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67  llbacks for trig
1ed70 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20  gers.** contain 
1ed80 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d  a UTF-8 SQL comm
1ed90 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69 66  ent that identif
1eda0 69 65 73 20 74 68 65 20 74 72 69 67 67 65 72 2e  ies the trigger.
1edb0 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51  )^.**.** The [SQ
1edc0 4c 49 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f  LITE_TRACE_SIZE_
1edd0 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74  LIMIT] compile-t
1ede0 69 6d 65 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62  ime option can b
1edf0 65 20 75 73 65 64 20 74 6f 20 6c 69 6d 69 74 0a  e used to limit.
1ee00 2a 2a 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66  ** the length of
1ee10 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65   [bound paramete
1ee20 72 5d 20 65 78 70 61 6e 73 69 6f 6e 20 69 6e 20  r] expansion in 
1ee30 74 68 65 20 6f 75 74 70 75 74 20 6f 66 20 73 71  the output of sq
1ee40 6c 69 74 65 33 5f 74 72 61 63 65 28 29 2e 0a 2a  lite3_trace()..*
1ee50 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61  *.** ^The callba
1ee60 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69  ck function regi
1ee70 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65  stered by sqlite
1ee80 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69  3_profile() is i
1ee90 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63  nvoked.** as eac
1eea0 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  h SQL statement 
1eeb0 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20  finishes.  ^The 
1eec0 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b  profile callback
1eed0 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65   contains.** the
1eee0 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d   original statem
1eef0 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20  ent text and an 
1ef00 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c  estimate of wall
1ef10 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f  -clock time.** o
1ef20 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20  f how long that 
1ef30 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74  statement took t
1ef40 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f  o run.  ^The pro
1ef50 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  file callback.**
1ef60 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 74   time is in unit
1ef70 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73  s of nanoseconds
1ef80 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20 63 75  , however the cu
1ef90 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61  rrent implementa
1efa0 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20  tion.** is only 
1efb0 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69  capable of milli
1efc0 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f  second resolutio
1efd0 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65 61  n so the six lea
1efe0 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a  st significant.*
1eff0 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68 65 20  * digits in the 
1f000 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e 67  time are meaning
1f010 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20 76 65  less.  Future ve
1f020 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
1f030 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 64  .** might provid
1f040 65 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c 75  e greater resolu
1f050 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66  tion on the prof
1f060 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20  iler callback.  
1f070 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70  The.** sqlite3_p
1f080 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 69 6f  rofile() functio
1f090 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  n is considered 
1f0a0 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64  experimental and
1f0b0 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74   is.** subject t
1f0c0 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75  o change in futu
1f0d0 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
1f0e0 51 4c 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  QLite..*/.void *
1f0f0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71  sqlite3_trace(sq
1f100 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54  lite3*, void(*xT
1f110 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73  race)(void*,cons
1f120 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29  t char*), void*)
1f130 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  ;.SQLITE_EXPERIM
1f140 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69  ENTAL void *sqli
1f150 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69  te3_profile(sqli
1f160 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78  te3*,.   void(*x
1f170 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63  Profile)(void*,c
1f180 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74  onst char*,sqlit
1f190 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64  e3_uint64), void
1f1a0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1f1b0 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72  REF: Query Progr
1f1c0 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ess Callbacks.**
1f1d0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1f1e0 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65  _progress_handle
1f1f0 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72  r(D,N,X,P) inter
1f200 66 61 63 65 20 63 61 75 73 65 73 20 74 68 65 20  face causes the 
1f210 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63  callback.** func
1f220 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e 76  tion X to be inv
1f230 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c  oked periodicall
1f240 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75  y during long ru
1f250 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a  nning calls to.*
1f260 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  * [sqlite3_exec(
1f270 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  )], [sqlite3_ste
1f280 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  p()] and [sqlite
1f290 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66  3_get_table()] f
1f2a0 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  or.** database c
1f2b0 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e  onnection D.  An
1f2c0 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72   example use for
1f2d0 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61   this.** interfa
1f2e0 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20  ce is to keep a 
1f2f0 47 55 49 20 75 70 64 61 74 65 64 20 64 75 72 69  GUI updated duri
1f300 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 79  ng a large query
1f310 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72  ..**.** ^The par
1f320 61 6d 65 74 65 72 20 50 20 69 73 20 70 61 73 73  ameter P is pass
1f330 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68  ed through as th
1f340 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72  e only parameter
1f350 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c   to the .** call
1f360 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e  back function X.
1f370 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72    ^The parameter
1f380 20 4e 20 69 73 20 74 68 65 20 61 70 70 72 6f 78   N is the approx
1f390 69 6d 61 74 65 20 6e 75 6d 62 65 72 20 6f 66 20  imate number of 
1f3a0 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 63  .** [virtual mac
1f3b0 68 69 6e 65 20 69 6e 73 74 72 75 63 74 69 6f 6e  hine instruction
1f3c0 73 5d 20 74 68 61 74 20 61 72 65 20 65 76 61 6c  s] that are eval
1f3d0 75 61 74 65 64 20 62 65 74 77 65 65 6e 20 73 75  uated between su
1f3e0 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f  ccessive.** invo
1f3f0 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 63  cations of the c
1f400 61 6c 6c 62 61 63 6b 20 58 2e 20 20 5e 49 66 20  allback X.  ^If 
1f410 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f  N is less than o
1f420 6e 65 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67  ne then the prog
1f430 72 65 73 73 0a 2a 2a 20 68 61 6e 64 6c 65 72 20  ress.** handler 
1f440 69 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a  is disabled..**.
1f450 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c  ** ^Only a singl
1f460 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
1f470 65 72 20 6d 61 79 20 62 65 20 64 65 66 69 6e 65  er may be define
1f480 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 65  d at one time pe
1f490 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
1f4a0 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74  onnection]; sett
1f4b0 69 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 72 65  ing a new progre
1f4c0 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 65  ss handler cance
1f4d0 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e  ls the.** old on
1f4e0 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 61 72  e.  ^Setting par
1f4f0 61 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c  ameter X to NULL
1f500 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 70 72   disables the pr
1f510 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a  ogress handler..
1f520 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 73 73  ** ^The progress
1f530 20 68 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f   handler is also
1f540 20 64 69 73 61 62 6c 65 64 20 62 79 20 73 65 74   disabled by set
1f550 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c 75  ting N to a valu
1f560 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31  e less.** than 1
1f570 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
1f580 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
1f590 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  k returns non-ze
1f5a0 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f  ro, the operatio
1f5b0 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70  n is.** interrup
1f5c0 74 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 75  ted.  This featu
1f5d0 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  re can be used t
1f5e0 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a  o implement a.**
1f5f0 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e   "Cancel" button
1f600 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65   on a GUI progre
1f610 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a  ss dialog box..*
1f620 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73  *.** The progres
1f630 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  s handler callba
1f640 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61  ck must not do a
1f650 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c  nything that wil
1f660 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20  l modify.** the 
1f670 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1f680 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
1f690 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   the progress ha
1f6a0 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74  ndler..** Note t
1f6b0 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hat [sqlite3_pre
1f6c0 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
1f6d0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1f6e0 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69  both modify thei
1f6f0 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
1f700 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68  nnections for th
1f710 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f  e meaning of "mo
1f720 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61  dify" in this pa
1f730 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76  ragraph..**.*/.v
1f740 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67  oid sqlite3_prog
1f750 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c  ress_handler(sql
1f760 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28  ite3*, int, int(
1f770 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a  *)(void*), void*
1f780 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1f790 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65  EF: Opening A Ne
1f7a0 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  w Database Conne
1f7b0 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ction.**.** ^The
1f7c0 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e  se routines open
1f7d0 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62   an SQLite datab
1f7e0 61 73 65 20 66 69 6c 65 20 61 73 20 73 70 65 63  ase file as spec
1f7f0 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a  ified by the .**
1f800 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
1f810 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d  nt. ^The filenam
1f820 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e  e argument is in
1f830 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46  terpreted as UTF
1f840 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  -8 for.** sqlite
1f850 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
1f860 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61  ite3_open_v2() a
1f870 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  nd as UTF-16 in 
1f880 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a  the native byte.
1f890 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c  ** order for sql
1f8a0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e  ite3_open16(). ^
1f8b0 28 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  (A [database con
1f8c0 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20  nection] handle 
1f8d0 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65  is usually.** re
1f8e0 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c  turned in *ppDb,
1f8f0 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f   even if an erro
1f900 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f  r occurs.  The o
1f910 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73  nly exception is
1f920 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69   that.** if SQLi
1f930 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  te is unable to 
1f940 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20  allocate memory 
1f950 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c  to hold the [sql
1f960 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a  ite3] object,.**
1f970 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20   a NULL will be 
1f980 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70  written into *pp
1f990 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20  Db instead of a 
1f9a0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
1f9b0 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65  sqlite3].** obje
1f9c0 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64  ct.)^ ^(If the d
1f9d0 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
1f9e0 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65  d (and/or create
1f9f0 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c  d) successfully,
1fa00 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45   then.** [SQLITE
1fa10 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64  _OK] is returned
1fa20 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20  .  Otherwise an 
1fa30 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
1fa40 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65  returned.)^ ^The
1fa50 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  .** [sqlite3_err
1fa60 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  msg()] or [sqlit
1fa70 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72  e3_errmsg16()] r
1fa80 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75  outines can be u
1fa90 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a  sed to obtain.**
1faa0 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67   an English lang
1fab0 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e  uage description
1fac0 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f   of the error fo
1fad0 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72  llowing a failur
1fae0 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74  e of any.** of t
1faf0 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  he sqlite3_open(
1fb00 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  ) routines..**.*
1fb10 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65  * ^The default e
1fb20 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20  ncoding for the 
1fb30 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
1fb40 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c   UTF-8 if.** sql
1fb50 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
1fb60 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1fb70 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a   is called and.*
1fb80 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20  * UTF-16 in the 
1fb90 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
1fba0 72 20 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 65  r if sqlite3_ope
1fbb0 6e 31 36 28 29 20 69 73 20 75 73 65 64 2e 0a 2a  n16() is used..*
1fbc0 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20  *.** Whether or 
1fbd0 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  not an error occ
1fbe0 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f  urs when it is o
1fbf0 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73  pened, resources
1fc00 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
1fc10 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
1fc20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
1fc30 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72  ndle should be r
1fc40 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61  eleased by.** pa
1fc50 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c  ssing it to [sql
1fc60 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68  ite3_close()] wh
1fc70 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67  en it is no long
1fc80 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  er required..**.
1fc90 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  ** The sqlite3_o
1fca0 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61  pen_v2() interfa
1fcb0 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71  ce works like sq
1fcc0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20  lite3_open().** 
1fcd0 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61  except that it a
1fce0 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74  ccepts two addit
1fcf0 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73  ional parameters
1fd00 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
1fd10 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20  control.** over 
1fd20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65  the new database
1fd30 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28   connection.  ^(
1fd40 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65  The flags parame
1fd50 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  ter to.** sqlite
1fd60 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20  3_open_v2() can 
1fd70 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74  take one of.** t
1fd80 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72  he following thr
1fd90 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f  ee values, optio
1fda0 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77  nally combined w
1fdb0 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ith the .** [SQL
1fdc0 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
1fdd0 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ], [SQLITE_OPEN_
1fde0 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c  FULLMUTEX], [SQL
1fdf0 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
1fe00 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ACHE],.** [SQLIT
1fe10 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
1fe20 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51  CHE], and/or [SQ
1fe30 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66  LITE_OPEN_URI] f
1fe40 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64  lags:)^.**.** <d
1fe50 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  l>.** ^(<dt>[SQL
1fe60 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
1fe70 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  Y]</dt>.** <dd>T
1fe80 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
1fe90 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e  pened in read-on
1fea0 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65  ly mode.  If the
1feb0 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e   database does n
1fec0 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78  ot.** already ex
1fed0 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73  ist, an error is
1fee0 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29   returned.</dd>)
1fef0 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  ^.**.** ^(<dt>[S
1ff00 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
1ff10 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  RITE]</dt>.** <d
1ff20 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
1ff30 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
1ff40 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67  ding and writing
1ff50 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72   if possible, or
1ff60 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79   reading.** only
1ff70 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   if the file is 
1ff80 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20  write protected 
1ff90 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  by the operating
1ffa0 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74   system.  In eit
1ffb0 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20  her.** case the 
1ffc0 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c  database must al
1ffd0 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68  ready exist, oth
1ffe0 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20  erwise an error 
1fff0 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64  is returned.</dd
20000 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
20010 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
20020 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54  DWRITE] | [SQLIT
20030 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f  E_OPEN_CREATE]</
20040 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
20050 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
20060 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  d for reading an
20070 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69  d writing, and i
20080 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20  s created if.** 
20090 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65  it does not alre
200a0 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20  ady exist. This 
200b0 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  is the behavior 
200c0 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75  that is always u
200d0 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  sed for.** sqlit
200e0 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
200f0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c  lite3_open16().<
20100 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  /dd>)^.** </dl>.
20110 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64  **.** If the 3rd
20120 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
20130 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
20140 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68  is not one of th
20150 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  e.** combination
20160 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70  s shown above op
20170 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65  tionally combine
20180 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20  d with other.** 
20190 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
201a0 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f  DONLY | SQLITE_O
201b0 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74  PEN_* bits].** t
201c0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
201d0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
201e0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51  *.** ^If the [SQ
201f0 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
20200 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20  X] flag is set, 
20210 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
20220 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
20230 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c  opens in the mul
20240 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61  ti-thread [threa
20250 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f  ding mode] as lo
20260 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65  ng as the single
20270 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20  -thread.** mode 
20280 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74  has not been set
20290 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
202a0 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20   or start-time. 
202b0 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c   ^If the.** [SQL
202c0 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
202d0 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20  EX] flag is set 
202e0 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
202f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65  e connection ope
20300 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72  ns.** in the ser
20310 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69  ialized [threadi
20320 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20  ng mode] unless 
20330 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61  single-thread wa
20340 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  s.** previously 
20350 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70  selected at comp
20360 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72  ile-time or star
20370 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20  t-time..** ^The 
20380 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41  [SQLITE_OPEN_SHA
20390 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63  REDCACHE] flag c
203a0 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61  auses the databa
203b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  se connection to
203c0 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20   be.** eligible 
203d0 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20 63  to use [shared c
203e0 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61  ache mode], rega
203f0 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
20400 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a  r or not shared.
20410 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62  ** cache is enab
20420 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  led using [sqlit
20430 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64  e3_enable_shared
20440 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65  _cache()].  ^The
20450 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
20460 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66  _PRIVATECACHE] f
20470 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64  lag causes the d
20480 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
20490 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72  on to not.** par
204a0 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61  ticipate in [sha
204b0 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20  red cache mode] 
204c0 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e  even if it is en
204d0 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  abled..**.** ^Th
204e0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
204f0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
20500 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e  en_v2() is the n
20510 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  ame of the.** [s
20520 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
20530 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20  ct that defines 
20540 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
20550 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74  stem interface t
20560 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64  hat.** the new d
20570 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
20580 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20  on should use.  
20590 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70  ^If the fourth p
205a0 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61  arameter is.** a
205b0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
205c0 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  en the default [
205d0 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
205e0 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  ect is used..**.
205f0 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e  ** ^If the filen
20600 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a  ame is ":memory:
20610 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74  ", then a privat
20620 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d  e, temporary in-
20630 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a  memory database.
20640 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 6f  ** is created fo
20650 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  r the connection
20660 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f  .  ^This in-memo
20670 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  ry database will
20680 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20   vanish when.** 
20690 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
206a0 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
206b0 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  d.  Future versi
206c0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ons of SQLite mi
206d0 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20  ght.** make use 
206e0 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70  of additional sp
206f0 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20  ecial filenames 
20700 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20  that begin with 
20710 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65  the ":" characte
20720 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f  r..** It is reco
20730 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65  mmended that whe
20740 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  n a database fil
20750 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64  ename actually d
20760 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a  oes begin with.*
20770 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65  * a ":" characte
20780 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65  r you should pre
20790 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  fix the filename
207a0 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65   with a pathname
207b0 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22   such as.** "./"
207c0 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75   to avoid ambigu
207d0 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ity..**.** ^If t
207e0 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61  he filename is a
207f0 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20  n empty string, 
20800 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20  then a private, 
20810 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d  temporary.** on-
20820 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69  disk database wi
20830 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20  ll be created.  
20840 5e 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61  ^This private da
20850 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a  tabase will be.*
20860 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  * automatically 
20870 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20  deleted as soon 
20880 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  as the database 
20890 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c  connection is cl
208a0 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52  osed..**.** [[UR
208b0 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73  I filenames in s
208c0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20  qlite3_open()]] 
208d0 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65  <h3>URI Filename
208e0 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66  s</h3>.**.** ^If
208f0 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20   [URI filename] 
20900 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69  interpretation i
20910 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74  s enabled, and t
20920 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
20930 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77  ment.** begins w
20940 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65  ith "file:", the
20950 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69  n the filename i
20960 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
20970 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20   a URI. ^URI.** 
20980 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72  filename interpr
20990 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c  etation is enabl
209a0 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54  ed if the [SQLIT
209b0 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67  E_OPEN_URI] flag
209c0 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68   is.** set in th
209d0 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
209e0 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  t to sqlite3_ope
209f0 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74  n_v2(), or if it
20a00 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61   has.** been ena
20a10 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73  bled globally us
20a20 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ing the [SQLITE_
20a30 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69  CONFIG_URI] opti
20a40 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  on with the.** [
20a50 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
20a60 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74  ] method or by t
20a70 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55  he [SQLITE_USE_U
20a80 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  RI] compile-time
20a90 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f   option..** As o
20aa0 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  f SQLite version
20ab0 20 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c 65   3.7.7, URI file
20ac0 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74  name interpretat
20ad0 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66  ion is turned of
20ae0 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c  f.** by default,
20af0 20 62 75 74 20 66 75 74 75 72 65 20 72 65 6c 65   but future rele
20b00 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ases of SQLite m
20b10 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20  ight enable URI 
20b20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65  filename.** inte
20b30 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65  rpretation by de
20b40 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52  fault.  See "[UR
20b50 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f  I filenames]" fo
20b60 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
20b70 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
20b80 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73  ** URI filenames
20b90 20 61 72 65 20 70 61 72 73 65 64 20 61 63 63 6f   are parsed acco
20ba0 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38  rding to RFC 398
20bb0 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20 63  6. ^If the URI c
20bc0 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75  ontains an.** au
20bd0 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74  thority, then it
20be0 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
20bf0 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20  an empty string 
20c00 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a  or the string .*
20c10 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e  * "localhost". ^
20c20 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 74 79  If the authority
20c30 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79   is not an empty
20c40 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61   string or "loca
20c50 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65  lhost", an .** e
20c60 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
20c70 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20   to the caller. 
20c80 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f  ^The fragment co
20c90 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49  mponent of a URI
20ca0 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74  , if .** present
20cb0 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a  , is ignored..**
20cc0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73  .** ^SQLite uses
20cd0 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e   the path compon
20ce0 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20 61  ent of the URI a
20cf0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
20d00 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77  e disk file.** w
20d10 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68  hich contains th
20d20 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20  e database. ^If 
20d30 74 68 65 20 70 61 74 68 20 62 65 67 69 6e 73 20  the path begins 
20d40 77 69 74 68 20 61 20 27 2f 27 20 63 68 61 72 61  with a '/' chara
20d50 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69  cter, .** then i
20d60 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  t is interpreted
20d70 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20   as an absolute 
20d80 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61  path. ^If the pa
20d90 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69  th does not begi
20da0 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27  n .** with a '/'
20db0 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74   (meaning that t
20dc0 68 65 20 61 75 74 68 6f 72 69 74 79 20 73 65 63  he authority sec
20dd0 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20  tion is omitted 
20de0 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a  from the URI).**
20df0 20 74 68 65 6e 20 74 68 65 20 70 61 74 68 20 69   then the path i
20e00 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
20e10 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 68   a relative path
20e20 2e 20 0a 2a 2a 20 5e 4f 6e 20 77 69 6e 64 6f 77  . .** ^On window
20e30 73 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d  s, the first com
20e40 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73  ponent of an abs
20e50 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69  olute path .** i
20e60 73 20 61 20 64 72 69 76 65 20 73 70 65 63 69 66  s a drive specif
20e70 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43  ication (e.g. "C
20e80 3a 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72  :")..**.** [[cor
20e90 65 20 55 52 49 20 71 75 65 72 79 20 70 61 72 61  e URI query para
20ea0 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20  meters]].** The 
20eb0 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20  query component 
20ec0 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e  of a URI may con
20ed0 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20  tain parameters 
20ee0 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 70 72  that are interpr
20ef0 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62  eted.** either b
20f00 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c  y SQLite itself,
20f10 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20   or by a [VFS | 
20f20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65  custom VFS imple
20f30 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53  mentation]..** S
20f40 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73  QLite interprets
20f50 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   the following t
20f60 68 72 65 65 20 71 75 65 72 79 20 70 61 72 61 6d  hree query param
20f70 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  eters:.**.** <ul
20f80 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76  >.**   <li> <b>v
20f90 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66  fs</b>: ^The "vf
20fa0 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  s" parameter may
20fb0 20 62 65 20 75 73 65 64 20 74 6f 20 73 70 65 63   be used to spec
20fc0 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a  ify the name of.
20fd0 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62 6a  **     a VFS obj
20fe0 65 63 74 20 74 68 61 74 20 70 72 6f 76 69 64 65  ect that provide
20ff0 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  s the operating 
21000 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65  system interface
21010 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20   that should.** 
21020 20 20 20 20 62 65 20 75 73 65 64 20 74 6f 20 61      be used to a
21030 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61  ccess the databa
21040 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e  se file on disk.
21050 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e   ^If this option
21060 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20   is set to.**   
21070 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e    an empty strin
21080 67 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46  g the default VF
21090 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  S object is used
210a0 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e  . ^Specifying an
210b0 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20   unknown.**     
210c0 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72 2e  VFS is an error.
210d0 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65   ^If sqlite3_ope
210e0 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61  n_v2() is used a
210f0 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74 69 6f  nd the vfs optio
21100 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 73  n is.**     pres
21110 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56 46  ent, then the VF
21120 53 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  S specified by t
21130 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  he option takes 
21140 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72 0a  precedence over.
21150 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75 65  **     the value
21160 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
21170 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
21180 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
21190 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c  v2()..**.**   <l
211a0 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20  i> <b>mode</b>: 
211b0 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61 6d  ^(The mode param
211c0 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20  eter may be set 
211d0 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c 20  to either "ro", 
211e0 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77  "rw",.**     "rw
211f0 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e  c", or "memory".
21200 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73   Attempting to s
21210 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 68  et it to any oth
21220 65 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20  er value is.**  
21230 20 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a     an error)^. .
21240 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20  **     ^If "ro" 
21250 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 68  is specified, th
21260 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
21270 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
21280 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20  ad-only .**     
21290 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20  access, just as 
212a0 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  if the [SQLITE_O
212b0 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c  PEN_READONLY] fl
212c0 61 67 20 68 61 64 20 62 65 65 6e 20 73 65 74 20  ag had been set 
212d0 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74  in the .**     t
212e0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  hird argument to
212f0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
21300 28 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65  (). ^If the mode
21310 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74   option is set t
21320 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20  o .**     "rw", 
21330 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
21340 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
21350 72 65 61 64 2d 77 72 69 74 65 20 28 62 75 74 20  read-write (but 
21360 6e 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20  not create) .** 
21370 20 20 20 20 61 63 63 65 73 73 2c 20 61 73 20 69      access, as i
21380 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  f SQLITE_OPEN_RE
21390 41 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74  ADWRITE (but not
213a0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
213b0 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20  ATE) had .**    
213c0 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75   been set. ^Valu
213d0 65 20 22 72 77 63 22 20 69 73 20 65 71 75 69 76  e "rwc" is equiv
213e0 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67  alent to setting
213f0 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51   both .**     SQ
21400 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
21410 49 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f  ITE and SQLITE_O
21420 50 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 66  PEN_CREATE.  ^If
21430 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e   the mode option
21440 20 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 74   is.**     set t
21450 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20  o "memory" then 
21460 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72  a pure [in-memor
21470 79 20 64 61 74 61 62 61 73 65 5d 20 74 68 61 74  y database] that
21480 20 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a 20   never reads.** 
21490 20 20 20 20 6f 72 20 77 72 69 74 65 73 20 66 72      or writes fr
214a0 6f 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64 2e  om disk is used.
214b0 20 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72   ^It is an error
214c0 20 74 6f 20 73 70 65 63 69 66 79 20 61 20 76 61   to specify a va
214d0 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74  lue for.**     t
214e0 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65  he mode paramete
214f0 72 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 72  r that is less r
21500 65 73 74 72 69 63 74 69 76 65 20 74 68 61 6e 20  estrictive than 
21510 74 68 61 74 20 73 70 65 63 69 66 69 65 64 20 62  that specified b
21520 79 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c 61  y.**     the fla
21530 67 73 20 70 61 73 73 65 64 20 69 6e 20 74 68 65  gs passed in the
21540 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
21550 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
21560 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c  _v2()..**.**   <
21570 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e  li> <b>cache</b>
21580 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70 61 72  : ^The cache par
21590 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65  ameter may be se
215a0 74 20 74 6f 20 65 69 74 68 65 72 20 22 73 68 61  t to either "sha
215b0 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22  red" or.**     "
215c0 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69  private". ^Setti
215d0 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72 65 64  ng it to "shared
215e0 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20  " is equivalent 
215f0 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a  to setting the.*
21600 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45  *     SQLITE_OPE
21610 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 62 69  N_SHAREDCACHE bi
21620 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61  t in the flags a
21630 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74  rgument passed t
21640 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33  o.**     sqlite3
21650 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74  _open_v2(). ^Set
21660 74 69 6e 67 20 74 68 65 20 63 61 63 68 65 20 70  ting the cache p
21670 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69  arameter to "pri
21680 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20  vate" is .**    
21690 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73   equivalent to s
216a0 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54  etting the SQLIT
216b0 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
216c0 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20  CHE bit..**     
216d0 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ^If sqlite3_open
216e0 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e  _v2() is used an
216f0 64 20 74 68 65 20 22 63 61 63 68 65 22 20 70 61  d the "cache" pa
21700 72 61 6d 65 74 65 72 20 69 73 20 70 72 65 73 65  rameter is prese
21710 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55  nt in.**     a U
21720 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73  RI filename, its
21730 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73   value overrides
21740 20 61 6e 79 20 62 65 68 61 76 69 6f 72 20 72 65   any behavior re
21750 71 75 65 73 74 65 64 20 62 79 20 73 65 74 74 69  quested by setti
21760 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45  ng.**     SQLITE
21770 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
21780 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45  HE or SQLITE_OPE
21790 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 66 6c  N_SHAREDCACHE fl
217a0 61 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  ag..** </ul>.**.
217b0 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61  ** ^Specifying a
217c0 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65  n unknown parame
217d0 74 65 72 20 69 6e 20 74 68 65 20 71 75 65 72 79  ter in the query
217e0 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20   component of a 
217f0 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a  URI is not an.**
21800 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65 20   error.  Future 
21810 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
21820 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73 74  te might underst
21830 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 71  and additional q
21840 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65  uery.** paramete
21850 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72 79  rs.  See "[query
21860 20 70 61 72 61 6d 65 74 65 72 73 20 77 69 74 68   parameters with
21870 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67   special meaning
21880 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f 72   to SQLite]" for
21890 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  .** additional i
218a0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
218b0 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  * [[URI filename
218c0 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e   examples]] <h3>
218d0 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61  URI filename exa
218e0 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a  mples</h3>.**.**
218f0 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22   <table border="
21900 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20  1" align=center 
21910 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a  cellpadding=5>.*
21920 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 66  * <tr><th> URI f
21930 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65  ilenames <th> Re
21940 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64  sults.** <tr><td
21950 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c  > file:data.db <
21960 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
21970 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22   Open the file "
21980 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20  data.db" in the 
21990 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72  current director
219a0 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  y..** <tr><td> f
219b0 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  ile:/home/fred/d
219c0 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20  ata.db<br>.**   
219d0 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68         file:///h
219e0 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
219f0 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <br> .**       
21a00 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68     file://localh
21a10 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  ost/home/fred/da
21a20 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20  ta.db <br> <td> 
21a30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
21a40 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
21a50 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f  ile "/home/fred/
21a60 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72  data.db"..** <tr
21a70 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72  ><td> file://dar
21a80 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f  kstar/home/fred/
21a90 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a  data.db <td> .**
21aa0 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72            An err
21ab0 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20 69  or. "darkstar" i
21ac0 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a  s not a recogniz
21ad0 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a  ed authority..**
21ae0 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22   <tr><td style="
21af0 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72  white-space:nowr
21b00 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  ap"> .**        
21b10 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63    file:///C:/Doc
21b20 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30 53  uments%20and%20S
21b30 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 73  ettings/fred/Des
21b40 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20  ktop/data.db.** 
21b50 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73      <td> Windows
21b60 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20   only: Open the 
21b70 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 6f  file "data.db" o
21b80 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f 70  n fred's desktop
21b90 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 20   on drive.**    
21ba0 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74        C:. Note t
21bb0 68 61 74 20 74 68 65 20 25 32 30 20 65 73 63 61  hat the %20 esca
21bc0 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78 61  ping in this exa
21bd0 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 69  mple is not stri
21be0 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20  ctly .**        
21bf0 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73 70    necessary - sp
21c00 61 63 65 20 63 68 61 72 61 63 74 65 72 73 20 63  ace characters c
21c10 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65 72  an be used liter
21c20 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  ally.**         
21c30 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65   in URI filename
21c40 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  s..** <tr><td> f
21c50 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65  ile:data.db?mode
21c60 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61 74  =ro&cache=privat
21c70 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  e <td> .**      
21c80 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 64      Open file "d
21c90 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63  ata.db" in the c
21ca0 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79  urrent directory
21cb0 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61   for read-only a
21cc0 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20  ccess..**       
21cd0 20 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66     Regardless of
21ce0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
21cf0 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64  shared-cache mod
21d00 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 0a  e is enabled by.
21d10 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 61  **          defa
21d20 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76 61  ult, use a priva
21d30 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72  te cache..** <tr
21d40 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65  ><td> file:/home
21d50 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 66  /fred/data.db?vf
21d60 73 3d 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 20 3c 74  s=unix-nolock <t
21d70 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  d>.**          O
21d80 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f  pen file "/home/
21d90 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55  fred/data.db". U
21da0 73 65 20 74 68 65 20 73 70 65 63 69 61 6c 20 56  se the special V
21db0 46 53 20 22 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 22  FS "unix-nolock"
21dc0 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
21dd0 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d  le:data.db?mode=
21de0 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a  readonly <td> .*
21df0 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72  *          An er
21e00 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20  ror. "readonly" 
21e10 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f  is not a valid o
21e20 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d  ption for the "m
21e30 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a  ode" parameter..
21e40 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a  ** </table>.**.*
21e50 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d  * ^URI hexadecim
21e60 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e  al escape sequen
21e70 63 65 73 20 28 25 48 48 29 20 61 72 65 20 73 75  ces (%HH) are su
21e80 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74  pported within t
21e90 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71  he path and.** q
21ea0 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20  uery components 
21eb0 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65 78 61  of a URI. A hexa
21ec0 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
21ed0 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73  equence consists
21ee0 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74   of a.** percent
21ef0 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f   sign - "%" - fo
21f00 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c  llowed by exactl
21f10 79 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61  y two hexadecima
21f20 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65  l digits .** spe
21f30 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74  cifying an octet
21f40 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20   value. ^Before 
21f50 74 68 65 20 70 61 74 68 20 6f 72 20 71 75 65 72  the path or quer
21f60 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20  y components of 
21f70 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d  a.** URI filenam
21f80 65 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  e are interprete
21f90 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f  d, they are enco
21fa0 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20  ded using UTF-8 
21fb0 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61  and all .** hexa
21fc0 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
21fd0 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65  equences replace
21fe0 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79  d by a single by
21ff0 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  te containing th
22000 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69  e.** correspondi
22010 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69  ng octet. If thi
22020 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61  s process genera
22030 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55  tes an invalid U
22040 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a  TF-8 encoding,.*
22050 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  * the results ar
22060 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  e undefined..**.
22070 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69  ** <b>Note to Wi
22080 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e  ndows users:</b>
22090 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75    The encoding u
220a0 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65  sed for the file
220b0 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  name argument.**
220c0 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   of sqlite3_open
220d0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
220e0 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65  pen_v2() must be
220f0 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74   UTF-8, not what
22100 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65  ever.** codepage
22110 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65   is currently de
22120 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65  fined.  Filename
22130 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74  s containing int
22140 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68  ernational.** ch
22150 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65  aracters must be
22160 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54   converted to UT
22170 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73  F-8 prior to pas
22180 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a  sing them into.*
22190 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
221a0 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
221b0 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  _v2()..**.** <b>
221c0 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20  Note to Windows 
221d0 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f  Runtime users:</
221e0 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72  b>  The temporar
221f0 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74  y directory must
22200 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72   be set.** prior
22210 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69   to calling sqli
22220 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
22230 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
22240 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72    Otherwise, var
22250 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73  ious.** features
22260 20 74 68 61 74 20 72 65 71 75 69 72 65 20 74 68   that require th
22270 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61  e use of tempora
22280 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69  ry files may fai
22290 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  l..**.** See als
222a0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70  o: [sqlite3_temp
222b0 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 69  _directory].*/.i
222c0 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  nt sqlite3_open(
222d0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66  .  const char *f
222e0 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
222f0 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
22300 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c  (UTF-8) */.  sql
22310 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20  ite3 **ppDb     
22320 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
22330 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
22340 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
22350 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20  open16(.  const 
22360 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  void *filename, 
22370 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
22380 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20  lename (UTF-16) 
22390 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
223a0 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb          /* 
223b0 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
223c0 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20  andle */.);.int 
223d0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
223e0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66  .  const char *f
223f0 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
22400 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
22410 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c  (UTF-8) */.  sql
22420 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20  ite3 **ppDb,    
22430 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
22440 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
22450 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20  .  int flags,   
22460 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c             /* Fl
22470 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ags */.  const c
22480 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20  har *zVfs       
22490 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20   /* Name of VFS 
224a0 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f  module to use */
224b0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
224c0 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75  REF: Obtain Valu
224d0 65 73 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d  es For URI Param
224e0 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  eters.**.** Thes
224f0 65 20 61 72 65 20 75 74 69 6c 69 74 79 20 72 6f  e are utility ro
22500 75 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20 74  utines, useful t
22510 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  o VFS implementa
22520 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63  tions, that chec
22530 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61  k.** to see if a
22540 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
22550 61 73 20 61 20 55 52 49 20 74 68 61 74 20 63 6f  as a URI that co
22560 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63 69 66  ntained a specif
22570 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72  ic query .** par
22580 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73  ameter, and if s
22590 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61  o obtains the va
225a0 6c 75 65 20 6f 66 20 74 68 61 74 20 71 75 65 72  lue of that quer
225b0 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  y parameter..**.
225c0 2a 2a 20 49 66 20 46 20 69 73 20 74 68 65 20 64  ** If F is the d
225d0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
225e0 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20   pointer passed 
225f0 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29  into the xOpen()
22600 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61   method of .** a
22610 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
22620 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c 61  ion when the fla
22630 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  gs parameter to 
22640 78 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65 20  xOpen() has one 
22650 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74  or .** more of t
22660 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
22670 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  URI] or [SQLITE_
22680 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69  OPEN_MAIN_DB] bi
22690 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20  ts set and.** P 
226a0 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
226b0 68 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  he query paramet
226c0 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  er, then.** sqli
226d0 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
226e0 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 74  r(F,P) returns t
226f0 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
22700 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69  P.** parameter i
22710 66 20 69 74 20 65 78 69 73 74 73 20 6f 72 20 61  f it exists or a
22720 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
22730 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65   P does not appe
22740 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65 72  ar as a .** quer
22750 79 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46  y parameter on F
22760 2e 20 20 49 66 20 50 20 69 73 20 61 20 71 75 65  .  If P is a que
22770 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  ry parameter of 
22780 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c  F.** has no expl
22790 69 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65 6e  icit value, then
227a0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72   sqlite3_uri_par
227b0 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75  ameter(F,P) retu
227c0 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  rns.** a pointer
227d0 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72   to an empty str
227e0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ing..**.** The s
227f0 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
22800 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e  an(F,P,B) routin
22810 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 50  e assumes that P
22820 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a   is a boolean.**
22830 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72   parameter and r
22840 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20  eturns true (1) 
22850 6f 72 20 66 61 6c 73 65 20 28 30 29 20 61 63 63  or false (0) acc
22860 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76 61  ording to the va
22870 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68  lue.** of P.  Th
22880 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  e sqlite3_uri_bo
22890 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75  olean(F,P,B) rou
228a0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72 75  tine returns tru
228b0 65 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a 20  e (1) if the.** 
228c0 76 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20 70  value of query p
228d0 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e  arameter P is on
228e0 65 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72 75  e of "yes", "tru
228f0 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61  e", or "on" in a
22900 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69 66  ny.** case or if
22910 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e   the value begin
22920 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72  s with a non-zer
22930 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 0a  o number.  The .
22940 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  ** sqlite3_uri_b
22950 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
22960 75 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20 66  utines returns f
22970 61 6c 73 65 20 28 30 29 20 69 66 20 74 68 65 20  alse (0) if the 
22980 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72  value of.** quer
22990 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73  y parameter P is
229a0 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66   one of "no", "f
229b0 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22 20  alse", or "off" 
229c0 69 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a  in any case or.*
229d0 2a 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62  * if the value b
229e0 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75 6d  egins with a num
229f0 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20 50  eric zero.  If P
22a00 20 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79 0a   is not a query.
22a10 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20  ** parameter on 
22a20 46 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75  F or if the valu
22a30 65 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20 6e  e of P is does n
22a40 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66 20  ot match any of 
22a50 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68  the.** above, th
22a60 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  en sqlite3_uri_b
22a70 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65  oolean(F,P,B) re
22a80 74 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a  turns (B!=0)..**
22a90 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
22aa0 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29  uri_int64(F,P,D)
22ab0 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72 74   routine convert
22ac0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50  s the value of P
22ad0 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69   into a.** 64-bi
22ae0 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
22af0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68 61   and returns tha
22b00 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44 20  t integer, or D 
22b10 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  if P does not.**
22b20 20 65 78 69 73 74 2e 20 20 49 66 20 74 68 65 20   exist.  If the 
22b30 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73 6f  value of P is so
22b40 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68  mething other th
22b50 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74  an an integer, t
22b60 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72  hen.** zero is r
22b70 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20  eturned..** .** 
22b80 49 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20 70  If F is a NULL p
22b90 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71 6c  ointer, then sql
22ba0 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
22bb0 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20  er(F,P) returns 
22bc0 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  NULL and.** sqli
22bd0 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
22be0 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 42  F,P,B) returns B
22bf0 2e 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20 61  .  If F is not a
22c00 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e   NULL pointer an
22c10 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64 61  d.** is not a da
22c20 74 61 62 61 73 65 20 66 69 6c 65 20 70 61 74 68  tabase file path
22c30 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68 61  name pointer tha
22c40 74 20 53 51 4c 69 74 65 20 70 61 73 73 65 64 20  t SQLite passed 
22c50 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a  into the xOpen.*
22c60 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68  * VFS method, th
22c70 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
22c80 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  of this routine 
22c90 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
22ca0 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64   probably.** und
22cb0 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e  esirable..*/.con
22cc0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
22cd0 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63  _uri_parameter(c
22ce0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
22cf0 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72  name, const char
22d00 20 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e 74 20 73   *zParam);.int s
22d10 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
22d20 61 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  an(const char *z
22d30 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72  File, const char
22d40 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44   *zParam, int bD
22d50 65 66 61 75 6c 74 29 3b 0a 73 71 6c 69 74 65 33  efault);.sqlite3
22d60 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75  _int64 sqlite3_u
22d70 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20 63  ri_int64(const c
22d80 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  har*, const char
22d90 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
22da0 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  );.../*.** CAPI3
22db0 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73  REF: Error Codes
22dc0 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a   And Messages.**
22dd0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
22de0 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65 72  _errcode() inter
22df0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
22e00 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74   numeric [result
22e10 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78   code] or.** [ex
22e20 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
22e30 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 74  de] for the most
22e40 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20 73   recent failed s
22e50 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c  qlite3_* API cal
22e60 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  l.** associated 
22e70 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65  with a [database
22e80 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66   connection]. If
22e90 20 61 20 70 72 69 6f 72 20 41 50 49 20 63 61 6c   a prior API cal
22ea0 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20  l failed.** but 
22eb0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
22ec0 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65 64  API call succeed
22ed0 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76  ed, the return v
22ee0 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c  alue from.** sql
22ef0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69  ite3_errcode() i
22f00 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 5e 54  s undefined.  ^T
22f10 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  he sqlite3_exten
22f20 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a  ded_errcode().**
22f30 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68   interface is th
22f40 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 74 68  e same except th
22f50 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 65 74  at it always ret
22f60 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78  urns the .** [ex
22f70 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
22f80 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78  de] even when ex
22f90 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
22fa0 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62  des are.** disab
22fb0 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  led..**.** ^The 
22fc0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
22fd0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72   and sqlite3_err
22fe0 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45  msg16() return E
22ff0 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a  nglish-language.
23000 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73  ** text that des
23010 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72  cribes the error
23020 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d  , as either UTF-
23030 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70  8 or UTF-16 resp
23040 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d  ectively..** ^(M
23050 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
23060 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
23070 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65  string is manage
23080 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a  d internally..**
23090 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
230a0 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
230b0 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72  o worry about fr
230c0 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74  eeing the result
230d0 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68  ..** However, th
230e0 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d  e error string m
230f0 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 74  ight be overwrit
23100 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74  ten or deallocat
23110 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75  ed by.** subsequ
23120 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68  ent calls to oth
23130 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
23140 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e  ace functions.)^
23150 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
23160 74 65 33 5f 65 72 72 73 74 72 28 29 20 69 6e 74  te3_errstr() int
23170 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
23180 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75  he English-langu
23190 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 61 74  age text.** that
231a0 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 5b   describes the [
231b0 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73  result code], as
231c0 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d   UTF-8..** ^(Mem
231d0 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
231e0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
231f0 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20  ring is managed 
23200 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e  internally.** an
23210 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 66 72  d must not be fr
23220 65 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69  eed by the appli
23230 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20  cation)^..**.** 
23240 57 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69  When the seriali
23250 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
23260 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20  ode] is in use, 
23270 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a  it might be the.
23280 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61 20 73  ** case that a s
23290 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75  econd error occu
232a0 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65  rs on a separate
232b0 20 74 68 72 65 61 64 20 69 6e 20 62 65 74 77 65   thread in betwe
232c0 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f  en.** the time o
232d0 66 20 74 68 65 20 66 69 72 73 74 20 65 72 72 6f  f the first erro
232e0 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74  r and the call t
232f0 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  o these interfac
23300 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74  es..** When that
23310 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65   happens, the se
23320 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20  cond error will 
23330 62 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63  be reported sinc
23340 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72  e these.** inter
23350 66 61 63 65 73 20 61 6c 77 61 79 73 20 72 65 70  faces always rep
23360 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ort the most rec
23370 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20  ent result.  To 
23380 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65  avoid.** this, e
23390 61 63 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f  ach thread can o
233a0 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20  btain exclusive 
233b0 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61  use of the [data
233c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
233d0 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e   D.** by invokin
233e0 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
233f0 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33  _enter]([sqlite3
23400 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62  _db_mutex](D)) b
23410 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a  efore beginning.
23420 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20  ** to use D and 
23430 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65  invoking [sqlite
23440 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b  3_mutex_leave]([
23450 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78  sqlite3_db_mutex
23460 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61  ](D)) after.** a
23470 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20  ll calls to the 
23480 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74 65  interfaces liste
23490 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c  d here are compl
234a0 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  eted..**.** If a
234b0 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c  n interface fail
234c0 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49  s with SQLITE_MI
234d0 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73  SUSE, that means
234e0 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a   the interface.*
234f0 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e  * was invoked in
23500 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68 65  correctly by the
23510 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49   application.  I
23520 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 68 65  n that case, the
23530 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61  .** error code a
23540 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f  nd message may o
23550 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74  r may not be set
23560 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
23570 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33  _errcode(sqlite3
23580 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74   *db);.int sqlit
23590 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63  e3_extended_errc
235a0 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29  ode(sqlite3 *db)
235b0 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
235c0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c  lite3_errmsg(sql
235d0 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  ite3*);.const vo
235e0 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d  id *sqlite3_errm
235f0 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a  sg16(sqlite3*);.
23600 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
23610 74 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29 3b  te3_errstr(int);
23620 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
23630 3a 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  : SQL Statement 
23640 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52  Object.** KEYWOR
23650 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74  DS: {prepared st
23660 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72  atement} {prepar
23670 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a  ed statements}.*
23680 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
23690 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
236a0 72 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e  represents a sin
236b0 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  gle SQL statemen
236c0 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63  t..** This objec
236d0 74 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b  t is variously k
236e0 6e 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70 61  nown as a "prepa
236f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f  red statement" o
23700 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64  r a.** "compiled
23710 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20   SQL statement" 
23720 6f 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22  or simply as a "
23730 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a  statement"..**.*
23740 2a 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20  * The life of a 
23750 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74  statement object
23760 20 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20   goes something 
23770 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a  like this:.**.**
23780 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72   <ol>.** <li> Cr
23790 65 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20  eate the object 
237a0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  using [sqlite3_p
237b0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
237c0 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20  a related.**    
237d0 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c    function..** <
237e0 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20  li> Bind values 
237f0 74 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74  to [host paramet
23800 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73  ers] using the s
23810 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a  qlite3_bind_*().
23820 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 63  **      interfac
23830 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20  es..** <li> Run 
23840 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69  the SQL by calli
23850 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
23860 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  ()] one or more 
23870 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52  times..** <li> R
23880 65 73 65 74 20 74 68 65 20 73 74 61 74 65 6d 65  eset the stateme
23890 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  nt using [sqlite
238a0 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20  3_reset()] then 
238b0 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20  go back.**      
238c0 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74  to step 2.  Do t
238d0 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  his zero or more
238e0 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20   times..** <li> 
238f0 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65  Destroy the obje
23900 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ct using [sqlite
23910 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a  3_finalize()]..*
23920 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65  * </ol>.**.** Re
23930 66 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61  fer to documenta
23940 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75  tion on individu
23950 61 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  al methods above
23960 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a   for additional.
23970 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  ** information..
23980 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
23990 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73  t sqlite3_stmt s
239a0 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a  qlite3_stmt;../*
239b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75  .** CAPI3REF: Ru
239c0 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a  n-time Limits.**
239d0 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72  .** ^(This inter
239e0 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20  face allows the 
239f0 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20  size of various 
23a00 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65  constructs to be
23a10 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61   limited.** on a
23a20 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63   connection by c
23a30 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e  onnection basis.
23a40 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61    The first para
23a50 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
23a60 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
23a70 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69  tion] whose limi
23a80 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f  t is to be set o
23a90 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a  r queried.  The.
23aa0 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
23ab0 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68  ter is one of th
23ac0 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  e [limit categor
23ad0 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65  ies] that define
23ae0 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63   a.** class of c
23af0 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
23b00 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54  size limited.  T
23b10 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
23b20 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77  er is the.** new
23b30 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20   limit for that 
23b40 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a  construct.)^.**.
23b50 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c  ** ^If the new l
23b60 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69  imit is a negati
23b70 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c  ve number, the l
23b80 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65  imit is unchange
23b90 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68  d..** ^(For each
23ba0 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20   limit category 
23bb0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e  SQLITE_LIMIT_<i>
23bc0 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69  NAME</i> there i
23bd0 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20  s a .** [limits 
23be0 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  | hard upper bou
23bf0 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f  nd].** set at co
23c00 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20  mpile-time by a 
23c10 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
23c20 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b  acro called.** [
23c30 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f  limits | SQLITE_
23c40 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d  MAX_<i>NAME</i>]
23c50 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49  ..** (The "_LIMI
23c60 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  T_" in the name 
23c70 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f  is changed to "_
23c80 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74  MAX_".))^.** ^At
23c90 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61  tempts to increa
23ca0 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65  se a limit above
23cb0 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20   its hard upper 
23cc0 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c  bound are.** sil
23cd0 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20  ently truncated 
23ce0 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65  to the hard uppe
23cf0 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e  r bound..**.** ^
23d00 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  Regardless of wh
23d10 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
23d20 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67   limit was chang
23d30 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c  ed, the .** [sql
23d40 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e  ite3_limit()] in
23d50 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
23d60 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20  the prior value 
23d70 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a  of the limit..**
23d80 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64   ^Hence, to find
23d90 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c   the current val
23da0 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69  ue of a limit wi
23db0 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69  thout changing i
23dc0 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76  t,.** simply inv
23dd0 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66 61  oke this interfa
23de0 63 65 20 77 69 74 68 20 74 68 65 20 74 68 69 72  ce with the thir
23df0 64 20 70 61 72 61 6d 65 74 65 72 20 73 65 74 20  d parameter set 
23e00 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e  to -1..**.** Run
23e10 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65  -time limits are
23e20 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
23e30 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  e in application
23e40 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a  s that manage.**
23e50 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20   both their own 
23e60 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73  internal databas
23e70 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62  e and also datab
23e80 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f  ases that are co
23e90 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75  ntrolled.** by u
23ea0 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61  ntrusted externa
23eb0 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65  l sources.  An e
23ec0 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69  xample applicati
23ed0 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a  on might be a.**
23ee0 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 61   web browser tha
23ef0 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61  t has its own da
23f00 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72  tabases for stor
23f10 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a  ing history and.
23f20 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61  ** separate data
23f30 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64  bases controlled
23f40 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61   by JavaScript a
23f50 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e  pplications down
23f60 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68  loaded.** off th
23f70 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65  e Internet.  The
23f80 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61   internal databa
23f90 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e  ses can be given
23fa0 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64   the.** large, d
23fb0 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20  efault limits.  
23fc0 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65  Databases manage
23fd0 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f  d by external so
23fe0 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20  urces can.** be 
23ff0 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c  given much small
24000 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e  er limits design
24010 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20  ed to prevent a 
24020 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63  denial of servic
24030 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65  e.** attack.  De
24040 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61  velopers might a
24050 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20  lso want to use 
24060 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  the [sqlite3_set
24070 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a  _authorizer()].*
24080 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66  * interface to f
24090 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75  urther control u
240a0 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54  ntrusted SQL.  T
240b0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64  he size of the d
240c0 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74  atabase.** creat
240d0 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74  ed by an untrust
240e0 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65  ed script can be
240f0 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67   contained using
24100 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67   the.** [max_pag
24110 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41  e_count] [PRAGMA
24120 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e  ]..**.** New run
24130 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65  -time limit cate
24140 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64  gories may be ad
24150 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
24160 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73  leases..*/.int s
24170 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c  qlite3_limit(sql
24180 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69  ite3*, int id, i
24190 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a  nt newVal);../*.
241a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
241b0 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65  -Time Limit Cate
241c0 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52  gories.** KEYWOR
241d0 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67  DS: {limit categ
241e0 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74  ory} {*limit cat
241f0 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54  egories}.**.** T
24200 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64  hese constants d
24210 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65  efine various pe
24220 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73  rformance limits
24230 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20  .** that can be 
24240 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74  lowered at run-t
24250 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ime using [sqlit
24260 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20  e3_limit()]..** 
24270 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20  The synopsis of 
24280 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20  the meanings of 
24290 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69  the various limi
242a0 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f  ts is shown belo
242b0 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c  w..** Additional
242c0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
242d0 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69  available at [li
242e0 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e  mits | Limits in
242f0 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20   SQLite]..**.** 
24300 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  <dl>.** [[SQLITE
24310 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20  _LIMIT_LENGTH]] 
24320 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
24330 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  IT_LENGTH</dt>.*
24340 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
24350 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74  m size of any st
24360 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20  ring or BLOB or 
24370 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79  table row, in by
24380 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  tes.<dd>)^.**.**
24390 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
243a0 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c  SQL_LENGTH]] ^(<
243b0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
243c0 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  SQL_LENGTH</dt>.
243d0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
243e0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20  um length of an 
243f0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69  SQL statement, i
24400 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a  n bytes.</dd>)^.
24410 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
24420 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28  IMIT_COLUMN]] ^(
24430 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
24440 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20  _COLUMN</dt>.** 
24450 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
24460 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
24470 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66  s in a table def
24480 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68  inition or in th
24490 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20  e.** result set 
244a0 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72  of a [SELECT] or
244b0 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
244c0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
244d0 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72  n an index.** or
244e0 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20   in an ORDER BY 
244f0 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75  or GROUP BY clau
24500 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  se.</dd>)^.**.**
24510 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
24520 45 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c  EXPR_DEPTH]] ^(<
24530 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
24540 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a  EXPR_DEPTH</dt>.
24550 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
24560 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20  um depth of the 
24570 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e  parse tree on an
24580 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64  y expression.</d
24590 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
245a0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
245b0 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64  ND_SELECT]] ^(<d
245c0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  t>SQLITE_LIMIT_C
245d0 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f  OMPOUND_SELECT</
245e0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
245f0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
24600 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70   terms in a comp
24610 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74  ound SELECT stat
24620 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ement.</dd>)^.**
24630 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
24640 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c  IT_VDBE_OP]] ^(<
24650 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
24660 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20  VDBE_OP</dt>.** 
24670 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
24680 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75  number of instru
24690 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74  ctions in a virt
246a0 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67  ual machine prog
246b0 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69  ram.** used to i
246c0 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20  mplement an SQL 
246d0 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 69 73  statement.  This
246e0 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 75   limit is not cu
246f0 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72  rrently.** enfor
24700 63 65 64 2c 20 74 68 6f 75 67 68 20 74 68 61 74  ced, though that
24710 20 6d 69 67 68 74 20 62 65 20 61 64 64 65 64 20   might be added 
24720 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72  in some future r
24730 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c  elease of.** SQL
24740 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ite.</dd>)^.**.*
24750 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
24760 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20  _FUNCTION_ARG]] 
24770 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
24780 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c  IT_FUNCTION_ARG<
24790 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
247a0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
247b0 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61  f arguments on a
247c0 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29   function.</dd>)
247d0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
247e0 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 5d  _LIMIT_ATTACHED]
247f0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
24800 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64  IMIT_ATTACHED</d
24810 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
24820 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
24830 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61 63 68  [ATTACH | attach
24840 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29 5e  ed databases].)^
24850 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
24860 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f  LITE_LIMIT_LIKE_
24870 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d  PATTERN_LENGTH]]
24880 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
24890 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
248a0 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  ERN_LENGTH</dt>.
248b0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
248c0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  um length of the
248d0 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e   pattern argumen
248e0 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20  t to the [LIKE] 
248f0 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65  or.** [GLOB] ope
24900 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a  rators.</dd>)^.*
24910 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
24920 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
24930 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53  BER]].** ^(<dt>S
24940 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
24950 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e  ABLE_NUMBER</dt>
24960 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
24970 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 72  mum index number
24980 20 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 74   of any [paramet
24990 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 74  er] in an SQL st
249a0 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a  atement.)^.**.**
249b0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
249c0 54 52 49 47 47 45 52 5f 44 45 50 54 48 5d 5d 20  TRIGGER_DEPTH]] 
249d0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
249e0 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  IT_TRIGGER_DEPTH
249f0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
24a00 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f   maximum depth o
24a10 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20  f recursion for 
24a20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e  triggers.</dd>)^
24a30 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
24a40 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
24a50 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20  T_LENGTH        
24a60 20 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64              0.#d
24a70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
24a80 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20  IT_SQL_LENGTH   
24a90 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23               1.#
24aa0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
24ab0 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20  MIT_COLUMN      
24ac0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a                2.
24ad0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
24ae0 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20  IMIT_EXPR_DEPTH 
24af0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33                 3
24b00 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
24b10 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53  LIMIT_COMPOUND_S
24b20 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20  ELECT           
24b30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
24b40 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20  _LIMIT_VDBE_OP  
24b50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
24b60 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   5.#define SQLIT
24b70 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
24b80 5f 41 52 47 20 20 20 20 20 20 20 20 20 20 20 20  _ARG            
24b90 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    6.#define SQLI
24ba0 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
24bb0 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  D               
24bc0 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c     7.#define SQL
24bd0 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50  ITE_LIMIT_LIKE_P
24be0 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20  ATTERN_LENGTH   
24bf0 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51      8.#define SQ
24c00 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
24c10 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20  BLE_NUMBER      
24c20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53       9.#define S
24c30 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
24c40 47 45 52 5f 44 45 50 54 48 20 20 20 20 20 20 20  GER_DEPTH       
24c50 20 20 20 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43       10../*.** C
24c60 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69  API3REF: Compili
24c70 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  ng An SQL Statem
24c80 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ent.** KEYWORDS:
24c90 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20   {SQL statement 
24ca0 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20  compiler}.**.** 
24cb0 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53 51  To execute an SQ
24cc0 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74  L query, it must
24cd0 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c   first be compil
24ce0 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63  ed into a byte-c
24cf0 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75  ode.** program u
24d00 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73  sing one of thes
24d10 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  e routines..**.*
24d20 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
24d30 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61  ment, "db", is a
24d40 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
24d50 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20  ction] obtained 
24d60 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20  from a.** prior 
24d70 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
24d80 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
24d90 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
24da0 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b  en_v2()] or.** [
24db0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
24dc0 5d 2e 20 20 54 68 65 20 64 61 74 61 62 61 73 65  ].  The database
24dd0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74   connection must
24de0 20 6e 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63   not have been c
24df0 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  losed..**.** The
24e00 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
24e10 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65  , "zSql", is the
24e20 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
24e30 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64   compiled, encod
24e40 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20  ed.** as either 
24e50 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e  UTF-8 or UTF-16.
24e60 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72    The sqlite3_pr
24e70 65 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69  epare() and sqli
24e80 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
24e90 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75  .** interfaces u
24ea0 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71  se UTF-8, and sq
24eb0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
24ec0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  ) and sqlite3_pr
24ed0 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20  epare16_v2().** 
24ee0 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a  use UTF-16..**.*
24ef0 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20  * ^If the nByte 
24f00 61 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73  argument is less
24f10 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e   than zero, then
24f20 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70   zSql is read up
24f30 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74   to the.** first
24f40 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
24f50 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 6e  . ^If nByte is n
24f60 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
24f70 6e 20 69 74 20 69 73 20 74 68 65 20 6d 61 78 69  n it is the maxi
24f80 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  mum.** number of
24f90 20 20 62 79 74 65 73 20 72 65 61 64 20 66 72 6f    bytes read fro
24fa0 6d 20 7a 53 71 6c 2e 20 20 5e 57 68 65 6e 20 6e  m zSql.  ^When n
24fb0 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  Byte is non-nega
24fc0 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71  tive, the.** zSq
24fd0 6c 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74  l string ends at
24fe0 20 65 69 74 68 65 72 20 74 68 65 20 66 69 72 73   either the firs
24ff0 74 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 30  t '\000' or '\u0
25000 30 30 30 27 20 63 68 61 72 61 63 74 65 72 20 6f  000' character o
25010 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d 74  r.** the nByte-t
25020 68 20 62 79 74 65 2c 20 77 68 69 63 68 65 76 65  h byte, whicheve
25030 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 49  r comes first. I
25040 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f  f the caller kno
25050 77 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73  ws.** that the s
25060 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69  upplied string i
25070 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64  s nul-terminated
25080 2c 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20  , then there is 
25090 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f  a small.** perfo
250a0 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65  rmance advantage
250b0 20 74 6f 20 62 65 20 67 61 69 6e 65 64 20 62 79   to be gained by
250c0 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74   passing an nByt
250d0 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74  e parameter that
250e0 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f 20  .** is equal to 
250f0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
25100 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74  tes in the input
25110 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75   string <i>inclu
25120 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20  ding</i>.** the 
25130 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62  nul-terminator b
25140 79 74 65 73 20 61 73 20 74 68 69 73 20 73 61 76  ytes as this sav
25150 65 73 20 53 51 4c 69 74 65 20 66 72 6f 6d 20 68  es SQLite from h
25160 61 76 69 6e 67 20 74 6f 0a 2a 2a 20 6d 61 6b 65  aving to.** make
25170 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 69   a copy of the i
25180 6e 70 75 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  nput string..**.
25190 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73  ** ^If pzTail is
251a0 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a   not NULL then *
251b0 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74  pzTail is made t
251c0 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66  o point to the f
251d0 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73  irst byte.** pas
251e0 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65  t the end of the
251f0 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65   first SQL state
25200 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54  ment in zSql.  T
25210 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e  hese routines on
25220 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68  ly.** compile th
25230 65 20 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e  e first statemen
25240 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70  t in zSql, so *p
25250 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f  zTail is left po
25260 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61  inting to.** wha
25270 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70  t remains uncomp
25280 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70  iled..**.** ^*pp
25290 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69  Stmt is left poi
252a0 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69  nting to a compi
252b0 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  led [prepared st
252c0 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61  atement] that ca
252d0 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64  n be.** executed
252e0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
252f0 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68  step()].  ^If th
25300 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c  ere is an error,
25310 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a   *ppStmt is set.
25320 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66  ** to NULL.  ^If
25330 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20   the input text 
25340 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20  contains no SQL 
25350 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73  (if the input is
25360 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72   an empty.** str
25370 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74  ing or a comment
25380 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69  ) then *ppStmt i
25390 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  s set to NULL..*
253a0 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72  * The calling pr
253b0 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f  ocedure is respo
253c0 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74  nsible for delet
253d0 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64  ing the compiled
253e0 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
253f0 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
25400 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74  _finalize()] aft
25410 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68  er it has finish
25420 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70  ed with it..** p
25430 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65  pStmt may not be
25440 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e   NULL..**.** ^On
25450 20 73 75 63 63 65 73 73 2c 20 74 68 65 20 73 71   success, the sq
25460 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20  lite3_prepare() 
25470 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e  family of routin
25480 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
25490 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77  E_OK];.** otherw
254a0 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ise an [error co
254b0 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
254c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
254d0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20  e3_prepare_v2() 
254e0 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
254f0 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72  are16_v2() inter
25500 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63  faces are.** rec
25510 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c  ommended for all
25520 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54   new programs. T
25530 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74  he two older int
25540 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74 61  erfaces are reta
25550 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b  ined.** for back
25560 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
25570 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75  ity, but their u
25580 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65  se is discourage
25590 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76  d..** ^In the "v
255a0 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74  2" interfaces, t
255b0 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
255c0 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73  ement.** that is
255d0 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b   returned (the [
255e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
255f0 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61  ject) contains a
25600 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
25610 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78  original SQL tex
25620 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74  t. This causes t
25630 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
25640 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f  ()] interface to
25650 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66 65  .** behave diffe
25660 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20  rently in three 
25670 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  ways:.**.** <ol>
25680 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20  .** <li>.** ^If 
25690 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  the database sch
256a0 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73  ema changes, ins
256b0 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e  tead of returnin
256c0 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  g [SQLITE_SCHEMA
256d0 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79  ] as it.** alway
256e0 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73  s used to do, [s
256f0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
25700 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ill automaticall
25710 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20  y recompile the 
25720 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  SQL.** statement
25730 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20   and try to run 
25740 69 74 20 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e  it again. As man
25750 79 20 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58  y as [SQLITE_MAX
25760 5f 53 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a  _SCHEMA_RETRY].*
25770 2a 20 72 65 74 72 69 65 73 20 77 69 6c 6c 20 6f  * retries will o
25780 63 63 75 72 20 62 65 66 6f 72 65 20 73 71 6c 69  ccur before sqli
25790 74 65 33 5f 73 74 65 70 28 29 20 67 69 76 65 73  te3_step() gives
257a0 20 75 70 20 61 6e 64 20 72 65 74 75 72 6e 73 20   up and returns 
257b0 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c  an error..** </l
257c0 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a  i>.**.** <li>.**
257d0 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20   ^When an error 
257e0 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33  occurs, [sqlite3
257f0 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65  _step()] will re
25800 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20  turn one of the 
25810 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72  detailed.** [err
25820 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78  or codes] or [ex
25830 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
25840 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63  es].  ^The legac
25850 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74  y behavior was t
25860 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  hat.** [sqlite3_
25870 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e  step()] would on
25880 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65  ly return a gene
25890 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ric [SQLITE_ERRO
258a0 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a  R] result code.*
258b0 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63  * and the applic
258c0 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65  ation would have
258d0 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e   to make a secon
258e0 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  d call to [sqlit
258f0 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69  e3_reset()].** i
25900 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20  n order to find 
25910 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63  the underlying c
25920 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62  ause of the prob
25930 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76  lem. With the "v
25940 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e  2" prepare.** in
25950 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e  terfaces, the un
25960 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20  derlying reason 
25970 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73  for the error is
25980 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
25990 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  ately..** </li>.
259a0 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49  **.** <li>.** ^I
259b0 66 20 74 68 65 20 73 70 65 63 69 66 69 63 20 76  f the specific v
259c0 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70  alue bound to [p
259d0 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20  arameter | host 
259e0 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68  parameter] in th
259f0 65 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75  e .** WHERE clau
25a00 73 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e  se might influen
25a10 63 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66  ce the choice of
25a20 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20   query plan for 
25a30 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20  a statement,.** 
25a40 74 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65  then the stateme
25a50 6e 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d  nt will be autom
25a60 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69  atically recompi
25a70 6c 65 64 2c 20 61 73 20 69 66 20 74 68 65 72 65  led, as if there
25a80 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20   had been .** a 
25a90 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f  schema change, o
25aa0 6e 20 74 68 65 20 66 69 72 73 74 20 20 5b 73 71  n the first  [sq
25ab0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61  lite3_step()] ca
25ac0 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79  ll following any
25ad0 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68   change.** to th
25ae0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
25af0 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d  text | bindings]
25b00 20 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65   of that [parame
25b10 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73  ter]. .** ^The s
25b20 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66  pecific value of
25b30 20 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70   WHERE-clause [p
25b40 61 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20  arameter] might 
25b50 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a  influence the .*
25b60 2a 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72  * choice of quer
25b70 79 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61  y plan if the pa
25b80 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c  rameter is the l
25b90 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66  eft-hand side of
25ba0 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20   a [LIKE].** or 
25bb0 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20  [GLOB] operator 
25bc0 6f 72 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  or if the parame
25bd0 74 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20  ter is compared 
25be0 74 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f  to an indexed co
25bf0 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20  lumn.** and the 
25c00 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53  [SQLITE_ENABLE_S
25c10 54 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  TAT3] compile-ti
25c20 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61  me option is ena
25c30 62 6c 65 64 2e 0a 2a 2a 20 74 68 65 20 0a 2a 2a  bled..** the .**
25c40 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a   </li>.** </ol>.
25c50 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  */.int sqlite3_p
25c60 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65  repare(.  sqlite
25c70 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
25c80 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
25c90 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
25ca0 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
25cb0 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
25cc0 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
25cd0 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
25ce0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
25cf0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
25d00 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
25d10 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
25d20 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
25d30 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
25d40 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
25d50 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
25d60 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
25d70 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
25d80 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
25d90 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
25da0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20  3_prepare_v2(.  
25db0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
25dc0 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
25dd0 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
25de0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
25df0 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
25e00 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20  tatement, UTF-8 
25e10 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
25e20 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
25e30 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
25e40 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
25e50 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
25e60 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
25e70 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
25e80 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
25e90 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
25ea0 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
25eb0 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
25ec0 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
25ed0 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
25ee0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
25ef0 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
25f00 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
25f10 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
25f20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
25f30 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
25f40 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
25f50 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
25f60 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
25f70 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
25f80 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
25f90 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
25fa0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
25fb0 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
25fc0 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
25fd0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
25fe0 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
25ff0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
26000 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
26010 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
26020 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
26030 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71  epare16_v2(.  sq
26040 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
26050 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
26060 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
26070 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
26080 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
26090 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
260a0 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
260b0 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
260c0 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
260d0 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
260e0 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
260f0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
26100 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
26110 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
26120 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
26130 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
26140 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
26150 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
26160 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  zSql */.);../*.*
26170 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72  * CAPI3REF: Retr
26180 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74  ieving Statement
26190 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73   SQL.**.** ^This
261a0 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
261b0 65 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65  e used to retrie
261c0 76 65 20 61 20 73 61 76 65 64 20 63 6f 70 79 20  ve a saved copy 
261d0 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a  of the original.
261e0 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64  ** SQL text used
261f0 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72   to create a [pr
26200 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
26210 5d 20 69 66 20 74 68 61 74 20 73 74 61 74 65 6d  ] if that statem
26220 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69  ent was.** compi
26230 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72  led using either
26240 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
26250 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
26260 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
26270 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ()]..*/.const ch
26280 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28  ar *sqlite3_sql(
26290 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
262a0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
262b0 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
262c0 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65   If An SQL State
262d0 6d 65 6e 74 20 57 72 69 74 65 73 20 54 68 65 20  ment Writes The 
262e0 44 61 74 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20 5e  Database.**.** ^
262f0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  The sqlite3_stmt
26300 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74  _readonly(X) int
26310 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
26320 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69  rue (non-zero) i
26330 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66  f.** and only if
26340 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
26350 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65  tatement] X make
26360 73 20 6e 6f 20 64 69 72 65 63 74 20 63 68 61 6e  s no direct chan
26370 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f  ges to.** the co
26380 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74  ntent of the dat
26390 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a  abase file..**.*
263a0 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 61 70 70  * Note that [app
263b0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
263c0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20   SQL functions] 
263d0 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74  or.** [virtual t
263e0 61 62 6c 65 73 5d 20 6d 69 67 68 74 20 63 68 61  ables] might cha
263f0 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  nge the database
26400 20 69 6e 64 69 72 65 63 74 6c 79 20 61 73 20 61   indirectly as a
26410 20 73 69 64 65 20 65 66 66 65 63 74 2e 20 20 0a   side effect.  .
26420 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65  ** ^(For example
26430 2c 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74  , if an applicat
26440 69 6f 6e 20 64 65 66 69 6e 65 73 20 61 20 66 75  ion defines a fu
26450 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28 29 22 20  nction "eval()" 
26460 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b  that .** calls [
26470 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c  sqlite3_exec()],
26480 20 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77   then the follow
26490 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ing SQL statemen
264a0 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67  t would.** chang
264b0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  e the database f
264c0 69 6c 65 20 74 68 72 6f 75 67 68 20 73 69 64 65  ile through side
264d0 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20  -effects:.**.** 
264e0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
264f0 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54 20 65  >.**    SELECT e
26500 76 61 6c 28 27 44 45 4c 45 54 45 20 46 52 4f 4d  val('DELETE FROM
26510 20 74 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a   t1') FROM t2;.*
26520 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
26530 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20  uote>.**.** But 
26540 62 65 63 61 75 73 65 20 74 68 65 20 5b 53 45 4c  because the [SEL
26550 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 64  ECT] statement d
26560 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
26570 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
26580 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20 73 71  .** directly, sq
26590 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
265a0 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73 74 69 6c  nly() would stil
265b0 6c 20 72 65 74 75 72 6e 20 74 72 75 65 2e 29 5e  l return true.)^
265c0 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74  .**.** ^Transact
265d0 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74  ion control stat
265e0 65 6d 65 6e 74 73 20 73 75 63 68 20 61 73 20 5b  ements such as [
265f0 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d  BEGIN], [COMMIT]
26600 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a  , [ROLLBACK],.**
26610 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e   [SAVEPOINT], an
26620 64 20 5b 52 45 4c 45 41 53 45 5d 20 63 61 75 73  d [RELEASE] caus
26630 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  e sqlite3_stmt_r
26640 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74  eadonly() to ret
26650 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e  urn true,.** sin
26660 63 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ce the statement
26670 73 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20  s themselves do 
26680 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64  not actually mod
26690 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65  ify the database
266a0 20 62 75 74 0a 2a 2a 20 72 61 74 68 65 72 20 74   but.** rather t
266b0 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20  hey control the 
266c0 74 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f  timing of when o
266d0 74 68 65 72 20 73 74 61 74 65 6d 65 6e 74 73 20  ther statements 
266e0 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a 20 64  modify the .** d
266f0 61 74 61 62 61 73 65 2e 20 20 5e 54 68 65 20 5b  atabase.  ^The [
26700 41 54 54 41 43 48 5d 20 61 6e 64 20 5b 44 45 54  ATTACH] and [DET
26710 41 43 48 5d 20 73 74 61 74 65 6d 65 6e 74 73 20  ACH] statements 
26720 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71  also cause.** sq
26730 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
26740 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20  nly() to return 
26750 74 72 75 65 20 73 69 6e 63 65 2c 20 77 68 69 6c  true since, whil
26760 65 20 74 68 6f 73 65 20 73 74 61 74 65 6d 65 6e  e those statemen
26770 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65  ts.** change the
26780 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
26790 66 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  f a database con
267a0 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f  nection, they do
267b0 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68   not make .** ch
267c0 61 6e 67 65 73 20 74 6f 20 74 68 65 20 63 6f 6e  anges to the con
267d0 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61  tent of the data
267e0 62 61 73 65 20 66 69 6c 65 73 20 6f 6e 20 64 69  base files on di
267f0 73 6b 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  sk..*/.int sqlit
26800 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
26810 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
26820 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
26830 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
26840 65 20 49 66 20 41 20 50 72 65 70 61 72 65 64 20  e If A Prepared 
26850 53 74 61 74 65 6d 65 6e 74 20 48 61 73 20 42 65  Statement Has Be
26860 65 6e 20 52 65 73 65 74 0a 2a 2a 0a 2a 2a 20 5e  en Reset.**.** ^
26870 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  The sqlite3_stmt
26880 5f 62 75 73 79 28 53 29 20 69 6e 74 65 72 66 61  _busy(S) interfa
26890 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  ce returns true 
268a0 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68  (non-zero) if th
268b0 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
268c0 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 73 20  tatement] S has 
268d0 62 65 65 6e 20 73 74 65 70 70 65 64 20 61 74 20  been stepped at 
268e0 6c 65 61 73 74 20 6f 6e 63 65 20 75 73 69 6e 67  least once using
268f0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74   .** [sqlite3_st
26900 65 70 28 53 29 5d 20 62 75 74 20 68 61 73 20 6e  ep(S)] but has n
26910 6f 74 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65  ot run to comple
26920 74 69 6f 6e 20 61 6e 64 2f 6f 72 20 68 61 73 20  tion and/or has 
26930 6e 6f 74 20 0a 2a 2a 20 62 65 65 6e 20 72 65 73  not .** been res
26940 65 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  et using [sqlite
26950 33 5f 72 65 73 65 74 28 53 29 5d 2e 20 20 5e 54  3_reset(S)].  ^T
26960 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  he sqlite3_stmt_
26970 62 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72  busy(S).** inter
26980 66 61 63 65 20 72 65 74 75 72 6e 73 20 66 61 6c  face returns fal
26990 73 65 20 69 66 20 53 20 69 73 20 61 20 4e 55 4c  se if S is a NUL
269a0 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 53  L pointer.  If S
269b0 20 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55   is not a .** NU
269c0 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 69  LL pointer and i
269d0 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72 20  s not a pointer 
269e0 74 6f 20 61 20 76 61 6c 69 64 20 5b 70 72 65 70  to a valid [prep
269f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
26a00 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20  ** object, then 
26a10 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
26a20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72  undefined and pr
26a30 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62  obably undesirab
26a40 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  le..**.** This i
26a50 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20  nterface can be 
26a60 75 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74  used in combinat
26a70 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78  ion [sqlite3_nex
26a80 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20  t_stmt()].** to 
26a90 6c 6f 63 61 74 65 20 61 6c 6c 20 70 72 65 70 61  locate all prepa
26aa0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20 61  red statements a
26ab0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61  ssociated with a
26ac0 20 64 61 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f   database .** co
26ad0 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 61 72  nnection that ar
26ae0 65 20 69 6e 20 6e 65 65 64 20 6f 66 20 62 65 69  e in need of bei
26af0 6e 67 20 72 65 73 65 74 2e 20 20 54 68 69 73 20  ng reset.  This 
26b00 63 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20  can be used,.** 
26b10 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20  for example, in 
26b20 64 69 61 67 6e 6f 73 74 69 63 20 72 6f 75 74 69  diagnostic routi
26b30 6e 65 73 20 74 6f 20 73 65 61 72 63 68 20 66 6f  nes to search fo
26b40 72 20 70 72 65 70 61 72 65 64 20 0a 2a 2a 20 73  r prepared .** s
26b50 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 61  tatements that a
26b60 72 65 20 68 6f 6c 64 69 6e 67 20 61 20 74 72 61  re holding a tra
26b70 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a  nsaction open..*
26b80 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  /.int sqlite3_st
26b90 6d 74 5f 62 75 73 79 28 73 71 6c 69 74 65 33 5f  mt_busy(sqlite3_
26ba0 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
26bb0 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63  API3REF: Dynamic
26bc0 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65  ally Typed Value
26bd0 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f   Object.** KEYWO
26be0 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20  RDS: {protected 
26bf0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b  sqlite3_value} {
26c00 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
26c10 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a  te3_value}.**.**
26c20 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65   SQLite uses the
26c30 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
26c40 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73 65  bject to represe
26c50 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a  nt all values.**
26c60 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f   that can be sto
26c70 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 73  red in a databas
26c80 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20  e table. SQLite 
26c90 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70  uses dynamic typ
26ca0 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76  ing.** for the v
26cb0 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e  alues it stores.
26cc0 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64    ^Values stored
26cd0 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75   in sqlite3_valu
26ce0 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e  e objects.** can
26cf0 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c   be integers, fl
26d00 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
26d10 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c  ues, strings, BL
26d20 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a  OBs, or NULL..**
26d30 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76  .** An sqlite3_v
26d40 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20  alue object may 
26d50 62 65 20 65 69 74 68 65 72 20 22 70 72 6f 74 65  be either "prote
26d60 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74  cted" or "unprot
26d70 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20  ected"..** Some 
26d80 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69  interfaces requi
26d90 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 20 73  re a protected s
26da0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f  qlite3_value.  O
26db0 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a  ther interfaces.
26dc0 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65  ** will accept e
26dd0 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 74 65  ither a protecte
26de0 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63  d or an unprotec
26df0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
26e00 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65  e..** Every inte
26e10 72 66 61 63 65 20 74 68 61 74 20 61 63 63 65 70  rface that accep
26e20 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ts sqlite3_value
26e30 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69   arguments speci
26e40 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20  fies.** whether 
26e50 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72  or not it requir
26e60 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 20 73  es a protected s
26e70 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a  qlite3_value..**
26e80 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70  .** The terms "p
26e90 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75  rotected" and "u
26ea0 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65  nprotected" refe
26eb0 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20  r to whether or 
26ec0 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69  not.** a mutex i
26ed0 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65  s held.  An inte
26ee0 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65  rnal mutex is he
26ef0 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74  ld for a protect
26f00 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
26f10 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e  lue object but n
26f20 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20  o mutex is held 
26f30 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74  for an unprotect
26f40 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
26f50 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20  lue object.  If 
26f60 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
26f70 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d  ed to be single-
26f80 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74  threaded.** (wit
26f90 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  h [SQLITE_THREAD
26fa0 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68  SAFE=0] and with
26fb0 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64   [sqlite3_thread
26fc0 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e  safe()] returnin
26fd0 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51  g 0).** or if SQ
26fe0 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f  Lite is run in o
26ff0 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75  ne of reduced mu
27000 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53  tex modes .** [S
27010 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
27020 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53  GLETHREAD] or [S
27030 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
27040 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65  TITHREAD].** the
27050 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69  n there is no di
27060 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
27070 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  n protected and 
27080 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
27090 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
270a0 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61  ects and they ca
270b0 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63  n be used interc
270c0 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65  hangeably.  Howe
270d0 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69  ver,.** for maxi
270e0 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69  mum code portabi
270f0 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d  lity it is recom
27100 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c  mended that appl
27110 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c  ications.** stil
27120 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69  l make the disti
27130 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70  nction between p
27140 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70  rotected and unp
27150 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
27160 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
27170 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20  s even when not 
27180 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65  strictly require
27190 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
271a0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
271b0 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73  cts that are pas
271c0 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72  sed as parameter
271d0 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d  s into the.** im
271e0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
271f0 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
27200 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
27210 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65  ns] are protecte
27220 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  d..** ^The sqlit
27230 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
27240 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
27250 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
27260 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f  alue()] is unpro
27270 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f  tected..** Unpro
27280 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
27290 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79  alue objects may
272a0 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69   only be used wi
272b0 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  th.** [sqlite3_r
272c0 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61  esult_value()] a
272d0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  nd [sqlite3_bind
272e0 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68  _value()]..** Th
272f0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
27300 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
27310 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61  value_type()] fa
27320 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72  mily of.** inter
27330 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72  faces require pr
27340 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
27350 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a  value objects..*
27360 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
27370 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c   Mem sqlite3_val
27380 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ue;../*.** CAPI3
27390 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f  REF: SQL Functio
273a0 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74  n Context Object
273b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65  .**.** The conte
273c0 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53  xt in which an S
273d0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63  QL function exec
273e0 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69  utes is stored i
273f0 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  n an.** sqlite3_
27400 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20  context object. 
27410 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61   ^A pointer to a
27420 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  n sqlite3_contex
27430 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61  t object.** is a
27440 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61  lways first para
27450 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63  meter to [applic
27460 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
27470 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  L functions]..**
27480 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
27490 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
274a0 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
274b0 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74  tion will pass t
274c0 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  his.** pointer t
274d0 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c  hrough into call
274e0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  s to [sqlite3_re
274f0 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74  sult_int | sqlit
27500 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a  e3_result()],.**
27510 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   [sqlite3_aggreg
27520 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20  ate_context()], 
27530 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
27540 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  ta()],.** [sqlit
27550 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
27560 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65  ndle()], [sqlite
27570 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d  3_get_auxdata()]
27580 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c  ,.** and/or [sql
27590 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
275a0 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ()]..*/.typedef 
275b0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63  struct sqlite3_c
275c0 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63  ontext sqlite3_c
275d0 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ontext;../*.** C
275e0 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67  API3REF: Binding
275f0 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61   Values To Prepa
27600 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a  red Statements.*
27610 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73  * KEYWORDS: {hos
27620 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f  t parameter} {ho
27630 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b  st parameters} {
27640 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e  host parameter n
27650 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ame}.** KEYWORDS
27660 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  : {SQL parameter
27670 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  } {SQL parameter
27680 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69  s} {parameter bi
27690 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49  nding}.**.** ^(I
276a0 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  n the SQL statem
276b0 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20 74  ent text input t
276c0 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  o [sqlite3_prepa
276d0 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73  re_v2()] and its
276e0 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69   variants,.** li
276f0 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65  terals may be re
27700 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61 72  placed by a [par
27710 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74  ameter] that mat
27720 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c  ches one of foll
27730 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74  owing.** templat
27740 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
27750 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69  * <li>  ?.** <li
27760 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20  >  ?NNN.** <li> 
27770 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40   :VVV.** <li>  @
27780 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56  VVV.** <li>  $VV
27790 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  V.** </ul>.**.**
277a0 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65   In the template
277b0 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70  s above, NNN rep
277c0 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67  resents an integ
277d0 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61  er literal,.** a
277e0 6e 64 20 56 56 56 20 72 65 70 72 65 73 65 6e 74  nd VVV represent
277f0 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69  s an alphanumeri
27800 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e 20  c identifier.)^ 
27810 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20   ^The values of 
27820 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74  these.** paramet
27830 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64  ers (also called
27840 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   "host parameter
27850 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20   names" or "SQL 
27860 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20  parameters").** 
27870 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67  can be set using
27880 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
27890 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64  d_*() routines d
278a0 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a  efined here..**.
278b0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
278c0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71  gument to the sq
278d0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
278e0 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79  outines is alway
278f0 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74  s.** a pointer t
27900 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  o the [sqlite3_s
27910 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75  tmt] object retu
27920 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71  rned from.** [sq
27930 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
27940 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
27950 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
27960 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
27970 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  is the index of 
27980 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65  the SQL paramete
27990 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20  r to be set..** 
279a0 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51  ^The leftmost SQ
279b0 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  L parameter has 
279c0 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20  an index of 1.  
279d0 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e  ^When the same n
279e0 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61  amed.** SQL para
279f0 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f  meter is used mo
27a00 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65  re than once, se
27a10 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75  cond and subsequ
27a20 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63  ent.** occurrenc
27a30 65 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65  es have the same
27a40 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69   index as the fi
27a50 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a  rst occurrence..
27a60 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f  ** ^The index fo
27a70 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  r named paramete
27a80 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64  rs can be looked
27a90 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a   up using the.**
27aa0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
27ab0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
27ac0 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65 64  ] API if desired
27ad0 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a  .  ^The index.**
27ae0 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61   for "?NNN" para
27af0 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61  meters is the va
27b00 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e  lue of NNN..** ^
27b10 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75  The NNN value mu
27b20 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20  st be between 1 
27b30 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  and the [sqlite3
27b40 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72  _limit()].** par
27b50 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c  ameter [SQLITE_L
27b60 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
27b70 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76  MBER] (default v
27b80 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a  alue: 999)..**.*
27b90 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67  * ^The third arg
27ba0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c  ument is the val
27bb0 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68  ue to bind to th
27bc0 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  e parameter..** 
27bd0 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61  ^If the third pa
27be0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
27bf0 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f  e3_bind_text() o
27c00 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  r sqlite3_bind_t
27c10 65 78 74 31 36 28 29 0a 2a 2a 20 6f 72 20 73 71  ext16().** or sq
27c20 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
27c30 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ) is a NULL poin
27c40 74 65 72 20 74 68 65 6e 20 74 68 65 20 66 6f 75  ter then the fou
27c50 72 74 68 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  rth parameter.**
27c60 20 69 73 20 69 67 6e 6f 72 65 64 20 61 6e 64 20   is ignored and 
27c70 74 68 65 20 65 6e 64 20 72 65 73 75 6c 74 20 69  the end result i
27c80 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 73 71  s the same as sq
27c90 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28  lite3_bind_null(
27ca0 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68  )..**.** ^(In th
27cb0 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ose routines tha
27cc0 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 20  t have a fourth 
27cd0 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61  argument, its va
27ce0 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75  lue is the.** nu
27cf0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
27d00 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20   the parameter. 
27d10 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68   To be clear: th
27d20 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a  e value is the.*
27d30 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62  * number of <u>b
27d40 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20  ytes</u> in the 
27d50 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e  value, not the n
27d60 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
27d70 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68  ers.)^.** ^If th
27d80 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
27d90 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
27da0 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c  nd_text() or sql
27db0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
27dc0 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76  ().** is negativ
27dd0 65 2c 20 74 68 65 6e 20 74 68 65 20 6c 65 6e 67  e, then the leng
27de0 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67  th of the string
27df0 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65   is.** the numbe
27e00 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f  r of bytes up to
27e10 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
27e20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49  terminator..** I
27e30 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
27e40 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
27e50 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73  3_bind_blob() is
27e60 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 0a   negative, then.
27e70 2a 2a 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  ** the behavior 
27e80 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
27e90 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69   If a non-negati
27ea0 76 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  ve fourth parame
27eb0 74 65 72 20 69 73 20 70 72 6f 76 69 64 65 64 20  ter is provided 
27ec0 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
27ed0 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  text().** or sql
27ee0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
27ef0 28 29 20 74 68 65 6e 20 74 68 61 74 20 70 61 72  () then that par
27f00 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 74  ameter must be t
27f10 68 65 20 62 79 74 65 20 6f 66 66 73 65 74 0a 2a  he byte offset.*
27f20 2a 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20  * where the NUL 
27f30 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64  terminator would
27f40 20 6f 63 63 75 72 20 61 73 73 75 6d 69 6e 67 20   occur assuming 
27f50 74 68 65 20 73 74 72 69 6e 67 20 77 65 72 65 20  the string were 
27f60 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65  NUL.** terminate
27f70 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63  d.  If any NUL c
27f80 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 20  haracters occur 
27f90 61 74 20 62 79 74 65 20 6f 66 66 73 65 74 73 20  at byte offsets 
27fa0 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68  less than .** th
27fb0 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66  e value of the f
27fc0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
27fd0 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69  then the resulti
27fe0 6e 67 20 73 74 72 69 6e 67 20 76 61 6c 75 65 20  ng string value 
27ff0 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20  will.** contain 
28000 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e 20 20  embedded NULs.  
28010 54 68 65 20 72 65 73 75 6c 74 20 6f 66 20 65 78  The result of ex
28020 70 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76  pressions involv
28030 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77  ing strings.** w
28040 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ith embedded NUL
28050 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  s is undefined..
28060 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68  **.** ^The fifth
28070 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
28080 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
28090 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  , sqlite3_bind_t
280a0 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71  ext(), and.** sq
280b0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
280c0 36 28 29 20 69 73 20 61 20 64 65 73 74 72 75 63  6() is a destruc
280d0 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70  tor used to disp
280e0 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  ose of the BLOB 
280f0 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74  or.** string aft
28100 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69  er SQLite has fi
28110 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20  nished with it. 
28120 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72   ^The destructor
28130 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f   is called.** to
28140 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20   dispose of the 
28150 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65  BLOB or string e
28160 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20  ven if the call 
28170 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
28180 62 6c 6f 62 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  blob(),.** sqlit
28190 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20  e3_bind_text(), 
281a0 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
281b0 74 65 78 74 31 36 28 29 20 66 61 69 6c 73 2e 20  text16() fails. 
281c0 20 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66   .** ^If the fif
281d0 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a  th argument is.*
281e0 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 61  * the special va
281f0 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54  lue [SQLITE_STAT
28200 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  IC], then SQLite
28210 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
28220 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  e.** information
28230 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75   is in static, u
28240 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 61  nmanaged space a
28250 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  nd does not need
28260 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a   to be freed..**
28270 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61   ^If the fifth a
28280 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20  rgument has the 
28290 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52  value [SQLITE_TR
282a0 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a  ANSIENT], then.*
282b0 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69  * SQLite makes i
282c0 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
282d0 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 20  opy of the data 
282e0 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66  immediately, bef
282f0 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74  ore.** the sqlit
28300 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
28310 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  ine returns..**.
28320 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
28330 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20  bind_zeroblob() 
28340 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20  routine binds a 
28350 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e  BLOB of length N
28360 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c   that.** is fill
28370 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20  ed with zeroes. 
28380 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65   ^A zeroblob use
28390 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74  s a fixed amount
283a0 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a   of memory.** (j
283b0 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74  ust an integer t
283c0 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29  o hold its size)
283d0 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 65 69   while it is bei
283e0 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a  ng processed..**
283f0 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69   Zeroblobs are i
28400 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65  ntended to serve
28410 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73   as placeholders
28420 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65   for BLOBs whose
28430 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c  .** content is l
28440 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73 69  ater written usi
28450 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ng.** [sqlite3_b
28460 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65  lob_open | incre
28470 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d  mental BLOB I/O]
28480 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41   routines..** ^A
28490 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 20   negative value 
284a0 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62  for the zeroblob
284b0 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65   results in a ze
284c0 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a  ro-length BLOB..
284d0 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66  **.** ^If any of
284e0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
284f0 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61  d_*() routines a
28500 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  re called with a
28510 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
28520 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72   for the [prepar
28530 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72  ed statement] or
28540 20 77 69 74 68 20 61 20 70 72 65 70 61 72 65 64   with a prepared
28550 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 77   statement for w
28560 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  hich.** [sqlite3
28570 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 65 65  _step()] has bee
28580 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65  n called more re
28590 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c  cently than [sql
285a0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a  ite3_reset()],.*
285b0 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 20  * then the call 
285c0 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
285d0 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66  ITE_MISUSE].  If
285e0 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 6e   any sqlite3_bin
285f0 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  d_().** routine 
28600 69 73 20 70 61 73 73 65 64 20 61 20 5b 70 72 65  is passed a [pre
28610 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
28620 20 74 68 61 74 20 68 61 73 20 62 65 65 6e 20 66   that has been f
28630 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a  inalized, the.**
28640 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66   result is undef
28650 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
28660 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a  y harmful..**.**
28670 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e   ^Bindings are n
28680 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 68  ot cleared by th
28690 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
286a0 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20  ()] routine..** 
286b0 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74  ^Unbound paramet
286c0 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 65  ers are interpre
286d0 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ted as NULL..**.
286e0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
286f0 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20  bind_* routines 
28700 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
28710 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72  K] on success or
28720 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f   an.** [error co
28730 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 20  de] if anything 
28740 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e  goes wrong..** ^
28750 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69  [SQLITE_RANGE] i
28760 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68  s returned if th
28770 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69  e parameter.** i
28780 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72  ndex is out of r
28790 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f  ange.  ^[SQLITE_
287a0 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e  NOMEM] is return
287b0 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66  ed if malloc() f
287c0 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  ails..**.** See 
287d0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
287e0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
287f0 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  unt()],.** [sqli
28800 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
28810 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20  er_name()], and 
28820 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
28830 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
28840 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
28850 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74  _bind_blob(sqlit
28860 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
28870 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20  onst void*, int 
28880 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  n, void(*)(void*
28890 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
288a0 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69  bind_double(sqli
288b0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
288c0 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c  double);.int sql
288d0 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71  ite3_bind_int(sq
288e0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
288f0 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69  , int);.int sqli
28900 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73  te3_bind_int64(s
28910 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
28920 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
28930 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
28940 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33  ind_null(sqlite3
28950 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e  _stmt*, int);.in
28960 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  t sqlite3_bind_t
28970 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ext(sqlite3_stmt
28980 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68  *, int, const ch
28990 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64  ar*, int n, void
289a0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
289b0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
289c0 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt16(sqlite3_stm
289d0 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76  t*, int, const v
289e0 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
289f0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
28a00 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
28a10 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ue(sqlite3_stmt*
28a20 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c  , int, const sql
28a30 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
28a40 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a  t sqlite3_bind_z
28a50 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  eroblob(sqlite3_
28a60 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20  stmt*, int, int 
28a70 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  n);../*.** CAPI3
28a80 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53  REF: Number Of S
28a90 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a  QL Parameters.**
28aa0 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
28ab0 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
28ac0 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72   find the number
28ad0 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74   of [SQL paramet
28ae0 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72  ers].** in a [pr
28af0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
28b00 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65  ].  SQL paramete
28b10 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66  rs are tokens of
28b20 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22   the.** form "?"
28b30 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22  , "?NNN", ":AAA"
28b40 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41  , "$AAA", or "@A
28b50 41 41 22 20 74 68 61 74 20 73 65 72 76 65 20 61  AA" that serve a
28b60 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72  s.** placeholder
28b70 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61  s for values tha
28b80 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62  t are [sqlite3_b
28b90 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64  ind_blob | bound
28ba0 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61  ].** to the para
28bb0 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 65  meters at a late
28bc0 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28  r time..**.** ^(
28bd0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74  This routine act
28be0 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68  ually returns th
28bf0 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c  e index of the l
28c00 61 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73  argest (rightmos
28c10 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e  t).** parameter.
28c20 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65   For all forms e
28c30 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73  xcept ?NNN, this
28c40 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64   will correspond
28c50 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   to the.** numbe
28c60 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61  r of unique para
28c70 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 61  meters.  If para
28c80 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e  meters of the ?N
28c90 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64  NN form are used
28ca0 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62  ,.** there may b
28cb0 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69  e gaps in the li
28cc0 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  st.)^.**.** See 
28cd0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
28ce0 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
28cf0 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
28d00 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
28d10 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e  eter_name()], an
28d20 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
28d30 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
28d40 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ex()]..*/.int sq
28d50 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
28d60 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74  eter_count(sqlit
28d70 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
28d80 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65  * CAPI3REF: Name
28d90 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d   Of A Host Param
28da0 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eter.**.** ^The 
28db0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
28dc0 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29  ameter_name(P,N)
28dd0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
28de0 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f  ns.** the name o
28df0 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20  f the N-th [SQL 
28e00 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68  parameter] in th
28e10 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
28e20 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53  ement] P..** ^(S
28e30 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66  QL parameters of
28e40 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22   the form "?NNN"
28e50 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40   or ":AAA" or "@
28e60 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a  AAA" or "$AAA".*
28e70 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68  * have a name wh
28e80 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e  ich is the strin
28e90 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41  g "?NNN" or ":AA
28ea0 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20  A" or "@AAA" or 
28eb0 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63  "$AAA".** respec
28ec0 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74  tively..** In ot
28ed0 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69  her words, the i
28ee0 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24  nitial ":" or "$
28ef0 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a  " or "@" or "?".
28f00 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61  ** is included a
28f10 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61  s part of the na
28f20 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65  me.)^.** ^Parame
28f30 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ters of the form
28f40 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66   "?" without a f
28f50 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72  ollowing integer
28f60 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a   have no name.**
28f70 20 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 65   and are referre
28f80 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73  d to as "nameles
28f90 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73  s" or "anonymous
28fa0 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a   parameters"..**
28fb0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68  .** ^The first h
28fc0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61  ost parameter ha
28fd0 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c  s an index of 1,
28fe0 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49   not 0..**.** ^I
28ff0 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73  f the value N is
29000 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72   out of range or
29010 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72   if the N-th par
29020 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d  ameter is.** nam
29030 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c  eless, then NULL
29040 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e   is returned.  ^
29050 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
29060 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73  ing is.** always
29070 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69   in UTF-8 encodi
29080 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e  ng even if the n
29090 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77  amed parameter w
290a0 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79  as.** originally
290b0 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54   specified as UT
290c0 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33  F-16 in [sqlite3
290d0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72  _prepare16()] or
290e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
290f0 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a  pare16_v2()]..**
29100 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
29110 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
29120 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
29130 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
29140 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
29150 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  nt()], and.** [s
29160 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
29170 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
29180 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
29190 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
291a0 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74  meter_name(sqlit
291b0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a  e3_stmt*, int);.
291c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
291d0 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61   Index Of A Para
291e0 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 69 76  meter With A Giv
291f0 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52  en Name.**.** ^R
29200 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20  eturn the index 
29210 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65  of an SQL parame
29220 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61  ter given its na
29230 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64  me.  ^The.** ind
29240 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  ex value returne
29250 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f  d is suitable fo
29260 72 20 75 73 65 20 61 73 20 74 68 65 20 73 65 63  r use as the sec
29270 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ond.** parameter
29280 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
29290 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
292a0 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f  ind()].  ^A zero
292b0 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
292c0 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70  if no matching p
292d0 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e  arameter is foun
292e0 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74  d.  ^The paramet
292f0 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20  er.** name must 
29300 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d  be given in UTF-
29310 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72  8 even if the or
29320 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74  iginal statement
29330 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65 64  .** was prepared
29340 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78   from UTF-16 tex
29350 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
29360 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
29370 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
29380 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
29390 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
293a0 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
293b0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
293c0 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a  _count()], and.*
293d0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
293e0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
293f0 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
29400 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
29410 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f  r_index(sqlite3_
29420 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  stmt*, const cha
29430 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a  r *zName);../*.*
29440 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
29450 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f  t All Bindings O
29460 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  n A Prepared Sta
29470 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f  tement.**.** ^Co
29480 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e  ntrary to the in
29490 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c  tuition of many,
294a0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
294b0 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65  )] does not rese
294c0 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  t.** the [sqlite
294d0 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69  3_bind_blob | bi
294e0 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72  ndings] on a [pr
294f0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
29500 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 20  ]..** ^Use this 
29510 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74  routine to reset
29520 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65   all host parame
29530 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f  ters to NULL..*/
29540 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65  .int sqlite3_cle
29550 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69  ar_bindings(sqli
29560 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
29570 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
29580 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49  ber Of Columns I
29590 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a  n A Result Set.*
295a0 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65  *.** ^Return the
295b0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
295c0 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
295d0 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79   set returned by
295e0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
295f0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54  d statement]. ^T
29600 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
29610 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20 69  rns 0 if pStmt i
29620 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74  s an SQL.** stat
29630 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20  ement that does 
29640 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 20  not return data 
29650 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20  (for example an 
29660 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a  [UPDATE])..**.**
29670 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
29680 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29  te3_data_count()
29690 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
296a0 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71  _column_count(sq
296b0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
296c0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
296d0 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65  REF: Column Name
296e0 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65  s In A Result Se
296f0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  t.**.** ^These r
29700 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
29710 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64  he name assigned
29720 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72   to a particular
29730 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68   column.** in th
29740 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  e result set of 
29750 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  a [SELECT] state
29760 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69  ment.  ^The sqli
29770 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
29780 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72  ).** interface r
29790 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
297a0 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   to a zero-termi
297b0 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
297c0 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65  ng.** and sqlite
297d0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
297e0 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  ) returns a poin
297f0 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65  ter to a zero-te
29800 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
29810 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65  16 string.  ^The
29820 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
29830 20 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 65   is the [prepare
29840 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
29850 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20  that implements 
29860 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  the [SELECT] sta
29870 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63  tement. ^The sec
29880 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
29890 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e   the.** column n
298a0 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66  umber.  ^The lef
298b0 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20  tmost column is 
298c0 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20  number 0..**.** 
298d0 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
298e0 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20  ring pointer is 
298f0 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68  valid until eith
29900 65 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  er the [prepared
29910 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69   statement].** i
29920 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b  s destroyed by [
29930 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
29940 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  ()] or until the
29950 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75   statement is au
29960 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72  tomatically.** r
29970 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65  eprepared by the
29980 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b   first call to [
29990 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
299a0 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
299b0 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c   run.** or until
299c0 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74   the next call t
299d0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  o.** sqlite3_col
299e0 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71  umn_name() or sq
299f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
29a00 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d  e16() on the sam
29a10 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20  e column..**.** 
29a20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ^If sqlite3_mall
29a30 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e  oc() fails durin
29a40 67 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67  g the processing
29a50 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69   of either routi
29a60 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70  ne.** (for examp
29a70 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76  le during a conv
29a80 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d  ersion from UTF-
29a90 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65  8 to UTF-16) the
29aa0 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e  n a.** NULL poin
29ab0 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ter is returned.
29ac0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  .**.** ^The name
29ad0 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c   of a result col
29ae0 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65  umn is the value
29af0 20 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c 61   of the "AS" cla
29b00 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20  use for.** that 
29b10 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65  column, if there
29b20 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65   is an AS clause
29b30 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e  .  If there is n
29b40 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74  o AS clause.** t
29b50 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  hen the name of 
29b60 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e  the column is un
29b70 73 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61  specified and ma
29b80 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a  y change from.**
29b90 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20   one release of 
29ba0 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65  SQLite to the ne
29bb0 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  xt..*/.const cha
29bc0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
29bd0 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  n_name(sqlite3_s
29be0 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f  tmt*, int N);.co
29bf0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
29c00 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
29c10 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
29c20 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt N);../*.** CA
29c30 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f  PI3REF: Source O
29c40 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72  f Data In A Quer
29c50 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e  y Result.**.** ^
29c60 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70  These routines p
29c70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74  rovide a means t
29c80 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  o determine the 
29c90 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
29ca0 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f   and.** table co
29cb0 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65  lumn that is the
29cc0 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72   origin of a par
29cd0 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63  ticular result c
29ce0 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c  olumn in.** [SEL
29cf0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a  ECT] statement..
29d00 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
29d10 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20  the database or 
29d20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20  table or column 
29d30 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20  can be returned 
29d40 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55  as.** either a U
29d50 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73  TF-8 or UTF-16 s
29d60 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61  tring.  ^The _da
29d70 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73  tabase_ routines
29d80 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64   return.** the d
29d90 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68  atabase name, th
29da0 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e  e _table_ routin
29db0 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61  es return the ta
29dc0 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a  ble name, and.**
29dd0 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75   the origin_ rou
29de0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
29df0 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a   column name..**
29e00 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
29e10 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75  tring is valid u
29e20 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72  ntil the [prepar
29e30 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73  ed statement] is
29e40 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73   destroyed.** us
29e50 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
29e60 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69  alize()] or unti
29e70 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  l the statement 
29e80 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  is automatically
29e90 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62  .** reprepared b
29ea0 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  y the first call
29eb0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
29ec0 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69  p()] for a parti
29ed0 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20  cular run.** or 
29ee0 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69  until the same i
29ef0 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65  nformation is re
29f00 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e  quested.** again
29f10 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20   in a different 
29f20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  encoding..**.** 
29f30 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72  ^The names retur
29f40 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67  ned are the orig
29f50 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20  inal un-aliased 
29f60 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20  names of the.** 
29f70 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
29f80 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a   and column..**.
29f90 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
29fa0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20  gument to these 
29fb0 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 61 20  interfaces is a 
29fc0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
29fd0 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20  ent]..** ^These 
29fe0 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
29ff0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
2a000 75 74 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c  ut the Nth resul
2a010 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  t column returne
2a020 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74  d by.** the stat
2a030 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69  ement, where N i
2a040 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e  s the second fun
2a050 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a  ction argument..
2a060 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73  ** ^The left-mos
2a070 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75  t column is colu
2a080 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20 72  mn 0 for these r
2a090 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  outines..**.** ^
2a0a0 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  If the Nth colum
2a0b0 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  n returned by th
2a0c0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
2a0d0 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a  n expression or.
2a0e0 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20  ** subquery and 
2a0f0 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20  is not a column 
2a100 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20  value, then all 
2a110 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  of these functio
2a120 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c  ns return.** NUL
2a130 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69  L.  ^These routi
2a140 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65  ne might also re
2a150 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d  turn NULL if a m
2a160 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
2a170 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73   error.** occurs
2a180 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74  .  ^Otherwise, t
2a190 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e  hey return the n
2a1a0 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63  ame of the attac
2a1b0 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61  hed database, ta
2a1c0 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d  ble,.** or colum
2a1d0 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73  n that query res
2a1e0 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65  ult column was e
2a1f0 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a  xtracted from..*
2a200 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c  *.** ^As with al
2a210 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41  l other SQLite A
2a220 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65  PIs, those whose
2a230 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20   names end with 
2a240 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55  "16" return.** U
2a250 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74  TF-16 encoded st
2a260 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74  rings and the ot
2a270 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  her functions re
2a280 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a  turn UTF-8..**.*
2a290 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20 61 72  * ^These APIs ar
2a2a0 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  e only available
2a2b0 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20   if the library 
2a2c0 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
2a2d0 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
2a2e0 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d  _ENABLE_COLUMN_M
2a2f0 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72  ETADATA] C-prepr
2a300 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a  ocessor symbol..
2a310 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20  **.** If two or 
2a320 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c  more threads cal
2a330 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66  l one or more of
2a340 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
2a350 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65  against the same
2a360 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61  .** prepared sta
2a370 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d  tement and colum
2a380 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  n at the same ti
2a390 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  me then the resu
2a3a0 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66  lts are.** undef
2a3b0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  ined..**.** If t
2a3c0 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
2a3d0 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
2a3e0 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ore.** [sqlite3_
2a3f0 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
2a400 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65  name | column me
2a410 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65  tadata interface
2a420 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  s].** for the sa
2a430 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  me [prepared sta
2a440 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75  tement] and resu
2a450 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20  lt column.** at 
2a460 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68  the same time th
2a470 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
2a480 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f  re undefined..*/
2a490 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
2a4a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
2a4b0 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65  base_name(sqlite
2a4c0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
2a4d0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2a4e0 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
2a4f0 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  e_name16(sqlite3
2a500 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
2a510 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
2a520 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61  _column_table_na
2a530 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
2a540 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
2a550 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2a560 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73  n_table_name16(s
2a570 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2a580 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
2a590 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72  qlite3_column_or
2a5a0 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65  igin_name(sqlite
2a5b0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
2a5c0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2a5d0 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f  3_column_origin_
2a5e0 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
2a5f0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  tmt*,int);../*.*
2a600 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c  * CAPI3REF: Decl
2a610 61 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66  ared Datatype Of
2a620 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a   A Query Result.
2a630 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73  **.** ^(The firs
2a640 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  t parameter is a
2a650 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2a660 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69  ment]..** If thi
2a670 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  s statement is a
2a680 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
2a690 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20  ent and the Nth 
2a6a0 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a  column of the.**
2a6b0 20 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74   returned result
2a6c0 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45   set of that [SE
2a6d0 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65  LECT] is a table
2a6e0 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a   column (not an.
2a6f0 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  ** expression or
2a700 20 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20   subquery) then 
2a710 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70  the declared typ
2a720 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a  e of the table.*
2a730 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75  * column is retu
2a740 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65  rned.)^  ^If the
2a750 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74   Nth column of t
2a760 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 73  he result set is
2a770 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f   an.** expressio
2a780 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74  n or subquery, t
2a790 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  hen a NULL point
2a7a0 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
2a7b0 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  ** ^The returned
2a7c0 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79   string is alway
2a7d0 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e  s UTF-8 encoded.
2a7e0 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61  .**.** ^(For exa
2a7f0 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20  mple, given the 
2a800 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a  database schema:
2a810 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41  .**.** CREATE TA
2a820 42 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e  BLE t1(c1 VARIAN
2a830 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68  T);.**.** and th
2a840 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74  e following stat
2a850 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70  ement to be comp
2a860 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45  iled:.**.** SELE
2a870 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52  CT c1 + 1, c1 FR
2a880 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69  OM t1;.**.** thi
2a890 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20  s routine would 
2a8a0 72 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e  return the strin
2a8b0 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20  g "VARIANT" for 
2a8c0 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c  the second resul
2a8d0 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d  t.** column (i==
2a8e0 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70  1), and a NULL p
2a8f0 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66  ointer for the f
2a900 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75  irst result colu
2a910 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a  mn (i==0).)^.**.
2a920 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20  ** ^SQLite uses 
2a930 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65  dynamic run-time
2a940 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75   typing.  ^So ju
2a950 73 74 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c  st because a col
2a960 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72  umn.** is declar
2a970 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20  ed to contain a 
2a980 70 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 20  particular type 
2a990 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68  does not mean th
2a9a0 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73  at the.** data s
2a9b0 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f  tored in that co
2a9c0 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64  lumn is of the d
2a9d0 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53  eclared type.  S
2a9e0 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f  QLite is.** stro
2a9f0 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20  ngly typed, but 
2aa00 74 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 79  the typing is dy
2aa10 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63  namic not static
2aa20 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61  .  ^Type.** is a
2aa30 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 69  ssociated with i
2aa40 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73  ndividual values
2aa50 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63  , not with the c
2aa60 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65  ontainers.** use
2aa70 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20  d to hold those 
2aa80 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74  values..*/.const
2aa90 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
2aaa0 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73  olumn_decltype(s
2aab0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2aac0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
2aad0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
2aae0 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33  cltype16(sqlite3
2aaf0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
2ab00 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76  .** CAPI3REF: Ev
2ab10 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74  aluate An SQL St
2ab20 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66  atement.**.** Af
2ab30 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20  ter a [prepared 
2ab40 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62  statement] has b
2ab50 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69  een prepared usi
2ab60 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71  ng either.** [sq
2ab70 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2ab80 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2ab90 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
2aba0 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65  or one of the le
2abb0 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
2abc0 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  es [sqlite3_prep
2abd0 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  are()] or [sqlit
2abe0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c  e3_prepare16()],
2abf0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a   this function.*
2ac00 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  * must be called
2ac10 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
2ac20 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74  es to evaluate t
2ac30 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  he statement..**
2ac40 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20  .** The details 
2ac50 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  of the behavior 
2ac60 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  of the sqlite3_s
2ac70 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20  tep() interface 
2ac80 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65  depend.** on whe
2ac90 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65  ther the stateme
2aca0 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20  nt was prepared 
2acb0 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20  using the newer 
2acc0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a  "v2" interface.*
2acd0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
2ace0 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
2acf0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2ad00 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64  v2()] or the old
2ad10 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  er legacy.** int
2ad20 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f  erface [sqlite3_
2ad30 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b  prepare()] and [
2ad40 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2ad50 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f  6()].  The use o
2ad60 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32  f the.** new "v2
2ad70 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72  " interface is r
2ad80 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e  ecommended for n
2ad90 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ew applications 
2ada0 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a  but the legacy.*
2adb0 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  * interface will
2adc0 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20   continue to be 
2add0 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a  supported..**.**
2ade0 20 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20   ^In the legacy 
2adf0 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72  interface, the r
2ae00 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c  eturn value will
2ae10 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49   be either [SQLI
2ae20 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51  TE_BUSY],.** [SQ
2ae30 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c  LITE_DONE], [SQL
2ae40 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54  ITE_ROW], [SQLIT
2ae50 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51  E_ERROR], or [SQ
2ae60 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a  LITE_MISUSE]..**
2ae70 20 5e 57 69 74 68 20 74 68 65 20 22 76 32 22 20   ^With the "v2" 
2ae80 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f  interface, any o
2ae90 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73  f the other [res
2aea0 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a  ult codes] or.**
2aeb0 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
2aec0 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62  t codes] might b
2aed0 65 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65  e returned as we
2aee0 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49  ll..**.** ^[SQLI
2aef0 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74  TE_BUSY] means t
2af00 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65  hat the database
2af10 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62   engine was unab
2af20 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68  le to acquire th
2af30 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f  e.** database lo
2af40 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20  cks it needs to 
2af50 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66  do its job.  ^If
2af60 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
2af70 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20  s a [COMMIT].** 
2af80 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64  or occurs outsid
2af90 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74  e of an explicit
2afa0 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68   transaction, th
2afb0 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79  en you can retry
2afc0 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   the.** statemen
2afd0 74 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65  t.  If the state
2afe0 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43  ment is not a [C
2aff0 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72  OMMIT] and occur
2b000 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65  s within an.** e
2b010 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
2b020 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f  ion then you sho
2b030 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65  uld rollback the
2b040 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66   transaction bef
2b050 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e  ore.** continuin
2b060 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  g..**.** ^[SQLIT
2b070 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68  E_DONE] means th
2b080 61 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  at the statement
2b090 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78   has finished ex
2b0a0 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65  ecuting.** succe
2b0b0 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65  ssfully.  sqlite
2b0c0 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20  3_step() should 
2b0d0 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67  not be called ag
2b0e0 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74  ain on this virt
2b0f0 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77  ual.** machine w
2b100 69 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c  ithout first cal
2b110 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
2b120 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20  set()] to reset 
2b130 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d  the virtual.** m
2b140 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69  achine back to i
2b150 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65  ts initial state
2b160 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2b170 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65  SQL statement be
2b180 69 6e 67 20 65 78 65 63 75 74 65 64 20 72 65 74  ing executed ret
2b190 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74  urns any data, t
2b1a0 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  hen [SQLITE_ROW]
2b1b0 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
2b1c0 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20  each time a new 
2b1d0 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20 72  row of data is r
2b1e0 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73  eady for process
2b1f0 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61  ing by the.** ca
2b200 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73  ller. The values
2b210 20 6d 61 79 20 62 65 20 61 63 63 65 73 73 65 64   may be accessed
2b220 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75   using the [colu
2b230 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
2b240 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33  ons]..** sqlite3
2b250 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65  _step() is calle
2b260 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69  d again to retri
2b270 65 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77  eve the next row
2b280 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20   of data..**.** 
2b290 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20  ^[SQLITE_ERROR] 
2b2a0 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e  means that a run
2b2b0 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63  -time error (suc
2b2c0 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e  h as a constrain
2b2d0 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20  t.** violation) 
2b2e0 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73  has occurred.  s
2b2f0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68  qlite3_step() sh
2b300 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c  ould not be call
2b310 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74  ed again on.** t
2b320 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f  he VM. More info
2b330 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66  rmation may be f
2b340 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20  ound by calling 
2b350 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
2b360 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65  )]..** ^With the
2b370 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
2b380 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66  e, a more specif
2b390 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66  ic error code (f
2b3a0 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b  or example,.** [
2b3b0 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
2b3c0 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  ], [SQLITE_SCHEM
2b3d0 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52  A], [SQLITE_CORR
2b3e0 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72  UPT], and so for
2b3f0 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62  th).** can be ob
2b400 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e  tained by callin
2b410 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
2b420 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70  ()] on the.** [p
2b430 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2b440 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32  t].  ^In the "v2
2b450 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20  " interface,.** 
2b460 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69  the more specifi
2b470 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20  c error code is 
2b480 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c  returned directl
2b490 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65  y by sqlite3_ste
2b4a0 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49  p()..**.** [SQLI
2b4b0 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73  TE_MISUSE] means
2b4c0 20 74 68 61 74 20 74 68 65 20 74 68 69 73 20 72   that the this r
2b4d0 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65  outine was calle
2b4e0 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c  d inappropriatel
2b4f0 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74  y..** Perhaps it
2b500 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61   was called on a
2b510 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2b520 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a  ment] that has.*
2b530 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b  * already been [
2b540 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2b550 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72   | finalized] or
2b560 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64   on one that had
2b570 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72  .** previously r
2b580 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
2b590 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54  ERROR] or [SQLIT
2b5a0 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20  E_DONE].  Or it 
2b5b0 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20  could.** be the 
2b5c0 63 61 73 65 20 74 68 61 74 20 74 68 65 20 73 61  case that the sa
2b5d0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
2b5e0 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20  ection is being 
2b5f0 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a  used by two or.*
2b600 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61  * more threads a
2b610 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e  t the same momen
2b620 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  t in time..**.**
2b630 20 46 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e   For all version
2b640 73 20 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74  s of SQLite up t
2b650 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20  o and including 
2b660 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c  3.6.23.1, a call
2b670 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
2b680 72 65 73 65 74 28 29 5d 20 77 61 73 20 72 65 71  reset()] was req
2b690 75 69 72 65 64 20 61 66 74 65 72 20 73 71 6c 69  uired after sqli
2b6a0 74 65 33 5f 73 74 65 70 28 29 20 72 65 74 75 72  te3_step() retur
2b6b0 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20  ned anything.** 
2b6c0 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
2b6d0 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 61  TE_ROW] before a
2b6e0 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e  ny subsequent in
2b6f0 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73  vocation of.** s
2b700 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
2b710 46 61 69 6c 75 72 65 20 74 6f 20 72 65 73 65 74  Failure to reset
2b720 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
2b730 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a  atement using .*
2b740 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
2b750 28 29 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c 74  ()] would result
2b760 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d   in an [SQLITE_M
2b770 49 53 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72  ISUSE] return fr
2b780 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  om.** sqlite3_st
2b790 65 70 28 29 2e 20 20 42 75 74 20 61 66 74 65 72  ep().  But after
2b7a0 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e   version 3.6.23.
2b7b0 31 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  1, sqlite3_step(
2b7c0 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69  ) began.** calli
2b7d0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
2b7e0 74 28 29 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c  t()] automatical
2b7f0 6c 79 20 69 6e 20 74 68 69 73 20 63 69 72 63 75  ly in this circu
2b800 6d 73 74 61 6e 63 65 20 72 61 74 68 65 72 0a 2a  mstance rather.*
2b810 2a 20 74 68 61 6e 20 72 65 74 75 72 6e 69 6e 67  * than returning
2b820 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
2b830 2e 20 20 54 68 69 73 20 69 73 20 6e 6f 74 20 63  .  This is not c
2b840 6f 6e 73 69 64 65 72 65 64 20 61 20 63 6f 6d 70  onsidered a comp
2b850 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65  atibility.** bre
2b860 61 6b 20 62 65 63 61 75 73 65 20 61 6e 79 20 61  ak because any a
2b870 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20  pplication that 
2b880 65 76 65 72 20 72 65 63 65 69 76 65 73 20 61 6e  ever receives an
2b890 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 65   SQLITE_MISUSE e
2b8a0 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65  rror.** is broke
2b8b0 6e 20 62 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e  n by definition.
2b8c0 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d    The [SQLITE_OM
2b8d0 49 54 5f 41 55 54 4f 52 45 53 45 54 5d 20 63 6f  IT_AUTORESET] co
2b8e0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
2b8f0 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64  n.** can be used
2b900 20 74 6f 20 72 65 73 74 6f 72 65 20 74 68 65 20   to restore the 
2b910 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 2e  legacy behavior.
2b920 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20  .**.** <b>Goofy 
2b930 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a  Interface Alert:
2b940 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61  </b> In the lega
2b950 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  cy interface, th
2b960 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  e sqlite3_step()
2b970 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72  .** API always r
2b980 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63  eturns a generic
2b990 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51   error code, [SQ
2b9a0 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c  LITE_ERROR], fol
2b9b0 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72  lowing any.** er
2b9c0 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ror other than [
2b9d0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64  SQLITE_BUSY] and
2b9e0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
2b9f0 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c  .  You must call
2ba00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
2ba10 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
2ba20 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e  3_finalize()] in
2ba30 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f   order to find o
2ba40 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65  ne of the.** spe
2ba50 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64  cific [error cod
2ba60 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 20  es] that better 
2ba70 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72  describes the er
2ba80 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74  ror..** We admit
2ba90 20 74 68 61 74 20 74 68 69 73 20 69 73 20 61 20   that this is a 
2baa0 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54  goofy design.  T
2bab0 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62  he problem has b
2bac0 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74  een fixed.** wit
2bad0 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  h the "v2" inter
2bae0 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72  face.  If you pr
2baf0 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75  epare all of you
2bb00 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  r SQL statements
2bb10 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72  .** using either
2bb20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2bb30 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
2bb40 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2bb50 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f  ()] instead.** o
2bb60 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71  f the legacy [sq
2bb70 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
2bb80 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
2bb90 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72  epare16()] inter
2bba0 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74  faces,.** then t
2bbb0 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63  he more specific
2bbc0 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61   [error codes] a
2bbd0 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 72 65  re returned dire
2bbe0 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74  ctly.** by sqlit
2bbf0 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20  e3_step().  The 
2bc00 75 73 65 20 6f 66 20 74 68 65 20 22 76 32 22 20  use of the "v2" 
2bc10 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63  interface is rec
2bc20 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74  ommended..*/.int
2bc30 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71   sqlite3_step(sq
2bc40 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
2bc50 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
2bc60 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
2bc70 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74   in a result set
2bc80 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2bc90 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
2bca0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2bcb0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
2bcc0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
2bcd0 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20  .** current row 
2bce0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
2bcf0 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73  t of [prepared s
2bd00 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20  tatement] P..** 
2bd10 5e 49 66 20 70 72 65 70 61 72 65 64 20 73 74 61  ^If prepared sta
2bd20 74 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f  tement P does no
2bd30 74 20 68 61 76 65 20 72 65 73 75 6c 74 73 20 72  t have results r
2bd40 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a  eady to return.*
2bd50 2a 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20  * (via calls to 
2bd60 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  the [sqlite3_col
2bd70 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65  umn_int | sqlite
2bd80 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66  3_column_*()] of
2bd90 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20  .** interfaces) 
2bda0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74  then sqlite3_dat
2bdb0 61 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72  a_count(P) retur
2bdc0 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  ns 0..** ^The sq
2bdd0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2bde0 28 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f  (P) routine also
2bdf0 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 50 20   returns 0 if P 
2be00 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
2be10 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  r..** ^The sqlit
2be20 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
2be30 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
2be40 20 30 20 69 66 20 74 68 65 20 70 72 65 76 69 6f   0 if the previo
2be50 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  us call to.** [s
2be60 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20  qlite3_step](P) 
2be70 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
2be80 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71  _DONE].  ^The sq
2be90 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2bea0 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75  (P).** will retu
2beb0 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70  rn non-zero if p
2bec0 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20  revious call to 
2bed0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50  [sqlite3_step](P
2bee0 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53  ) returned.** [S
2bef0 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65  QLITE_ROW], exce
2bf00 70 74 20 69 6e 20 74 68 65 20 63 61 73 65 20 6f  pt in the case o
2bf10 66 20 74 68 65 20 5b 50 52 41 47 4d 41 20 69 6e  f the [PRAGMA in
2bf20 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d  cremental_vacuum
2bf30 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74 20 61 6c  ].** where it al
2bf40 77 61 79 73 20 72 65 74 75 72 6e 73 20 7a 65 72  ways returns zer
2bf50 6f 20 73 69 6e 63 65 20 65 61 63 68 20 73 74 65  o since each ste
2bf60 70 20 6f 66 20 74 68 61 74 20 6d 75 6c 74 69 2d  p of that multi-
2bf70 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72  step.** pragma r
2bf80 65 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73  eturns 0 columns
2bf90 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20   of data..**.** 
2bfa0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
2bfb0 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
2bfc0 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  )].*/.int sqlite
2bfd0 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c  3_data_count(sql
2bfe0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2bff0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2c000 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20  EF: Fundamental 
2c010 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59  Datatypes.** KEY
2c020 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45  WORDS: SQLITE_TE
2c030 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79  XT.**.** ^(Every
2c040 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65   value in SQLite
2c050 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65   has one of five
2c060 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74   fundamental dat
2c070 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  atypes:.**.** <u
2c080 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69  l>.** <li> 64-bi
2c090 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
2c0a0 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20  .** <li> 64-bit 
2c0b0 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f  IEEE floating po
2c0c0 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c  int number.** <l
2c0d0 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69  i> string.** <li
2c0e0 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e  > BLOB.** <li> N
2c0f0 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a  ULL.** </ul>)^.*
2c100 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
2c110 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66  ants are codes f
2c120 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65  or each of those
2c130 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f   types..**.** No
2c140 74 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49  te that the SQLI
2c150 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74  TE_TEXT constant
2c160 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69   was also used i
2c170 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  n SQLite version
2c180 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70   2.** for a comp
2c190 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74  letely different
2c1a0 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77   meaning.  Softw
2c1b0 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61  are that links a
2c1c0 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53  gainst both.** S
2c1d0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20  QLite version 2 
2c1e0 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69  and SQLite versi
2c1f0 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20  on 3 should use 
2c200 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f  SQLITE3_TEXT, no
2c210 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54  t.** SQLITE_TEXT
2c220 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
2c230 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23  ITE_INTEGER  1.#
2c240 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c  define SQLITE_FL
2c250 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65  OAT    2.#define
2c260 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20   SQLITE_BLOB    
2c270 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
2c280 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66  E_NULL     5.#if
2c290 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  def SQLITE_TEXT.
2c2a0 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54  # undef SQLITE_T
2c2b0 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69  EXT.#else.# defi
2c2c0 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20  ne SQLITE_TEXT  
2c2d0 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66     3.#endif.#def
2c2e0 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54  ine SQLITE3_TEXT
2c2f0 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41       3../*.** CA
2c300 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56  PI3REF: Result V
2c310 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65  alues From A Que
2c320 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ry.** KEYWORDS: 
2c330 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  {column access f
2c340 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20  unctions}.**.** 
2c350 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66  These routines f
2c360 6f 72 6d 20 74 68 65 20 22 72 65 73 75 6c 74 20  orm the "result 
2c370 73 65 74 22 20 69 6e 74 65 72 66 61 63 65 2e 0a  set" interface..
2c380 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
2c390 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66  tines return inf
2c3a0 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61  ormation about a
2c3b0 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f   single column o
2c3c0 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  f the current.**
2c3d0 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61   result row of a
2c3e0 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65   query.  ^In eve
2c3f0 72 79 20 63 61 73 65 20 74 68 65 20 66 69 72 73  ry case the firs
2c400 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  t argument is a 
2c410 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68  pointer.** to th
2c420 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2c430 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62  ement] that is b
2c440 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28  eing evaluated (
2c450 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
2c460 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20  t*].** that was 
2c470 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73  returned from [s
2c480 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2c490 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69  2()] or one of i
2c4a0 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20  ts variants).** 
2c4b0 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61  and the second a
2c4c0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
2c4d0 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75  ndex of the colu
2c4e0 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66  mn for which inf
2c4f0 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75  ormation.** shou
2c500 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20  ld be returned. 
2c510 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f  ^The leftmost co
2c520 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75  lumn of the resu
2c530 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 20 69  lt set has the i
2c540 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20  ndex 0..** ^The 
2c550 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
2c560 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  s in the result 
2c570 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65  can be determine
2c580 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  d using.** [sqli
2c590 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
2c5a0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ()]..**.** If th
2c5b0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
2c5c0 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  does not current
2c5d0 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61  ly point to a va
2c5e0 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74  lid row, or if t
2c5f0 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64  he.** column ind
2c600 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e  ex is out of ran
2c610 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69  ge, the result i
2c620 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
2c630 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
2c640 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65  ay only be calle
2c650 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20  d when the most 
2c660 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a  recent call to.*
2c670 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
2c680 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20  )] has returned 
2c690 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64  [SQLITE_ROW] and
2c6a0 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c   neither.** [sql
2c6b0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f  ite3_reset()] no
2c6c0 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
2c6d0 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e  ize()] have been
2c6e0 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65   called subseque
2c6f0 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20  ntly..** If any 
2c700 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
2c710 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74  s are called aft
2c720 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  er [sqlite3_rese
2c730 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  t()] or.** [sqli
2c740 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2c750 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  or after [sqlite
2c760 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65  3_step()] has re
2c770 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68  turned.** someth
2c780 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ing other than [
2c790 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65  SQLITE_ROW], the
2c7a0 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
2c7b0 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73  efined..** If [s
2c7c0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
2c7d0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
2c7e0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2c7f0 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61  finalize()].** a
2c800 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61  re called from a
2c810 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
2c820 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74  d while any of t
2c830 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  hese routines.**
2c840 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68   are pending, th
2c850 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
2c860 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
2c870 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2c880 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72  _column_type() r
2c890 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
2c8a0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  he.** [SQLITE_IN
2c8b0 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65  TEGER | datatype
2c8c0 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69   code] for the i
2c8d0 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65  nitial data type
2c8e0 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c  .** of the resul
2c8f0 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20  t column.  ^The 
2c900 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69  returned value i
2c910 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  s one of [SQLITE
2c920 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53  _INTEGER],.** [S
2c930 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53  QLITE_FLOAT], [S
2c940 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51  QLITE_TEXT], [SQ
2c950 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b  LITE_BLOB], or [
2c960 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54  SQLITE_NULL].  T
2c970 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75  he value.** retu
2c980 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
2c990 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73  column_type() is
2c9a0 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c   only meaningful
2c9b0 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63   if no type.** c
2c9c0 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20  onversions have 
2c9d0 6f 63 63 75 72 72 65 64 20 61 73 20 64 65 73 63  occurred as desc
2c9e0 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66  ribed below.  Af
2c9f0 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65  ter a type conve
2ca00 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61  rsion,.** the va
2ca10 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
2ca20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2ca30 79 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e  ype() is undefin
2ca40 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76  ed.  Future.** v
2ca50 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
2ca60 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65  e may change the
2ca70 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c   behavior of sql
2ca80 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
2ca90 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ().** following 
2caa0 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
2cab0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  n..**.** ^If the
2cac0 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f   result is a BLO
2cad0 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e  B or UTF-8 strin
2cae0 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  g then the sqlit
2caf0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2cb00 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
2cb10 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
2cb20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
2cb30 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e   BLOB or string.
2cb40 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2cb50 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 20 73  lt is a UTF-16 s
2cb60 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69  tring, then sqli
2cb70 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2cb80 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74  () converts.** t
2cb90 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46  he string to UTF
2cba0 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75  -8 and then retu
2cbb0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
2cbc0 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20  f bytes..** ^If 
2cbd0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
2cbe0 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68  numeric value th
2cbf0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
2cc00 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a  n_bytes() uses.*
2cc10 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  * [sqlite3_snpri
2cc20 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72  ntf()] to conver
2cc30 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20  t that value to 
2cc40 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61  a UTF-8 string a
2cc50 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68  nd returns.** th
2cc60 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2cc70 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67  s in that string
2cc80 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
2cc90 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ult is NULL, the
2cca0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
2ccb0 5f 62 79 74 65 73 28 29 20 72 65 74 75 72 6e 73  _bytes() returns
2ccc0 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66   zero..**.** ^If
2ccd0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
2cce0 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36 20   BLOB or UTF-16 
2ccf0 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20  string then the 
2cd00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2cd10 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74  ytes16().** rout
2cd20 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
2cd30 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2cd40 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20  in that BLOB or 
2cd50 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
2cd60 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55  he result is a U
2cd70 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68 65  TF-8 string, the
2cd80 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
2cd90 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76 65  _bytes16() conve
2cda0 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  rts.** the strin
2cdb0 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64 20  g to UTF-16 and 
2cdc0 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65  then returns the
2cdd0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2cde0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
2cdf0 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63  ult is a numeric
2ce00 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69   value then sqli
2ce10 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2ce20 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71  16() uses.** [sq
2ce30 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
2ce40 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61  ] to convert tha
2ce50 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46  t value to a UTF
2ce60 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20 72  -16 string and r
2ce70 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75  eturns.** the nu
2ce80 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
2ce90 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a   that string..**
2cea0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
2ceb0 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71  is NULL, then sq
2cec0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2ced0 65 73 31 36 28 29 20 72 65 74 75 72 6e 73 20 7a  es16() returns z
2cee0 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ero..**.** ^The 
2cef0 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
2cf00 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  by [sqlite3_colu
2cf10 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20  mn_bytes()] and 
2cf20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
2cf30 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 64  umn_bytes16()] d
2cf40 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68  o not include th
2cf50 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  e zero terminato
2cf60 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a  rs at the end.**
2cf70 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20   of the string. 
2cf80 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74   ^For clarity: t
2cf90 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
2cfa0 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
2cfb0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2cfc0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
2cfd0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d  olumn_bytes16()]
2cfe0 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72 20   are the number 
2cff0 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74  of.** bytes in t
2d000 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74  he string, not t
2d010 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
2d020 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e  racters..**.** ^
2d030 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  Strings returned
2d040 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
2d050 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71  mn_text() and sq
2d060 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2d070 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65  t16(),.** even e
2d080 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72  mpty strings, ar
2d090 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65  e always zero-te
2d0a0 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20  rminated.  ^The 
2d0b0 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20  return.** value 
2d0c0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c  from sqlite3_col
2d0d0 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61  umn_blob() for a
2d0e0 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f   zero-length BLO
2d0f0 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  B is a NULL poin
2d100 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
2d110 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
2d120 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  by [sqlite3_colu
2d130 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61  mn_value()] is a
2d140 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65  n.** [unprotecte
2d150 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2d160 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70   object.  An unp
2d170 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2d180 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a  _value object.**
2d190 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65   may only be use
2d1a0 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f  d with [sqlite3_
2d1b0 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e  bind_value()] an
2d1c0 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  d [sqlite3_resul
2d1d0 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49  t_value()]..** I
2d1e0 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74  f the [unprotect
2d1f0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2d200 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  ] object returne
2d210 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
2d220 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
2d230 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20   is used in any 
2d240 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75  other way, inclu
2d250 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f  ding calls.** to
2d260 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b   routines like [
2d270 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
2d280 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  t()], [sqlite3_v
2d290 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a  alue_text()],.**
2d2a0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   or [sqlite3_val
2d2b0 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65  ue_bytes()], the
2d2c0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
2d2d0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
2d2e0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
2d2f0 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e  s attempt to con
2d300 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 77  vert the value w
2d310 68 65 72 65 20 61 70 70 72 6f 70 72 69 61 74 65  here appropriate
2d320 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70  .  ^For.** examp
2d330 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72  le, if the inter
2d340 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69  nal representati
2d350 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20  on is FLOAT and 
2d360 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a  a text result.**
2d370 20 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b   is requested, [
2d380 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
2d390 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65  ()] is used inte
2d3a0 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72  rnally to perfor
2d3b0 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73  m the.** convers
2d3c0 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ion automaticall
2d3d0 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77  y.  ^(The follow
2d3e0 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c  ing table detail
2d3f0 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e  s the conversion
2d400 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70  s.** that are ap
2d410 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  plied:.**.** <bl
2d420 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61  ockquote>.** <ta
2d430 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a  ble border="1">.
2d440 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65  ** <tr><th> Inte
2d450 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68  rnal<br>Type <th
2d460 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54  > Requested<br>T
2d470 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72  ype <th>  Conver
2d480 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c  sion.**.** <tr><
2d490 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
2d4a0 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
2d4b0 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20   Result is 0.** 
2d4c0 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
2d4d0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
2d4e0 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
2d4f0 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  0.0.** <tr><td> 
2d500 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20   NULL    <td>   
2d510 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73  TEXT    <td> Res
2d520 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e  ult is NULL poin
2d530 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ter.** <tr><td> 
2d540 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20   NULL    <td>   
2d550 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73  BLOB    <td> Res
2d560 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e  ult is NULL poin
2d570 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ter.** <tr><td> 
2d580 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46  INTEGER  <td>  F
2d590 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e  LOAT    <td> Con
2d5a0 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65  vert from intege
2d5b0 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74  r to float.** <t
2d5c0 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
2d5d0 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
2d5e0 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72  td> ASCII render
2d5f0 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67  ing of the integ
2d600 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  er.** <tr><td> I
2d610 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42  NTEGER  <td>   B
2d620 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65  LOB    <td> Same
2d630 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58   as INTEGER->TEX
2d640 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  T.** <tr><td>  F
2d650 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45  LOAT   <td> INTE
2d660 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  GER   <td> Conve
2d670 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f  rt from float to
2d680 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e   integer.** <tr>
2d690 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
2d6a0 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
2d6b0 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e  > ASCII renderin
2d6c0 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a  g of the float.*
2d6d0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
2d6e0 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20  T   <td>   BLOB 
2d6f0 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20     <td> Same as 
2d700 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c  FLOAT->TEXT.** <
2d710 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
2d720 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
2d730 3c 74 64 3e 20 55 73 65 20 61 74 6f 69 28 29 0a  <td> Use atoi().
2d740 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58  ** <tr><td>  TEX
2d750 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  T    <td>  FLOAT
2d760 20 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f      <td> Use ato
2d770 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  f().** <tr><td> 
2d780 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20   TEXT    <td>   
2d790 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20  BLOB    <td> No 
2d7a0 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74  change.** <tr><t
2d7b0 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
2d7c0 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
2d7d0 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20  Convert to TEXT 
2d7e0 74 68 65 6e 20 75 73 65 20 61 74 6f 69 28 29 0a  then use atoi().
2d7f0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
2d800 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  B    <td>  FLOAT
2d810 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74      <td> Convert
2d820 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73   to TEXT then us
2d830 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e  e atof().** <tr>
2d840 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
2d850 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
2d860 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72  > Add a zero ter
2d870 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65  minator if neede
2d880 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a  d.** </table>.**
2d890 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e   </blockquote>)^
2d8a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65  .**.** The table
2d8b0 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 66   above makes ref
2d8c0 65 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 61  erence to standa
2d8d0 72 64 20 43 20 6c 69 62 72 61 72 79 20 66 75 6e  rd C library fun
2d8e0 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a  ctions atoi().**
2d8f0 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 51   and atof().  SQ
2d900 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 65  Lite does not re
2d910 61 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20 66  ally use these f
2d920 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 61  unctions.  It ha
2d930 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75  s its.** own equ
2d940 69 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c  ivalent internal
2d950 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20   routines.  The 
2d960 61 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28  atoi() and atof(
2d970 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75  ) names are.** u
2d980 73 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65  sed in the table
2d990 20 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64   for brevity and
2d9a0 20 62 65 63 61 75 73 65 20 74 68 65 79 20 61 72   because they ar
2d9b0 65 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f  e familiar to mo
2d9c0 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d  st.** C programm
2d9d0 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ers..**.** Note 
2d9e0 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 63  that when type c
2d9f0 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72  onversions occur
2da00 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  , pointers retur
2da10 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20  ned by prior.** 
2da20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
2da30 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20  _column_blob(), 
2da40 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2da50 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a  ext(), and/or.**
2da60 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2da70 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 20  text16() may be 
2da80 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20  invalidated..** 
2da90 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73  Type conversions
2daa0 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76   and pointer inv
2dab0 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74  alidations might
2dac0 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65   occur.** in the
2dad0 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73   following cases
2dae0 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
2daf0 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c  <li> The initial
2db00 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c   content is a BL
2db10 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  OB and sqlite3_c
2db20 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a  olumn_text() or.
2db30 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
2db40 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
2db50 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65  is called.  A ze
2db60 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69  ro-terminator mi
2db70 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64  ght.**      need
2db80 20 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20   to be added to 
2db90 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e  the string.</li>
2dba0 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
2dbb0 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
2dbc0 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73  UTF-8 text and s
2dbd0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2dbe0 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20  tes16() or.**   
2dbf0 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
2dc00 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61  n_text16() is ca
2dc10 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65  lled.  The conte
2dc20 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  nt must be conve
2dc30 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20  rted.**      to 
2dc40 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20  UTF-16.</li>.** 
2dc50 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c  <li> The initial
2dc60 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d   content is UTF-
2dc70 31 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69  16 text and sqli
2dc80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2dc90 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
2dca0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2dcb0 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  t() is called.  
2dcc0 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74  The content must
2dcd0 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a   be converted.**
2dce0 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c        to UTF-8.<
2dcf0 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  /li>.** </ul>.**
2dd00 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73  .** ^Conversions
2dd10 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62   between UTF-16b
2dd20 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61  e and UTF-16le a
2dd30 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69  re always done i
2dd40 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a  n place and do.*
2dd50 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65  * not invalidate
2dd60 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72   a prior pointer
2dd70 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72  , though of cour
2dd80 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  se the content o
2dd90 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20  f the buffer.** 
2dda0 74 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 70  that the prior p
2ddb0 6f 69 6e 74 65 72 20 72 65 66 65 72 65 6e 63 65  ointer reference
2ddc0 73 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e  s will have been
2ddd0 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65   modified.  Othe
2dde0 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f  r kinds.** of co
2ddf0 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e  nversion are don
2de00 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20  e in place when 
2de10 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20  it is possible, 
2de20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68  but sometimes th
2de30 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f  ey.** are not po
2de40 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68  ssible and in th
2de50 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f 72 20  ose cases prior 
2de60 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76  pointers are inv
2de70 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  alidated..**.** 
2de80 54 68 65 20 73 61 66 65 73 74 20 61 6e 64 20 65  The safest and e
2de90 61 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62  asiest to rememb
2dea0 65 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20  er policy is to 
2deb0 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75  invoke these rou
2dec0 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20  tines.** in one 
2ded0 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
2dee0 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c   ways:.**.** <ul
2def0 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
2df00 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
2df10 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
2df20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2df30 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e  ()</li>.**  <li>
2df40 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2df50 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  lob() followed b
2df60 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
2df70 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a  _bytes()</li>.**
2df80 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
2df90 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f  lumn_text16() fo
2dfa0 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
2dfb0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2dfc0 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e  ()</li>.** </ul>
2dfd0 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20  .**.** In other 
2dfe0 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c  words, you shoul
2dff0 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63  d call sqlite3_c
2e000 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a  olumn_text(),.**
2e010 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2e020 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74  blob(), or sqlit
2e030 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2e040 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63  () first to forc
2e050 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20  e the result.** 
2e060 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 64  into the desired
2e070 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e   format, then in
2e080 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  voke sqlite3_col
2e090 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a  umn_bytes() or.*
2e0a0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
2e0b0 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20 66 69  _bytes16() to fi
2e0c0 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  nd the size of t
2e0d0 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e  he result.  Do n
2e0e0 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20  ot mix calls.** 
2e0f0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
2e100 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69  n_text() or sqli
2e110 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
2e120 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a  ) with calls to.
2e130 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
2e140 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64  n_bytes16(), and
2e150 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c   do not mix call
2e160 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
2e170 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20  umn_text16().** 
2e180 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71  with calls to sq
2e190 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2e1a0 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  es()..**.** ^The
2e1b0 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
2e1c0 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74  ed are valid unt
2e1d0 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  il a type conver
2e1e0 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a  sion occurs as.*
2e1f0 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 6f 76  * described abov
2e200 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c  e, or until [sql
2e210 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20  ite3_step()] or 
2e220 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2e230 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
2e240 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20  _finalize()] is 
2e250 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65  called.  ^The me
2e260 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 20  mory space used 
2e270 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a  to hold strings.
2e280 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20  ** and BLOBs is 
2e290 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61  freed automatica
2e2a0 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c  lly.  Do <b>not<
2e2b0 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69  /b> pass the poi
2e2c0 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a  nters returned.*
2e2d0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2e2e0 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69  n_blob()], [sqli
2e2f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2e300 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a  )], etc. into.**
2e310 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
2e320 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20  ]..**.** ^(If a 
2e330 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
2e340 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64  n error occurs d
2e350 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61  uring the evalua
2e360 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f  tion of any.** o
2e370 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
2e380 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75  , a default valu
2e390 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  e is returned.  
2e3a0 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75  The default valu
2e3b0 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74  e.** is either t
2e3c0 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68  he integer 0, th
2e3d0 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  e floating point
2e3e0 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20   number 0.0, or 
2e3f0 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
2e400 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 63  r.  Subsequent c
2e410 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
2e420 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c  _errcode()] will
2e430 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49   return.** [SQLI
2e440 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a  TE_NOMEM].)^.*/.
2e450 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2e460 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
2e470 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2e480 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
2e490 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2e4a0 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  es(sqlite3_stmt*
2e4b0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
2e4c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2e4d0 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f  bytes16(sqlite3_
2e4e0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2e4f0 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33  ;.double sqlite3
2e500 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73  _column_double(s
2e510 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2e520 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
2e530 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28  ite3_column_int(
2e540 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2e550 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65  nt iCol);.sqlite
2e560 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
2e570 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c  column_int64(sql
2e580 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2e590 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73  iCol);.const uns
2e5a0 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69  igned char *sqli
2e5b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2e5c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2e5d0 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20  nt iCol);.const 
2e5e0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
2e5f0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69  lumn_text16(sqli
2e600 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2e610 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
2e620 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71  3_column_type(sq
2e630 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2e640 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f   iCol);.sqlite3_
2e650 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63  value *sqlite3_c
2e660 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69  olumn_value(sqli
2e670 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2e680 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  Col);../*.** CAP
2e690 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41  I3REF: Destroy A
2e6a0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
2e6b0 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ent Object.**.**
2e6c0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69   ^The sqlite3_fi
2e6d0 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f  nalize() functio
2e6e0 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64  n is called to d
2e6f0 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72 65  elete a [prepare
2e700 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
2e710 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
2e720 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  cent evaluation 
2e730 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  of the statement
2e740 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20   encountered no 
2e750 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20  errors.** or if 
2e760 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
2e770 20 6e 65 76 65 72 20 62 65 65 6e 20 65 76 61 6c   never been eval
2e780 75 61 74 65 64 2c 20 74 68 65 6e 20 73 71 6c 69  uated, then sqli
2e790 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72  te3_finalize() r
2e7a0 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45  eturns.** SQLITE
2e7b0 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f  _OK.  ^If the mo
2e7c0 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61  st recent evalua
2e7d0 74 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e  tion of statemen
2e7e0 74 20 53 20 66 61 69 6c 65 64 2c 20 74 68 65 6e  t S failed, then
2e7f0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  .** sqlite3_fina
2e800 6c 69 7a 65 28 53 29 20 72 65 74 75 72 6e 73 20  lize(S) returns 
2e810 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 65 20  the appropriate 
2e820 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a  [error code] or.
2e830 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72  ** [extended err
2e840 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20  or code]..**.** 
2e850 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e  ^The sqlite3_fin
2e860 61 6c 69 7a 65 28 53 29 20 72 6f 75 74 69 6e 65  alize(S) routine
2e870 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61   can be called a
2e880 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69  t any point duri
2e890 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20 63  ng.** the life c
2e8a0 79 63 6c 65 20 6f 66 20 5b 70 72 65 70 61 72 65  ycle of [prepare
2e8b0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a  d statement] S:.
2e8c0 2a 2a 20 62 65 66 6f 72 65 20 73 74 61 74 65 6d  ** before statem
2e8d0 65 6e 74 20 53 20 69 73 20 65 76 65 72 20 65 76  ent S is ever ev
2e8e0 61 6c 75 61 74 65 64 2c 20 61 66 74 65 72 0a 2a  aluated, after.*
2e8f0 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61  * one or more ca
2e900 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
2e910 72 65 73 65 74 28 29 5d 2c 20 6f 72 20 61 66 74  reset()], or aft
2e920 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74  er any call.** t
2e930 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
2e940 29 5d 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  )] regardless of
2e950 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
2e960 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
2e970 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65  s.** completed e
2e980 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  xecution..**.** 
2e990 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65  ^Invoking sqlite
2e9a0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20  3_finalize() on 
2e9b0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
2e9c0 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  s a harmless no-
2e9d0 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  op..**.** The ap
2e9e0 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 66  plication must f
2e9f0 69 6e 61 6c 69 7a 65 20 65 76 65 72 79 20 5b 70  inalize every [p
2ea00 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2ea10 74 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 61  t] in order to a
2ea20 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65  void.** resource
2ea30 20 6c 65 61 6b 73 2e 20 20 49 74 20 69 73 20 61   leaks.  It is a
2ea40 20 67 72 69 65 76 6f 75 73 20 65 72 72 6f 72 20   grievous error 
2ea50 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  for the applicat
2ea60 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20 75 73  ion to try to us
2ea70 65 0a 2a 2a 20 61 20 70 72 65 70 61 72 65 64 20  e.** a prepared 
2ea80 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20  statement after 
2ea90 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61  it has been fina
2eaa0 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75 73 65 20  lized.  Any use 
2eab0 6f 66 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a  of a prepared.**
2eac0 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72   statement after
2ead0 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e   it has been fin
2eae0 61 6c 69 7a 65 64 20 63 61 6e 20 72 65 73 75 6c  alized can resul
2eaf0 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61  t in undefined a
2eb00 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c  nd.** undesirabl
2eb10 65 20 62 65 68 61 76 69 6f 72 20 73 75 63 68 20  e behavior such 
2eb20 61 73 20 73 65 67 66 61 75 6c 74 73 20 61 6e 64  as segfaults and
2eb30 20 68 65 61 70 20 63 6f 72 72 75 70 74 69 6f 6e   heap corruption
2eb40 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2eb50 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65  _finalize(sqlite
2eb60 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
2eb70 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2eb80 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72 65   Reset A Prepare
2eb90 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
2eba0 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ct.**.** The sql
2ebb0 69 74 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e  ite3_reset() fun
2ebc0 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20  ction is called 
2ebd0 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65 70  to reset a [prep
2ebe0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
2ebf0 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74  ** object back t
2ec00 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74  o its initial st
2ec10 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65  ate, ready to be
2ec20 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a   re-executed..**
2ec30 20 5e 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d   ^Any SQL statem
2ec40 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74 68  ent variables th
2ec50 61 74 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f  at had values bo
2ec60 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e  und to them usin
2ec70 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  g.** the [sqlite
2ec80 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71  3_bind_blob | sq
2ec90 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41  lite3_bind_*() A
2eca0 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72  PI] retain their
2ecb0 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20   values..** Use 
2ecc0 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62  [sqlite3_clear_b
2ecd0 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65  indings()] to re
2ece0 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73  set the bindings
2ecf0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ..**.** ^The [sq
2ed00 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
2ed10 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73  interface resets
2ed20 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2ed30 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62  tatement] S.** b
2ed40 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e  ack to the begin
2ed50 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67  ning of its prog
2ed60 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ram..**.** ^If t
2ed70 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
2ed80 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2ed90 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65  step(S)] for the
2eda0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
2edb0 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72  atement] S retur
2edc0 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  ned [SQLITE_ROW]
2edd0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45   or [SQLITE_DONE
2ede0 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c  ],.** or if [sql
2edf0 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61  ite3_step(S)] ha
2ee00 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62  s never before b
2ee10 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c  een called on S,
2ee20 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 65  .** then [sqlite
2ee30 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75  3_reset(S)] retu
2ee40 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e  rns [SQLITE_OK].
2ee50 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  .**.** ^If the m
2ee60 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
2ee70 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
2ee80 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20  (S)] for the.** 
2ee90 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2eea0 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64  ent] S indicated
2eeb0 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a   an error, then.
2eec0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
2eed0 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e  t(S)] returns an
2eee0 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
2eef0 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a  ror code]..**.**
2ef00 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72   ^The [sqlite3_r
2ef10 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61  eset(S)] interfa
2ef20 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  ce does not chan
2ef30 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a  ge the values.**
2ef40 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33   of any [sqlite3
2ef50 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69  _bind_blob|bindi
2ef60 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65  ngs] on the [pre
2ef70 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2ef80 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74   S..*/.int sqlit
2ef90 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33  e3_reset(sqlite3
2efa0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
2efb0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2efc0 43 72 65 61 74 65 20 4f 72 20 52 65 64 65 66 69  Create Or Redefi
2efd0 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73  ne SQL Functions
2efe0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66  .** KEYWORDS: {f
2eff0 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  unction creation
2f000 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45   routines}.** KE
2f010 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61  YWORDS: {applica
2f020 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
2f030 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45   function}.** KE
2f040 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61  YWORDS: {applica
2f050 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
2f060 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a   functions}.**.*
2f070 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f  * ^These functio
2f080 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79  ns (collectively
2f090 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74   known as "funct
2f0a0 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75  ion creation rou
2f0b0 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75  tines").** are u
2f0c0 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66  sed to add SQL f
2f0d0 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72  unctions or aggr
2f0e0 65 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64  egates or to red
2f0f0 65 66 69 6e 65 20 74 68 65 20 62 65 68 61 76 69  efine the behavi
2f100 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e  or.** of existin
2f110 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  g SQL functions 
2f120 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e 20 20  or aggregates.  
2f130 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65  The only differe
2f140 6e 63 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20  nces between.** 
2f150 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
2f160 72 65 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f  re the text enco
2f170 64 69 6e 67 20 65 78 70 65 63 74 65 64 20 66 6f  ding expected fo
2f180 72 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20  r.** the second 
2f190 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 6e  parameter (the n
2f1a0 61 6d 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74  ame of the funct
2f1b0 69 6f 6e 20 62 65 69 6e 67 20 63 72 65 61 74 65  ion being create
2f1c0 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70 72  d).** and the pr
2f1d0 65 73 65 6e 63 65 20 6f 72 20 61 62 73 65 6e 63  esence or absenc
2f1e0 65 20 6f 66 20 61 20 64 65 73 74 72 75 63 74 6f  e of a destructo
2f1f0 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a  r callback for.*
2f200 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
2f210 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a  n data pointer..
2f220 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
2f230 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
2f240 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
2f250 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68  ection] to which
2f260 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63   the SQL.** func
2f270 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64  tion is to be ad
2f280 64 65 64 2e 20 20 5e 49 66 20 61 6e 20 61 70 70  ded.  ^If an app
2f290 6c 69 63 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f  lication uses mo
2f2a0 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61  re than one data
2f2b0 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
2f2c0 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69 63 61 74  on then applicat
2f2d0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
2f2e0 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62  functions must b
2f2f0 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61  e added.** to ea
2f300 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ch database conn
2f310 65 63 74 69 6f 6e 20 73 65 70 61 72 61 74 65 6c  ection separatel
2f320 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65  y..**.** ^The se
2f330 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
2f340 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
2f350 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  e SQL function t
2f360 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a  o be created or.
2f370 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20 5e  ** redefined.  ^
2f380 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  The length of th
2f390 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65  e name is limite
2f3a0 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 20 69  d to 255 bytes i
2f3b0 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70  n a UTF-8.** rep
2f3c0 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63  resentation, exc
2f3d0 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65  lusive of the ze
2f3e0 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  ro-terminator.  
2f3f0 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e  ^Note that the n
2f400 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69  ame.** length li
2f410 6d 69 74 20 69 73 20 69 6e 20 55 54 46 2d 38 20  mit is in UTF-8 
2f420 62 79 74 65 73 2c 20 6e 6f 74 20 63 68 61 72 61  bytes, not chara
2f430 63 74 65 72 73 20 6e 6f 72 20 55 54 46 2d 31 36  cters nor UTF-16
2f440 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e   bytes.  .** ^An
2f450 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65  y attempt to cre
2f460 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  ate a function w
2f470 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d  ith a longer nam
2f480 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74  e.** will result
2f490 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   in [SQLITE_MISU
2f4a0 53 45 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e  SE] being return
2f4b0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74  ed..**.** ^The t
2f4c0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 28  hird parameter (
2f4d0 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20  nArg).** is the 
2f4e0 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
2f4f0 6e 74 73 20 74 68 61 74 20 74 68 65 20 53 51 4c  nts that the SQL
2f500 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
2f510 61 67 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e  aggregate takes.
2f520 20 5e 49 66 20 74 68 69 73 20 70 61 72 61 6d 65   ^If this parame
2f530 74 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20  ter is -1, then 
2f540 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2f550 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
2f560 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75   may take any nu
2f570 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
2f580 73 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20  s between 0 and 
2f590 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74  the limit.** set
2f5a0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d   by [sqlite3_lim
2f5b0 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  it]([SQLITE_LIMI
2f5c0 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29  T_FUNCTION_ARG])
2f5d0 2e 20 20 49 66 20 74 68 65 20 74 68 69 72 64 0a  .  If the third.
2f5e0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ** parameter is 
2f5f0 6c 65 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 20  less than -1 or 
2f600 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 32 37  greater than 127
2f610 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
2f620 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e  or is.** undefin
2f630 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
2f640 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c  ourth parameter,
2f650 20 65 54 65 78 74 52 65 70 2c 20 73 70 65 63 69   eTextRep, speci
2f660 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51  fies what.** [SQ
2f670 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74  LITE_UTF8 | text
2f680 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20   encoding] this 
2f690 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65  SQL function pre
2f6a0 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20  fers for.** its 
2f6b0 70 61 72 61 6d 65 74 65 72 73 2e 20 20 45 76 65  parameters.  Eve
2f6c0 72 79 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ry SQL function 
2f6d0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d  implementation m
2f6e0 75 73 74 20 62 65 20 61 62 6c 65 20 74 6f 20 77  ust be able to w
2f6f0 6f 72 6b 0a 2a 2a 20 77 69 74 68 20 55 54 46 2d  ork.** with UTF-
2f700 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20  8, UTF-16le, or 
2f710 55 54 46 2d 31 36 62 65 2e 20 20 42 75 74 20 73  UTF-16be.  But s
2f720 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ome implementati
2f730 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f  ons may be.** mo
2f740 72 65 20 65 66 66 69 63 69 65 6e 74 20 77 69 74  re efficient wit
2f750 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74  h one encoding t
2f760 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20 5e 41  han another.  ^A
2f770 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61  n application ma
2f780 79 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69  y.** invoke sqli
2f790 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2f7a0 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ion() or sqlite3
2f7b0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2f7c0 31 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a  16() multiple.**
2f7d0 20 74 69 6d 65 73 20 77 69 74 68 20 74 68 65 20   times with the 
2f7e0 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62 75  same function bu
2f7f0 74 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74  t with different
2f800 20 76 61 6c 75 65 73 20 6f 66 20 65 54 65 78 74   values of eText
2f810 52 65 70 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75  Rep..** ^When mu
2f820 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
2f830 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
2f840 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20  me function are 
2f850 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74  available, SQLit
2f860 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74  e.** will pick t
2f870 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f  he one that invo
2f880 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74 20 61  lves the least a
2f890 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f  mount of data co
2f8a0 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20  nversion..** If 
2f8b0 74 68 65 72 65 20 69 73 20 6f 6e 6c 79 20 61 20  there is only a 
2f8c0 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  single implement
2f8d0 61 74 69 6f 6e 20 77 68 69 63 68 20 64 6f 65 73  ation which does
2f8e0 20 6e 6f 74 20 63 61 72 65 20 77 68 61 74 20 74   not care what t
2f8f0 65 78 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67 20  ext.** encoding 
2f900 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68  is used, then th
2f910 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
2f920 74 20 73 68 6f 75 6c 64 20 62 65 20 5b 53 51 4c  t should be [SQL
2f930 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20  ITE_ANY]..**.** 
2f940 5e 28 54 68 65 20 66 69 66 74 68 20 70 61 72 61  ^(The fifth para
2f950 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 69  meter is an arbi
2f960 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20  trary pointer.  
2f970 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  The implementati
2f980 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e  on of the.** fun
2f990 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61  ction can gain a
2f9a0 63 63 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f  ccess to this po
2f9b0 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c  inter using [sql
2f9c0 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
2f9d0 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ].)^.**.** ^The 
2f9e0 73 69 78 74 68 2c 20 73 65 76 65 6e 74 68 20 61  sixth, seventh a
2f9f0 6e 64 20 65 69 67 68 74 68 20 70 61 72 61 6d 65  nd eighth parame
2fa00 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74  ters, xFunc, xSt
2fa10 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61  ep and xFinal, a
2fa20 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74  re.** pointers t
2fa30 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e  o C-language fun
2fa40 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c  ctions that impl
2fa50 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75  ement the SQL fu
2fa60 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
2fa70 72 65 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61  regate. ^A scala
2fa80 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72  r SQL function r
2fa90 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65  equires an imple
2faa0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
2fab0 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61   xFunc.** callba
2fac0 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f  ck only; NULL po
2fad0 69 6e 74 65 72 73 20 6d 75 73 74 20 62 65 20 70  inters must be p
2fae0 61 73 73 65 64 20 61 73 20 74 68 65 20 78 53 74  assed as the xSt
2faf0 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a  ep and xFinal.**
2fb00 20 70 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e   parameters. ^An
2fb10 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
2fb20 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73  unction requires
2fb30 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69   an implementati
2fb40 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61  on of xStep.** a
2fb50 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55  nd xFinal and NU
2fb60 4c 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73 74 20  LL pointer must 
2fb70 62 65 20 70 61 73 73 65 64 20 66 6f 72 20 78 46  be passed for xF
2fb80 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20  unc. ^To delete 
2fb90 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53  an existing.** S
2fba0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61  QL function or a
2fbb0 67 67 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e  ggregate, pass N
2fbc0 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f 72  ULL pointers for
2fbd0 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74   all three funct
2fbe0 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73  ion.** callbacks
2fbf0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65  ..**.** ^(If the
2fc00 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72   ninth parameter
2fc10 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61   to sqlite3_crea
2fc20 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29  te_function_v2()
2fc30 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a   is not NULL,.**
2fc40 20 74 68 65 6e 20 69 74 20 69 73 20 64 65 73 74   then it is dest
2fc50 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 61  ructor for the a
2fc60 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
2fc70 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65  pointer. .** The
2fc80 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 69   destructor is i
2fc90 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20  nvoked when the 
2fca0 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65  function is dele
2fcb0 74 65 64 2c 20 65 69 74 68 65 72 20 62 79 20 62  ted, either by b
2fcc0 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64  eing.** overload
2fcd0 65 64 20 6f 72 20 77 68 65 6e 20 74 68 65 20 64  ed or when the d
2fce0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2fcf0 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20  on closes.)^.** 
2fd00 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20  ^The destructor 
2fd10 69 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20  is also invoked 
2fd20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a  if the call to.*
2fd30 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
2fd40 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66  _function_v2() f
2fd50 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74  ails..** ^When t
2fd60 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 63 61  he destructor ca
2fd70 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 74 65  llback of the te
2fd80 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  nth parameter is
2fd90 20 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20   invoked, it.** 
2fda0 69 73 20 70 61 73 73 65 64 20 61 20 73 69 6e 67  is passed a sing
2fdb0 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
2fdc0 68 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  h is a copy of t
2fdd0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
2fde0 61 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ata .** pointer 
2fdf0 77 68 69 63 68 20 77 61 73 20 74 68 65 20 66 69  which was the fi
2fe00 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  fth parameter to
2fe10 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2fe20 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a  function_v2()..*
2fe30 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d  *.** ^It is perm
2fe40 69 74 74 65 64 20 74 6f 20 72 65 67 69 73 74 65  itted to registe
2fe50 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  r multiple imple
2fe60 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
2fe70 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69  e same.** functi
2fe80 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73 61 6d  ons with the sam
2fe90 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20  e name but with 
2fea0 65 69 74 68 65 72 20 64 69 66 66 65 72 69 6e 67  either differing
2feb0 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61   numbers of.** a
2fec0 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66  rguments or diff
2fed0 65 72 69 6e 67 20 70 72 65 66 65 72 72 65 64 20  ering preferred 
2fee0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20  text encodings. 
2fef0 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73   ^SQLite will us
2ff00 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65  e.** the impleme
2ff10 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73  ntation that mos
2ff20 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65  t closely matche
2ff30 73 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 69  s the way in whi
2ff40 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75  ch the.** SQL fu
2ff50 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20  nction is used. 
2ff60 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70   ^A function imp
2ff70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68  lementation with
2ff80 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a   a non-negative.
2ff90 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65  ** nArg paramete
2ffa0 72 20 69 73 20 61 20 62 65 74 74 65 72 20 6d 61  r is a better ma
2ffb0 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74  tch than a funct
2ffc0 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
2ffd0 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67  on with.** a neg
2ffe0 61 74 69 76 65 20 6e 41 72 67 2e 20 20 5e 41 20  ative nArg.  ^A 
2fff0 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
30000 68 65 20 70 72 65 66 65 72 72 65 64 20 74 65 78  he preferred tex
30010 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61  t encoding.** ma
30020 74 63 68 65 73 20 74 68 65 20 64 61 74 61 62 61  tches the databa
30030 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61  se encoding is a
30040 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68   better.** match
30050 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e   than a function
30060 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64   where the encod
30070 69 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74  ing is different
30080 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69  .  .** ^A functi
30090 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63  on where the enc
300a0 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65  oding difference
300b0 20 69 73 20 62 65 74 77 65 65 6e 20 55 54 46 31   is between UTF1
300c0 36 6c 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a  6le and UTF16be.
300d0 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d  ** is a closer m
300e0 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63  atch than a func
300f0 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65  tion where the e
30100 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e  ncoding differen
30110 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e  ce is.** between
30120 20 55 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e   UTF8 and UTF16.
30130 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e  .**.** ^Built-in
30140 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62   functions may b
30150 65 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20  e overloaded by 
30160 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  new application-
30170 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
30180 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70  s..**.** ^An app
30190 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
301a0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72   function is per
301b0 6d 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f  mitted to call o
301c0 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ther.** SQLite i
301d0 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65  nterfaces.  Howe
301e0 76 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20  ver, such calls 
301f0 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73  must not.** clos
30200 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
30210 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69  onnection nor fi
30220 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20  nalize or reset 
30230 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20  the prepared.** 
30240 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69  statement in whi
30250 63 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  ch the function 
30260 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69  is running..*/.i
30270 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
30280 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71  e_function(.  sq
30290 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e  lite3 *db,.  con
302a0 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69  st char *zFuncti
302b0 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41  onName,.  int nA
302c0 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  rg,.  int eTextR
302d0 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70  ep,.  void *pApp
302e0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63  ,.  void (*xFunc
302f0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
30300 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
30310 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
30320 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33  (*xStep)(sqlite3
30330 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
30340 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
30350 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29    void (*xFinal)
30360 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
30370 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
30380 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
30390 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  n16(.  sqlite3 *
303a0 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64  db,.  const void
303b0 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
303c0 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
303d0 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
303e0 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
303f0 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
30400 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
30410 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
30420 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
30430 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
30440 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
30450 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
30460 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
30470 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69  3_context*).);.i
30480 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
30490 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20  e_function_v2(. 
304a0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
304b0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e  const char *zFun
304c0 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
304d0 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
304e0 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
304f0 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
30500 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
30510 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
30520 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
30530 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
30540 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
30550 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
30560 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
30570 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
30580 65 78 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78  ext*),.  void(*x
30590 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a  Destroy)(void*).
305a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
305b0 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e  EF: Text Encodin
305c0 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  gs.**.** These c
305d0 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69  onstant define i
305e0 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74 68 61  nteger codes tha
305f0 74 20 72 65 70 72 65 73 65 6e 74 20 74 68 65 20  t represent the 
30600 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20  various.** text 
30610 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72  encodings suppor
30620 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a  ted by SQLite..*
30630 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
30640 5f 55 54 46 38 20 20 20 20 20 20 20 20 20 20 20  _UTF8           
30650 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
30660 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20 20 20  _UTF16LE        
30670 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
30680 5f 55 54 46 31 36 42 45 20 20 20 20 20 20 20 20  _UTF16BE        
30690 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
306a0 5f 55 54 46 31 36 20 20 20 20 20 20 20 20 20 20  _UTF16          
306b0 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69  4    /* Use nati
306c0 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f  ve byte order */
306d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
306e0 41 4e 59 20 20 20 20 20 20 20 20 20 20 20 20 35  ANY            5
306f0 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63      /* sqlite3_c
30700 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f  reate_function o
30710 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
30720 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
30730 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c  NED  8    /* sql
30740 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
30750 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f  ation only */../
30760 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
30770 65 70 72 65 63 61 74 65 64 20 46 75 6e 63 74 69  eprecated Functi
30780 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45  ons.** DEPRECATE
30790 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  D.**.** These fu
307a0 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70  nctions are [dep
307b0 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72  recated].  In or
307c0 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a  der to maintain.
307d0 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  ** backwards com
307e0 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 68 20  patibility with 
307f0 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 65 73  older code, thes
30800 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74  e functions cont
30810 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73  inue .** to be s
30820 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76  upported.  Howev
30830 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 74  er, new applicat
30840 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f 69  ions should avoi
30850 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20  d.** the use of 
30860 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e  these functions.
30870 20 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72    To help encour
30880 61 67 65 20 70 65 6f 70 6c 65 20 74 6f 20 61 76  age people to av
30890 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65  oid.** using the
308a0 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65  se functions, we
308b0 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74   are not going t
308c0 6f 20 74 65 6c 6c 20 79 6f 75 20 77 68 61 74 20  o tell you what 
308d0 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e  they do..*/.#ifn
308e0 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
308f0 44 45 50 52 45 43 41 54 45 44 0a 53 51 4c 49 54  DEPRECATED.SQLIT
30900 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
30910 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
30920 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  te_count(sqlite3
30930 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49  _context*);.SQLI
30940 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
30950 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65  t sqlite3_expire
30960 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  d(sqlite3_stmt*)
30970 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
30980 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
30990 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67  transfer_binding
309a0 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  s(sqlite3_stmt*,
309b0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b   sqlite3_stmt*);
309c0 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
309d0 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  ED int sqlite3_g
309e0 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f  lobal_recover(vo
309f0 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  id);.SQLITE_DEPR
30a00 45 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c 69  ECATED void sqli
30a10 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e  te3_thread_clean
30a20 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  up(void);.SQLITE
30a30 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
30a40 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61  sqlite3_memory_a
30a50 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69  larm(void(*)(voi
30a60 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  d*,sqlite3_int64
30a70 2c 69 6e 74 29 2c 0a 20 20 20 20 20 20 20 20 20  ,int),.         
30a80 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69               voi
30a90 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  d*,sqlite3_int64
30aa0 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  );.#endif../*.**
30ab0 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
30ac0 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f  ning SQL Functio
30ad0 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75  n Parameter Valu
30ae0 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c  es.**.** The C-l
30af0 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e  anguage implemen
30b00 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75  tation of SQL fu
30b10 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
30b20 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74  egates uses.** t
30b30 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72  his set of inter
30b40 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f  face routines to
30b50 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72 61   access the para
30b60 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a  meter values on.
30b70 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  ** the function 
30b80 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a  or aggregate..**
30b90 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66  .** The xFunc (f
30ba0 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69  or scalar functi
30bb0 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28 66  ons) or xStep (f
30bc0 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20 70  or aggregates) p
30bd0 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20  arameters.** to 
30be0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
30bf0 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20  function()] and 
30c00 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
30c10 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a  function16()].**
30c20 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b   define callback
30c30 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  s that implement
30c40 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
30c50 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
30c60 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20 70 61  s..** The 3rd pa
30c70 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65  rameter to these
30c80 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e   callbacks is an
30c90 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
30ca0 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63  rs to.** [protec
30cb0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
30cc0 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65  e] objects.  The
30cd0 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74  re is one [sqlit
30ce0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
30cf0 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72   for.** each par
30d00 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 51  ameter to the SQ
30d10 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65  L function.  The
30d20 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
30d30 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61  used to.** extra
30d40 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74  ct values from t
30d50 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
30d60 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a  e] objects..**.*
30d70 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
30d80 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20   work only with 
30d90 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
30da0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
30db0 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70  s..** Any attemp
30dc0 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20 72  t to use these r
30dd0 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75  outines on an [u
30de0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
30df0 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a  e3_value].** obj
30e00 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75  ect results in u
30e10 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f  ndefined behavio
30e20 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  r..**.** ^These 
30e30 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75  routines work ju
30e40 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72  st like the corr
30e50 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d  esponding [colum
30e60 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
30e70 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68  ns].** except th
30e80 61 74 20 20 74 68 65 73 65 20 72 6f 75 74 69 6e  at  these routin
30e90 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65  es take a single
30ea0 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
30eb0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
30ec0 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73  t.** pointer ins
30ed0 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74  tead of a [sqlit
30ee0 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65  e3_stmt*] pointe
30ef0 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72  r and an integer
30f00 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a   column number..
30f10 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
30f20 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
30f30 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 72  ) interface extr
30f40 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 73 74  acts a UTF-16 st
30f50 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e  ring.** in the n
30f60 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72  ative byte-order
30f70 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63   of the host mac
30f80 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73  hine.  ^The.** s
30f90 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
30fa0 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69  t16be() and sqli
30fb0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
30fc0 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  le() interfaces.
30fd0 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d 31  ** extract UTF-1
30fe0 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 67  6 strings as big
30ff0 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74  -endian and litt
31000 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63  le-endian respec
31010 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28  tively..**.** ^(
31020 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
31030 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29  e_numeric_type()
31040 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
31050 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20  pts to apply.** 
31060 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79  numeric affinity
31070 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20   to the value.  
31080 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20  This means that 
31090 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a  an attempt is.**
310a0 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74   made to convert
310b0 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e   the value to an
310c0 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61   integer or floa
310d0 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a  ting point.  If.
310e0 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72  ** such a conver
310f0 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65  sion is possible
31100 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66   without loss of
31110 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e   information (in
31120 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c   other.** words,
31130 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 73   if the value is
31140 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c   a string that l
31150 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62  ooks like a numb
31160 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  er).** then the 
31170 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65  conversion is pe
31180 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77  rformed.  Otherw
31190 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f  ise no conversio
311a0 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65  n occurs..** The
311b0 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
311c0 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74   | datatype] aft
311d0 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73  er conversion is
311e0 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a   returned.)^.**.
311f0 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 61  ** Please pay pa
31200 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69  rticular attenti
31210 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 74  on to the fact t
31220 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20  hat the pointer 
31230 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d  returned.** from
31240 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
31250 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65  blob()], [sqlite
31260 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
31270 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
31280 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20  value_text16()] 
31290 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74  can be invalidat
312a0 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75 65  ed by a subseque
312b0 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  nt call to.** [s
312c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
312d0 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  es()], [sqlite3_
312e0 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d  value_bytes16()]
312f0 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
31300 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20  _text()],.** or 
31310 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
31320 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  ext16()]..**.** 
31330 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
31340 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
31350 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
31360 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c  ad as.** the SQL
31370 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73   function that s
31380 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c  upplied the [sql
31390 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72  ite3_value*] par
313a0 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73  ameters..*/.cons
313b0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
313c0 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74  value_blob(sqlit
313d0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
313e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
313f0 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  tes(sqlite3_valu
31400 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
31410 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73  _value_bytes16(s
31420 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
31430 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76  double sqlite3_v
31440 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69  alue_double(sqli
31450 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
31460 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69   sqlite3_value_i
31470 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt(sqlite3_value
31480 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  *);.sqlite3_int6
31490 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  4 sqlite3_value_
314a0 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61  int64(sqlite3_va
314b0 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73  lue*);.const uns
314c0 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69  igned char *sqli
314d0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73  te3_value_text(s
314e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
314f0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
31500 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
31510 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
31520 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
31530 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
31540 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  16le(sqlite3_val
31550 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  ue*);.const void
31560 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
31570 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33  text16be(sqlite3
31580 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
31590 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65  lite3_value_type
315a0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
315b0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
315c0 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65  lue_numeric_type
315d0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
315e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
315f0 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67  F: Obtain Aggreg
31600 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e  ate Function Con
31610 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65  text.**.** Imple
31620 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61 67  mentations of ag
31630 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
31640 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a  tions use this.*
31650 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c  * routine to all
31660 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72  ocate memory for
31670 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73   storing their s
31680 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tate..**.** ^The
31690 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 65 20   first time the 
316a0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
316b0 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72  e_context(C,N) r
316c0 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64  outine is called
316d0 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69   .** for a parti
316e0 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 20  cular aggregate 
316f0 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65  function, SQLite
31700 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20  .** allocates N 
31710 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65  of memory, zeroe
31720 73 20 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72  s out that memor
31730 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  y, and returns a
31740 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
31750 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e  he new memory. ^
31760 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75  On second and su
31770 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
31780 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67  o.** sqlite3_agg
31790 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
317a0 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67   for the same ag
317b0 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
317c0 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68   instance,.** th
317d0 65 20 73 61 6d 65 20 62 75 66 66 65 72 20 69 73  e same buffer is
317e0 20 72 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69   returned.  Sqli
317f0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
31800 6e 74 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61  ntext() is norma
31810 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e  lly.** called on
31820 63 65 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f  ce for each invo
31830 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53  cation of the xS
31840 74 65 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64  tep callback and
31850 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73   then one.** las
31860 74 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20  t time when the 
31870 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20  xFinal callback 
31880 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57  is invoked.  ^(W
31890 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63  hen no rows matc
318a0 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74  h.** an aggregat
318b0 65 20 71 75 65 72 79 2c 20 74 68 65 20 78 53 74  e query, the xSt
318c0 65 70 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66  ep() callback of
318d0 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 66   the aggregate f
318e0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65  unction.** imple
318f0 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76  mentation is nev
31900 65 72 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46  er called and xF
31910 69 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64  inal() is called
31920 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a   exactly once..*
31930 2a 20 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73  * In those cases
31940 2c 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  , sqlite3_aggreg
31950 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69  ate_context() mi
31960 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f  ght be called fo
31970 72 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74  r the.** first t
31980 69 6d 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20  ime from within 
31990 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a  xFinal().)^.**.*
319a0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61  * ^The sqlite3_a
319b0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
319c0 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65  (C,N) routine re
319d0 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
319e0 6e 74 65 72 20 0a 2a 2a 20 77 68 65 6e 20 66 69  nter .** when fi
319f0 72 73 74 20 63 61 6c 6c 65 64 20 69 66 20 4e 20  rst called if N 
31a00 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20  is less than or 
31a10 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72  equal to zero or
31a20 20 69 66 20 61 20 6d 65 6d 6f 72 79 0a 2a 2a 20   if a memory.** 
31a30 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f  allocate error o
31a40 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ccurs..**.** ^(T
31a50 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61  he amount of spa
31a60 63 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  ce allocated by 
31a70 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
31a80 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69  e_context(C,N) i
31a90 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20  s.** determined 
31aa0 62 79 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74  by the N paramet
31ab0 65 72 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63  er on first succ
31ac0 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68  essful call.  Ch
31ad0 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61  anging the.** va
31ae0 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73  lue of N in subs
31af0 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73  equent call to s
31b00 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
31b10 5f 63 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69  _context() withi
31b20 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67  n.** the same ag
31b30 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
31b40 20 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e   instance will n
31b50 6f 74 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65  ot resize the me
31b60 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69  mory.** allocati
31b70 6f 6e 2e 29 5e 20 20 57 69 74 68 69 6e 20 74 68  on.)^  Within th
31b80 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  e xFinal callbac
31b90 6b 2c 20 69 74 20 69 73 20 63 75 73 74 6f 6d 61  k, it is customa
31ba0 72 79 20 74 6f 20 73 65 74 0a 2a 2a 20 4e 3d 30  ry to set.** N=0
31bb0 20 69 6e 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c   in calls to sql
31bc0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
31bd0 6f 6e 74 65 78 74 28 43 2c 4e 29 20 73 6f 20 74  ontext(C,N) so t
31be0 68 61 74 20 6e 6f 20 0a 2a 2a 20 70 6f 69 6e 74  hat no .** point
31bf0 6c 65 73 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  less memory allo
31c00 63 61 74 69 6f 6e 73 20 6f 63 63 75 72 2e 0a 2a  cations occur..*
31c10 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74  *.** ^SQLite aut
31c20 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73  omatically frees
31c30 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
31c40 63 61 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c  cated by .** sql
31c50 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
31c60 6f 6e 74 65 78 74 28 29 20 77 68 65 6e 20 74 68  ontext() when th
31c70 65 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72  e aggregate quer
31c80 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a  y concludes..**.
31c90 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72  ** The first par
31ca0 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 61  ameter must be a
31cb0 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
31cc0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
31cd0 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20   | SQL function 
31ce0 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73  context] that is
31cf0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
31d00 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78  eter.** to the x
31d10 53 74 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63  Step or xFinal c
31d20 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20  allback routine 
31d30 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20  that implements 
31d40 74 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a  the aggregate.**
31d50 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
31d60 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75   This routine mu
31d70 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
31d80 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
31d90 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68  d in which.** th
31da0 65 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  e aggregate SQL 
31db0 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
31dc0 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ing..*/.void *sq
31dd0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
31de0 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f  context(sqlite3_
31df0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42  context*, int nB
31e00 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ytes);../*.** CA
31e10 50 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74  PI3REF: User Dat
31e20 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a  a For Functions.
31e30 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
31e40 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69  e3_user_data() i
31e50 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
31e60 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
31e70 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77  e pointer that w
31e80 61 73 20 74 68 65 20 70 55 73 65 72 44 61 74 61  as the pUserData
31e90 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20   parameter (the 
31ea0 35 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a  5th parameter).*
31eb0 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
31ec0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
31ed0 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  n()].** and [sql
31ee0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
31ef0 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e  tion16()] routin
31f00 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c  es that original
31f10 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64  ly.** registered
31f20 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
31f30 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f   defined functio
31f40 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  n..**.** This ro
31f50 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61  utine must be ca
31f60 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
31f70 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
31f80 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  ch.** the applic
31f90 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
31fa0 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
31fb0 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  g..*/.void *sqli
31fc0 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71  te3_user_data(sq
31fd0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
31fe0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
31ff0 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
32000 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69  ction For Functi
32010 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ons.**.** ^The s
32020 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
32030 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72  b_handle() inter
32040 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63  face returns a c
32050 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f  opy of.** the po
32060 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61  inter to the [da
32070 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
32080 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61 72 61  n] (the 1st para
32090 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65  meter).** of the
320a0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
320b0 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20  _function()].** 
320c0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
320d0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
320e0 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  ] routines that 
320f0 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65  originally.** re
32100 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70  gistered the app
32110 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64  lication defined
32120 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 71   function..*/.sq
32130 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63  lite3 *sqlite3_c
32140 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
32150 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
32160 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
32170 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75  REF: Function Au
32180 78 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a  xiliary Data.**.
32190 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
321a0 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 62  ns may be used b
321b0 79 20 28 6e 6f 6e 2d 61 67 67 72 65 67 61 74 65  y (non-aggregate
321c0 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  ) SQL functions 
321d0 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20  to.** associate 
321e0 6d 65 74 61 64 61 74 61 20 77 69 74 68 20 61 72  metadata with ar
321f0 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49  gument values. I
32200 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65  f the same value
32210 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a   is passed to.**
32220 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61   multiple invoca
32230 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
32240 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64  e SQL function d
32250 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 63  uring query exec
32260 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20  ution, under.** 
32270 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63  some circumstanc
32280 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65  es the associate
32290 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62  d metadata may b
322a0 65 20 70 72 65 73 65 72 76 65 64 2e 20 20 41 6e  e preserved.  An
322b0 20 65 78 61 6d 70 6c 65 0a 2a 2a 20 6f 66 20 77   example.** of w
322c0 68 65 72 65 20 74 68 69 73 20 6d 69 67 68 74 20  here this might 
322d0 62 65 20 75 73 65 66 75 6c 20 69 73 20 69 6e 20  be useful is in 
322e0 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73  a regular-expres
322f0 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 0a 2a 2a  sion matching.**
32300 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63   function. The c
32310 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20  ompiled version 
32320 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65  of the regular e
32330 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65  xpression can be
32340 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65   stored as.** me
32350 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65  tadata associate
32360 64 20 77 69 74 68 20 74 68 65 20 70 61 74 74 65  d with the patte
32370 72 6e 20 73 74 72 69 6e 67 2e 20 20 0a 2a 2a 20  rn string.  .** 
32380 54 68 65 6e 20 61 73 20 6c 6f 6e 67 20 61 73 20  Then as long as 
32390 74 68 65 20 70 61 74 74 65 72 6e 20 73 74 72 69  the pattern stri
323a0 6e 67 20 72 65 6d 61 69 6e 73 20 74 68 65 20 73  ng remains the s
323b0 61 6d 65 2c 0a 2a 2a 20 74 68 65 20 63 6f 6d 70  ame,.** the comp
323c0 69 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78 70  iled regular exp
323d0 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72  ression can be r
323e0 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c  eused on multipl
323f0 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73  e.** invocations
32400 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e   of the same fun
32410 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ction..**.** ^Th
32420 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  e sqlite3_get_au
32430 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  xdata() interfac
32440 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
32450 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64  ter to the metad
32460 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ata.** associate
32470 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33  d by the sqlite3
32480 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 66  _set_auxdata() f
32490 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65  unction with the
324a0 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a   Nth argument.**
324b0 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70   value to the ap
324c0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
324d0 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20  d function. ^If 
324e0 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 74 61  there is no meta
324f0 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74  data.** associat
32500 65 64 20 77 69 74 68 20 74 68 65 20 66 75 6e 63  ed with the func
32510 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2c 20 74  tion argument, t
32520 68 69 73 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  his sqlite3_get_
32530 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66  auxdata() interf
32540 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61  ace.** returns a
32550 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
32560 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
32570 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c  3_set_auxdata(C,
32580 4e 2c 50 2c 58 29 20 69 6e 74 65 72 66 61 63 65  N,P,X) interface
32590 20 73 61 76 65 73 20 50 20 61 73 20 6d 65 74 61   saves P as meta
325a0 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74  data for the N-t
325b0 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66  h.** argument of
325c0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
325d0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
325e0 6e 2e 20 20 5e 53 75 62 73 65 71 75 65 6e 74 0a  n.  ^Subsequent.
325f0 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ** calls to sqli
32600 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
32610 43 2c 4e 29 20 72 65 74 75 72 6e 20 50 20 66 72  C,N) return P fr
32620 6f 6d 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  om the most rece
32630 6e 74 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65  nt.** sqlite3_se
32640 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c  t_auxdata(C,N,P,
32650 58 29 20 63 61 6c 6c 20 69 66 20 74 68 65 20 6d  X) call if the m
32660 65 74 61 64 61 74 61 20 69 73 20 73 74 69 6c 6c  etadata is still
32670 20 76 61 6c 69 64 20 6f 72 0a 2a 2a 20 4e 55 4c   valid or.** NUL
32680 4c 20 69 66 20 74 68 65 20 6d 65 74 61 64 61 74  L if the metadat
32690 61 20 68 61 73 20 62 65 65 6e 20 64 69 73 63 61  a has been disca
326a0 72 64 65 64 2e 0a 2a 2a 20 5e 41 66 74 65 72 20  rded..** ^After 
326b0 65 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c  each call to sql
326c0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
326d0 28 43 2c 4e 2c 50 2c 58 29 20 77 68 65 72 65 20  (C,N,P,X) where 
326e0 58 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a  X is not NULL,.*
326f0 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e  * SQLite will in
32700 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63  voke the destruc
32710 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 58 20 77  tor function X w
32720 69 74 68 20 70 61 72 61 6d 65 74 65 72 20 50 20  ith parameter P 
32730 65 78 61 63 74 6c 79 0a 2a 2a 20 6f 6e 63 65 2c  exactly.** once,
32740 20 77 68 65 6e 20 74 68 65 20 6d 65 74 61 64 61   when the metada
32750 74 61 20 69 73 20 64 69 73 63 61 72 64 65 64 2e  ta is discarded.
32760 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72  .** SQLite is fr
32770 65 65 20 74 6f 20 64 69 73 63 61 72 64 20 74 68  ee to discard th
32780 65 20 6d 65 74 61 64 61 74 61 20 61 74 20 61 6e  e metadata at an
32790 79 20 74 69 6d 65 2c 20 69 6e 63 6c 75 64 69 6e  y time, includin
327a0 67 3a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  g: <ul>.** <li> 
327b0 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70  when the corresp
327c0 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  onding function 
327d0 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65  parameter change
327e0 73 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68  s, or.** <li> wh
327f0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  en [sqlite3_rese
32800 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
32810 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20  _finalize()] is 
32820 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a  called for the.*
32830 2a 20 20 20 20 20 20 53 51 4c 20 73 74 61 74 65  *      SQL state
32840 6d 65 6e 74 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  ment, or.** <li>
32850 20 77 68 65 6e 20 73 71 6c 69 74 65 33 5f 73 65   when sqlite3_se
32860 74 5f 61 75 78 64 61 74 61 28 29 20 69 73 20 69  t_auxdata() is i
32870 6e 76 6f 6b 65 64 20 61 67 61 69 6e 20 6f 6e 20  nvoked again on 
32880 74 68 65 20 73 61 6d 65 20 70 61 72 61 6d 65 74  the same paramet
32890 65 72 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 64  er, or.** <li> d
328a0 75 72 69 6e 67 20 74 68 65 20 6f 72 69 67 69 6e  uring the origin
328b0 61 6c 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  al sqlite3_set_a
328c0 75 78 64 61 74 61 28 29 20 63 61 6c 6c 20 77 68  uxdata() call wh
328d0 65 6e 20 61 20 6d 65 6d 6f 72 79 20 0a 2a 2a 20  en a memory .** 
328e0 20 20 20 20 20 61 6c 6c 6f 63 61 74 69 6f 6e 20       allocation 
328f0 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 3c 2f  error occurs. </
32900 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  ul>)^.**.** Note
32910 20 74 68 65 20 6c 61 73 74 20 62 75 6c 6c 65 74   the last bullet
32920 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72 2e 20   in particular. 
32930 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   The destructor 
32940 58 20 69 6e 20 0a 2a 2a 20 73 71 6c 69 74 65 33  X in .** sqlite3
32950 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e  _set_auxdata(C,N
32960 2c 50 2c 58 29 20 6d 69 67 68 74 20 62 65 20 63  ,P,X) might be c
32970 61 6c 6c 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  alled immediatel
32980 79 2c 20 62 65 66 6f 72 65 20 74 68 65 0a 2a 2a  y, before the.**
32990 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
329a0 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
329b0 20 65 76 65 6e 20 72 65 74 75 72 6e 73 2e 20 20   even returns.  
329c0 48 65 6e 63 65 20 73 71 6c 69 74 65 33 5f 73 65  Hence sqlite3_se
329d0 74 5f 61 75 78 64 61 74 61 28 29 0a 2a 2a 20 73  t_auxdata().** s
329e0 68 6f 75 6c 64 20 62 65 20 63 61 6c 6c 65 64 20  hould be called 
329f0 6e 65 61 72 20 74 68 65 20 65 6e 64 20 6f 66 20  near the end of 
32a00 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  the function imp
32a10 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 20  lementation and 
32a20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  the.** function 
32a30 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73  implementation s
32a40 68 6f 75 6c 64 20 6e 6f 74 20 6d 61 6b 65 20 61  hould not make a
32a50 6e 79 20 75 73 65 20 6f 66 20 50 20 61 66 74 65  ny use of P afte
32a60 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74  r.** sqlite3_set
32a70 5f 61 75 78 64 61 74 61 28 29 20 68 61 73 20 62  _auxdata() has b
32a80 65 65 6e 20 63 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a  een called..**.*
32a90 2a 20 5e 28 49 6e 20 70 72 61 63 74 69 63 65 2c  * ^(In practice,
32aa0 20 6d 65 74 61 64 61 74 61 20 69 73 20 70 72 65   metadata is pre
32ab0 73 65 72 76 65 64 20 62 65 74 77 65 65 6e 20 66  served between f
32ac0 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f  unction calls fo
32ad0 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61  r.** function pa
32ae0 72 61 6d 65 74 65 72 73 20 74 68 61 74 20 61 72  rameters that ar
32af0 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 63  e compile-time c
32b00 6f 6e 73 74 61 6e 74 73 2c 20 69 6e 63 6c 75 64  onstants, includ
32b10 69 6e 67 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76  ing literal.** v
32b20 61 6c 75 65 73 20 61 6e 64 20 5b 70 61 72 61 6d  alues and [param
32b30 65 74 65 72 73 5d 20 61 6e 64 20 65 78 70 72 65  eters] and expre
32b40 73 73 69 6f 6e 73 20 63 6f 6d 70 6f 73 65 64 20  ssions composed 
32b50 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 2e 29 5e  from the same.)^
32b60 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
32b70 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61  tines must be ca
32b80 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
32b90 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
32ba0 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75  ch.** the SQL fu
32bb0 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
32bc0 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  g..*/.void *sqli
32bd0 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
32be0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
32bf0 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20 73  , int N);.void s
32c00 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
32c10 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
32c20 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64  xt*, int N, void
32c30 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64  *, void (*)(void
32c40 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *));.../*.** CAP
32c50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73  I3REF: Constants
32c60 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61   Defining Specia
32c70 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 65 68  l Destructor Beh
32c80 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73  avior.**.** Thes
32c90 65 20 61 72 65 20 73 70 65 63 69 61 6c 20 76 61  e are special va
32ca0 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64 65 73  lues for the des
32cb0 74 72 75 63 74 6f 72 20 74 68 61 74 20 69 73 20  tructor that is 
32cc0 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65  passed in as the
32cd0 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65  .** final argume
32ce0 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c  nt to routines l
32cf0 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ike [sqlite3_res
32d00 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e 49  ult_blob()].  ^I
32d10 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  f the destructor
32d20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20  .** argument is 
32d30 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69  SQLITE_STATIC, i
32d40 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  t means that the
32d50 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72   content pointer
32d60 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20   is constant.** 
32d70 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63  and will never c
32d80 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20  hange.  It does 
32d90 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64  not need to be d
32da0 65 73 74 72 6f 79 65 64 2e 20 20 5e 54 68 65 0a  estroyed.  ^The.
32db0 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  ** SQLITE_TRANSI
32dc0 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20  ENT value means 
32dd0 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74  that the content
32de0 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61   will likely cha
32df0 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65  nge in.** the ne
32e00 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 74 68  ar future and th
32e10 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64  at SQLite should
32e20 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72   make its own pr
32e30 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a  ivate copy of.**
32e40 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66   the content bef
32e50 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a  ore returning..*
32e60 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66  *.** The typedef
32e70 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f   is necessary to
32e80 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f   work around pro
32e90 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e  blems in certain
32ea0 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72  .** C++ compiler
32eb0 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f  s..*/.typedef vo
32ec0 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73  id (*sqlite3_des
32ed0 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f  tructor_type)(vo
32ee0 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51  id*);.#define SQ
32ef0 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20 20 20  LITE_STATIC     
32f00 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72   ((sqlite3_destr
32f10 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64  uctor_type)0).#d
32f20 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41  efine SQLITE_TRA
32f30 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74  NSIENT   ((sqlit
32f40 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79  e3_destructor_ty
32f50 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41  pe)-1)../*.** CA
32f60 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20  PI3REF: Setting 
32f70 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e  The Result Of An
32f80 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a   SQL Function.**
32f90 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
32fa0 65 73 20 61 72 65 20 75 73 65 64 20 62 79 20 74  es are used by t
32fb0 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e  he xFunc or xFin
32fc0 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61  al callbacks tha
32fd0 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53  t.** implement S
32fe0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
32ff0 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 53 65   aggregates.  Se
33000 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  e.** [sqlite3_cr
33010 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
33020 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
33030 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
33040 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69  )].** for additi
33050 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
33060 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  ..**.** These fu
33070 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72  nctions work ver
33080 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20  y much like the 
33090 5b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69  [parameter bindi
330a0 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a  ng] family of.**
330b0 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 20   functions used 
330c0 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20 74  to bind values t
330d0 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  o host parameter
330e0 73 20 69 6e 20 70 72 65 70 61 72 65 64 20 73 74  s in prepared st
330f0 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66  atements..** Ref
33100 65 72 20 74 6f 20 74 68 65 20 5b 53 51 4c 20 70  er to the [SQL p
33110 61 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65  arameter] docume
33120 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69  ntation for addi
33130 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
33140 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  on..**.** ^The s
33150 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
33160 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ob() interface s
33170 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66  ets the result f
33180 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63  rom.** an applic
33190 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
331a0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65  nction to be the
331b0 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74   BLOB whose cont
331c0 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a  ent is pointed.*
331d0 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f  * to by the seco
331e0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64  nd parameter and
331f0 20 77 68 69 63 68 20 69 73 20 4e 20 62 79 74 65   which is N byte
33200 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69  s long where N i
33210 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70  s the.** third p
33220 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
33230 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
33240 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69  ult_zeroblob() i
33250 6e 74 65 72 66 61 63 65 73 20 73 65 74 20 74 68  nterfaces set th
33260 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74  e result of.** t
33270 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
33280 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
33290 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e  to be a BLOB con
332a0 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f  taining all zero
332b0 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 4e 20  .** bytes and N 
332c0 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2c 20 77  bytes in size, w
332d0 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 76 61  here N is the va
332e0 6c 75 65 20 6f 66 20 74 68 65 20 32 6e 64 20 70  lue of the 2nd p
332f0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
33300 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
33310 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74  ult_double() int
33320 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
33330 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61  result from.** a
33340 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
33350 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
33360 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67 20  o be a floating 
33370 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65 63  point value spec
33380 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73 20  ified.** by its 
33390 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
333a0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
333b0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
333c0 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  and sqlite3_resu
333d0 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e  lt_error16() fun
333e0 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20  ctions.** cause 
333f0 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20  the implemented 
33400 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  SQL function to 
33410 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69  throw an excepti
33420 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75  on..** ^SQLite u
33430 73 65 73 20 74 68 65 20 73 74 72 69 6e 67 20 70  ses the string p
33440 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65  ointed to by the
33450 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65  .** 2nd paramete
33460 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65 73  r of sqlite3_res
33470 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73  ult_error() or s
33480 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
33490 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74 68  ror16().** as th
334a0 65 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72  e text of an err
334b0 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 5e 53 51  or message.  ^SQ
334c0 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20  Lite interprets 
334d0 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73  the error.** mes
334e0 73 61 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d  sage string from
334f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33500 65 72 72 6f 72 28 29 20 61 73 20 55 54 46 2d 38  error() as UTF-8
33510 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74  . ^SQLite.** int
33520 65 72 70 72 65 74 73 20 74 68 65 20 73 74 72 69  erprets the stri
33530 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ng from sqlite3_
33540 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
33550 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61   as UTF-16 in na
33560 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64  tive.** byte ord
33570 65 72 2e 20 20 5e 49 66 20 74 68 65 20 74 68 69  er.  ^If the thi
33580 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
33590 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
335a0 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  rror().** or sql
335b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
335c0 72 31 36 28 29 20 69 73 20 6e 65 67 61 74 69 76  r16() is negativ
335d0 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  e then SQLite ta
335e0 6b 65 73 20 61 73 20 74 68 65 20 65 72 72 6f 72  kes as the error
335f0 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c 20  .** message all 
33600 74 65 78 74 20 75 70 20 74 68 72 6f 75 67 68 20  text up through 
33610 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63  the first zero c
33620 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66  haracter..** ^If
33630 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
33640 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
33650 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f  result_error() o
33660 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  r.** sqlite3_res
33670 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73  ult_error16() is
33680 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 68   non-negative th
33690 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
336a0 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74  that many.** byt
336b0 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65  es (not characte
336c0 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e 64  rs) from the 2nd
336d0 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68   parameter as th
336e0 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  e error message.
336f0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
33700 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
33710 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  and sqlite3_resu
33720 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20  lt_error16().** 
33730 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20  routines make a 
33740 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
33750 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
33760 65 20 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a  e text before.**
33770 20 74 68 65 79 20 72 65 74 75 72 6e 2e 20 20 48   they return.  H
33780 65 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e  ence, the callin
33790 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64  g function can d
337a0 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20  eallocate or.** 
337b0 6d 6f 64 69 66 79 20 74 68 65 20 74 65 78 74 20  modify the text 
337c0 61 66 74 65 72 20 74 68 65 79 20 72 65 74 75 72  after they retur
337d0 6e 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a  n without harm..
337e0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
337f0 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64  result_error_cod
33800 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 68 61  e() function cha
33810 6e 67 65 73 20 74 68 65 20 65 72 72 6f 72 20 63  nges the error c
33820 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  ode.** returned 
33830 62 79 20 53 51 4c 69 74 65 20 61 73 20 61 20 72  by SQLite as a r
33840 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f  esult of an erro
33850 72 20 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e  r in a function.
33860 20 20 5e 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a    ^By default,.*
33870 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  * the error code
33880 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f 52   is SQLITE_ERROR
33890 2e 20 20 5e 41 20 73 75 62 73 65 71 75 65 6e 74  .  ^A subsequent
338a0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
338b0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a  _result_error().
338c0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
338d0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 72  sult_error16() r
338e0 65 73 65 74 73 20 74 68 65 20 65 72 72 6f 72 20  esets the error 
338f0 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f 45  code to SQLITE_E
33900 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  RROR..**.** ^The
33910 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33920 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 29 20 69  error_toobig() i
33930 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
33940 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20  SQLite to throw 
33950 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69  an.** error indi
33960 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 73 74  cating that a st
33970 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20  ring or BLOB is 
33980 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72  too long to repr
33990 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  esent..**.** ^Th
339a0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
339b0 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 29 20 69  _error_nomem() i
339c0 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
339d0 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20  SQLite to throw 
339e0 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69  an.** error indi
339f0 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65  cating that a me
33a00 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
33a10 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  failed..**.** ^T
33a20 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
33a30 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63  t_int() interfac
33a40 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72  e sets the retur
33a50 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68  n value.** of th
33a60 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
33a70 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
33a80 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 20  o be the 32-bit 
33a90 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a  signed integer.*
33aa0 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e  * value given in
33ab0 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e   the 2nd argumen
33ac0 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  t..** ^The sqlit
33ad0 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28  e3_result_int64(
33ae0 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
33af0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
33b00 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c  e.** of the appl
33b10 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
33b20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74  function to be t
33b30 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  he 64-bit signed
33b40 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75   integer.** valu
33b50 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32  e given in the 2
33b60 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
33b70 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
33b80 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e  result_null() in
33b90 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
33ba0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
33bb0 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
33bc0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
33bd0 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e  tion to be NULL.
33be0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
33bf0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28  te3_result_text(
33c00 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ), sqlite3_resul
33c10 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73  t_text16(),.** s
33c20 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
33c30 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71  xt16le(), and sq
33c40 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
33c50 74 31 36 62 65 28 29 20 69 6e 74 65 72 66 61 63  t16be() interfac
33c60 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65  es.** set the re
33c70 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
33c80 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
33c90 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
33ca0 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73  o be.** a text s
33cb0 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 20 72  tring which is r
33cc0 65 70 72 65 73 65 6e 74 65 64 20 61 73 20 55 54  epresented as UT
33cd0 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69  F-8, UTF-16 nati
33ce0 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a  ve byte order,.*
33cf0 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20  * UTF-16 little 
33d00 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31  endian, or UTF-1
33d10 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65  6 big endian, re
33d20 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e  spectively..** ^
33d30 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65  SQLite takes the
33d40 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f   text result fro
33d50 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  m the applicatio
33d60 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e  n from.** the 2n
33d70 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74  d parameter of t
33d80 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
33d90 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
33da0 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33  es..** ^If the 3
33db0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
33dc0 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
33dd0 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
33de0 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69  ces.** is negati
33df0 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  ve, then SQLite 
33e00 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78  takes result tex
33e10 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70  t from the 2nd p
33e20 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f  arameter.** thro
33e30 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65  ugh the first ze
33e40 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  ro character..**
33e50 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72   ^If the 3rd par
33e60 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
33e70 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
33e80 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
33e90 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
33ea0 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62  , then as many b
33eb0 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63  ytes (not charac
33ec0 74 65 72 73 29 20 6f 66 20 74 68 65 20 74 65 78  ters) of the tex
33ed0 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20  t.** pointed to 
33ee0 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  by the 2nd param
33ef0 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61  eter are taken a
33f00 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  s the applicatio
33f10 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e  n-defined.** fun
33f20 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 20 20 49  ction result.  I
33f30 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
33f40 74 65 72 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  ter is non-negat
33f50 69 76 65 2c 20 74 68 65 6e 20 69 74 0a 2a 2a 20  ive, then it.** 
33f60 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74 65  must be the byte
33f70 20 6f 66 66 73 65 74 20 69 6e 74 6f 20 74 68 65   offset into the
33f80 20 73 74 72 69 6e 67 20 77 68 65 72 65 20 74 68   string where th
33f90 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72  e NUL terminator
33fa0 20 77 6f 75 6c 64 0a 2a 2a 20 61 70 70 65 61 72   would.** appear
33fb0 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 20 77   if the string w
33fc0 68 65 72 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61  here NUL termina
33fd0 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c  ted.  If any NUL
33fe0 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 63 75   characters occu
33ff0 72 0a 2a 2a 20 69 6e 20 74 68 65 20 73 74 72 69  r.** in the stri
34000 6e 67 20 61 74 20 61 20 62 79 74 65 20 6f 66 66  ng at a byte off
34010 73 65 74 20 74 68 61 74 20 69 73 20 6c 65 73 73  set that is less
34020 20 74 68 61 6e 20 74 68 65 20 76 61 6c 75 65 20   than the value 
34030 6f 66 20 74 68 65 20 33 72 64 0a 2a 2a 20 70 61  of the 3rd.** pa
34040 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68  rameter, then th
34050 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69  e resulting stri
34060 6e 67 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20  ng will contain 
34070 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 61 6e  embedded NULs an
34080 64 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  d the.** result 
34090 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 6f  of expressions o
340a0 70 65 72 61 74 69 6e 67 20 6f 6e 20 73 74 72 69  perating on stri
340b0 6e 67 73 20 77 69 74 68 20 65 6d 62 65 64 64 65  ngs with embedde
340c0 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69  d NULs is undefi
340d0 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ned..** ^If the 
340e0 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
340f0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
34100 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
34110 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  aces.** or sqlit
34120 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69  e3_result_blob i
34130 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  s a non-NULL poi
34140 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74  nter, then SQLit
34150 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20  e calls that.** 
34160 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20  function as the 
34170 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68  destructor on th
34180 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72  e text or BLOB r
34190 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61  esult when it ha
341a0 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73  s.** finished us
341b0 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e  ing that result.
341c0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20  .** ^If the 4th 
341d0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
341e0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
341f0 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
34200 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65   or to.** sqlite
34210 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73  3_result_blob is
34220 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e   the special con
34230 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41  stant SQLITE_STA
34240 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  TIC, then SQLite
34250 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74  .** assumes that
34260 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f   the text or BLO
34270 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63  B result is in c
34280 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e  onstant space an
34290 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f  d does not.** co
342a0 70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  py the content o
342b0 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
342c0 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72  nor call a destr
342d0 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e  uctor on the con
342e0 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20  tent.** when it 
342f0 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69  has finished usi
34300 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a  ng that result..
34310 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70  ** ^If the 4th p
34320 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
34330 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
34340 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
34350 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
34360 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65  sult_blob is the
34370 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e   special constan
34380 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  t SQLITE_TRANSIE
34390 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74  NT.** then SQLit
343a0 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
343b0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74  f the result int
343c0 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64  o space obtained
343d0 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73   from.** from [s
343e0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
343f0 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 75 72   before it retur
34400 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ns..**.** ^The s
34410 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
34420 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  lue() interface 
34430 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
34440 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
34450 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
34460 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63  nction to be a c
34470 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72  opy the.** [unpr
34480 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
34490 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70  value] object sp
344a0 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 32  ecified by the 2
344b0 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e  nd parameter.  ^
344c0 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72  The.** sqlite3_r
344d0 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e  esult_value() in
344e0 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20  terface makes a 
344f0 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c  copy of the [sql
34500 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73  ite3_value].** s
34510 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69  o that the [sqli
34520 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69  te3_value] speci
34530 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 72 61  fied in the para
34540 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65  meter may change
34550 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f   or.** be deallo
34560 63 61 74 65 64 20 61 66 74 65 72 20 73 71 6c 69  cated after sqli
34570 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
34580 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f  () returns witho
34590 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b  ut harm..** ^A [
345a0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
345b0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
345c0 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 75 73  may always be us
345d0 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b  ed where an.** [
345e0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
345f0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
34600 74 20 69 73 20 72 65 71 75 69 72 65 64 2c 20 73  t is required, s
34610 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64  o either.** kind
34620 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   of [sqlite3_val
34630 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62  ue] object can b
34640 65 20 75 73 65 64 20 77 69 74 68 20 74 68 69 73  e used with this
34650 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
34660 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 74 69  * If these routi
34670 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66  nes are called f
34680 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64  rom within the d
34690 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 0a  ifferent thread.
346a0 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20  ** than the one 
346b0 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61  containing the a
346c0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
346d0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  ed function that
346e0 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65   received.** the
346f0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
34700 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20  t] pointer, the 
34710 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
34720 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73  fined..*/.void s
34730 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
34740 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ob(sqlite3_conte
34750 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
34760 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
34770 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
34780 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62  ite3_result_doub
34790 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
347a0 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f  xt*, double);.vo
347b0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
347c0 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f  t_error(sqlite3_
347d0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
347e0 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  char*, int);.voi
347f0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
34800 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33  _error16(sqlite3
34810 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
34820 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f   void*, int);.vo
34830 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
34840 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73  t_error_toobig(s
34850 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
34860 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
34870 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65  esult_error_nome
34880 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  m(sqlite3_contex
34890 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  t*);.void sqlite
348a0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63  3_result_error_c
348b0 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ode(sqlite3_cont
348c0 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  ext*, int);.void
348d0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
348e0 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  int(sqlite3_cont
348f0 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  ext*, int);.void
34900 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34910 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f  int64(sqlite3_co
34920 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f  ntext*, sqlite3_
34930 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c  int64);.void sql
34940 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c  ite3_result_null
34950 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
34960 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
34970 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c  _result_text(sql
34980 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
34990 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c  onst char*, int,
349a0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
349b0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
349c0 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c  esult_text16(sql
349d0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
349e0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
349f0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
34a00 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
34a10 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73  esult_text16le(s
34a20 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
34a30 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
34a40 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  t,void(*)(void*)
34a50 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
34a60 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28  result_text16be(
34a70 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
34a80 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
34a90 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  nt,void(*)(void*
34aa0 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
34ab0 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71  _result_value(sq
34ac0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
34ad0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
34ae0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
34af0 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71  sult_zeroblob(sq
34b00 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
34b10 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int n);../*.** C
34b20 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20  API3REF: Define 
34b30 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65  New Collating Se
34b40 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e 54  quences.**.** ^T
34b50 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61  hese functions a
34b60 64 64 2c 20 72 65 6d 6f 76 65 2c 20 6f 72 20 6d  dd, remove, or m
34b70 6f 64 69 66 79 20 61 20 5b 63 6f 6c 6c 61 74 69  odify a [collati
34b80 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 0a 2a  on] associated.*
34b90 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  * with the [data
34ba0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
34bb0 20 73 70 65 63 69 66 69 65 64 20 61 73 20 74 68   specified as th
34bc0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
34bd0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ..**.** ^The nam
34be0 65 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69  e of the collati
34bf0 6f 6e 20 69 73 20 61 20 55 54 46 2d 38 20 73 74  on is a UTF-8 st
34c00 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69  ring.** for sqli
34c10 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
34c20 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  tion() and sqlit
34c30 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
34c40 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20  ion_v2().** and 
34c50 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  a UTF-16 string 
34c60 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  in native byte o
34c70 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33  rder for sqlite3
34c80 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
34c90 6e 31 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61  n16()..** ^Colla
34ca0 74 69 6f 6e 20 6e 61 6d 65 73 20 74 68 61 74 20  tion names that 
34cb0 63 6f 6d 70 61 72 65 20 65 71 75 61 6c 20 61 63  compare equal ac
34cc0 63 6f 72 64 69 6e 67 20 74 6f 20 5b 73 71 6c 69  cording to [sqli
34cd0 74 65 33 5f 73 74 72 6e 69 63 6d 70 28 29 5d 20  te3_strnicmp()] 
34ce0 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65  are.** considere
34cf0 64 20 74 6f 20 62 65 20 74 68 65 20 73 61 6d 65  d to be the same
34d00 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54   name..**.** ^(T
34d10 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
34d20 74 20 28 65 54 65 78 74 52 65 70 29 20 6d 75 73  t (eTextRep) mus
34d30 74 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20  t be one of the 
34d40 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75  constants:.** <u
34d50 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
34d60 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69  TE_UTF8],.** <li
34d70 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  > [SQLITE_UTF16L
34d80 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  E],.** <li> [SQL
34d90 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a  ITE_UTF16BE],.**
34da0 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54   <li> [SQLITE_UT
34db0 46 31 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  F16], or.** <li>
34dc0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41   [SQLITE_UTF16_A
34dd0 4c 49 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c  LIGNED]..** </ul
34de0 3e 29 5e 0a 2a 2a 20 5e 54 68 65 20 65 54 65 78  >)^.** ^The eTex
34df0 74 52 65 70 20 61 72 67 75 6d 65 6e 74 20 64 65  tRep argument de
34e00 74 65 72 6d 69 6e 65 73 20 74 68 65 20 65 6e 63  termines the enc
34e10 6f 64 69 6e 67 20 6f 66 20 73 74 72 69 6e 67 73  oding of strings
34e20 20 70 61 73 73 65 64 0a 2a 2a 20 74 6f 20 74 68   passed.** to th
34e30 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
34e40 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c 20 78  tion callback, x
34e50 43 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68  Callback..** ^Th
34e60 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d  e [SQLITE_UTF16]
34e70 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 55 54 46   and [SQLITE_UTF
34e80 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75  16_ALIGNED] valu
34e90 65 73 20 66 6f 72 20 65 54 65 78 74 52 65 70 0a  es for eTextRep.
34ea0 2a 2a 20 66 6f 72 63 65 20 73 74 72 69 6e 67 73  ** force strings
34eb0 20 74 6f 20 62 65 20 55 54 46 31 36 20 77 69 74   to be UTF16 wit
34ec0 68 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  h native byte or
34ed0 64 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  der..** ^The [SQ
34ee0 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
34ef0 45 44 5d 20 76 61 6c 75 65 20 66 6f 72 20 65 54  ED] value for eT
34f00 65 78 74 52 65 70 20 66 6f 72 63 65 73 20 73 74  extRep forces st
34f10 72 69 6e 67 73 20 74 6f 20 62 65 67 69 6e 0a 2a  rings to begin.*
34f20 2a 20 6f 6e 20 61 6e 20 65 76 65 6e 20 62 79 74  * on an even byt
34f30 65 20 61 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a  e address..**.**
34f40 20 5e 54 68 65 20 66 6f 75 72 74 68 20 61 72 67   ^The fourth arg
34f50 75 6d 65 6e 74 2c 20 70 41 72 67 2c 20 69 73 20  ument, pArg, is 
34f60 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  an application d
34f70 61 74 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ata pointer that
34f80 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 68   is passed.** th
34f90 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72  rough as the fir
34fa0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
34fb0 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
34fc0 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a  ction callback..
34fd0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68  **.** ^The fifth
34fe0 20 61 72 67 75 6d 65 6e 74 2c 20 78 43 61 6c 6c   argument, xCall
34ff0 62 61 63 6b 2c 20 69 73 20 61 20 70 6f 69 6e 74  back, is a point
35000 65 72 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74  er to the collat
35010 69 6e 67 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ing function..**
35020 20 5e 4d 75 6c 74 69 70 6c 65 20 63 6f 6c 6c 61   ^Multiple colla
35030 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 63  ting functions c
35040 61 6e 20 62 65 20 72 65 67 69 73 74 65 72 65 64  an be registered
35050 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20   using the same 
35060 6e 61 6d 65 20 62 75 74 0a 2a 2a 20 77 69 74 68  name but.** with
35070 20 64 69 66 66 65 72 65 6e 74 20 65 54 65 78 74   different eText
35080 52 65 70 20 70 61 72 61 6d 65 74 65 72 73 20 61  Rep parameters a
35090 6e 64 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  nd SQLite will u
350a0 73 65 20 77 68 69 63 68 65 76 65 72 0a 2a 2a 20  se whichever.** 
350b0 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
350c0 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75  s the least amou
350d0 6e 74 20 6f 66 20 64 61 74 61 20 74 72 61 6e 73  nt of data trans
350e0 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49  formation..** ^I
350f0 66 20 74 68 65 20 78 43 61 6c 6c 62 61 63 6b 20  f the xCallback 
35100 61 72 67 75 6d 65 6e 74 20 69 73 20 4e 55 4c 4c  argument is NULL
35110 20 74 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74   then the collat
35120 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a  ing function is.
35130 2a 2a 20 64 65 6c 65 74 65 64 2e 20 20 5e 57 68  ** deleted.  ^Wh
35140 65 6e 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67  en all collating
35150 20 66 75 6e 63 74 69 6f 6e 73 20 68 61 76 69 6e   functions havin
35160 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20  g the same name 
35170 61 72 65 20 64 65 6c 65 74 65 64 2c 0a 2a 2a 20  are deleted,.** 
35180 74 68 61 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 69  that collation i
35190 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 75 73 61 62  s no longer usab
351a0 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63  le..**.** ^The c
351b0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
351c0 6e 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  n callback is in
351d0 76 6f 6b 65 64 20 77 69 74 68 20 61 20 63 6f 70  voked with a cop
351e0 79 20 6f 66 20 74 68 65 20 70 41 72 67 20 0a 2a  y of the pArg .*
351f0 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  * application da
35200 74 61 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 77  ta pointer and w
35210 69 74 68 20 74 77 6f 20 73 74 72 69 6e 67 73 20  ith two strings 
35220 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  in the encoding 
35230 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20  specified.** by 
35240 74 68 65 20 65 54 65 78 74 52 65 70 20 61 72 67  the eTextRep arg
35250 75 6d 65 6e 74 2e 20 20 54 68 65 20 63 6f 6c 6c  ument.  The coll
35260 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d  ating function m
35270 75 73 74 20 72 65 74 75 72 6e 20 61 6e 0a 2a 2a  ust return an.**
35280 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 69 73   integer that is
35290 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 2c   negative, zero,
352a0 20 6f 72 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20   or positive.** 
352b0 69 66 20 74 68 65 20 66 69 72 73 74 20 73 74 72  if the first str
352c0 69 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ing is less than
352d0 2c 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67  , equal to, or g
352e0 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 65 20  reater than the 
352f0 73 65 63 6f 6e 64 2c 0a 2a 2a 20 72 65 73 70 65  second,.** respe
35300 63 74 69 76 65 6c 79 2e 20 20 41 20 63 6f 6c 6c  ctively.  A coll
35310 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d  ating function m
35320 75 73 74 20 61 6c 77 61 79 73 20 72 65 74 75 72  ust always retur
35330 6e 20 74 68 65 20 73 61 6d 65 20 61 6e 73 77 65  n the same answe
35340 72 0a 2a 2a 20 67 69 76 65 6e 20 74 68 65 20 73  r.** given the s
35350 61 6d 65 20 69 6e 70 75 74 73 2e 20 20 49 66 20  ame inputs.  If 
35360 74 77 6f 20 6f 72 20 6d 6f 72 65 20 63 6f 6c 6c  two or more coll
35370 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20  ating functions 
35380 61 72 65 20 72 65 67 69 73 74 65 72 65 64 0a 2a  are registered.*
35390 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 63 6f  * to the same co
353a0 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 28 75 73  llation name (us
353b0 69 6e 67 20 64 69 66 66 65 72 65 6e 74 20 65 54  ing different eT
353c0 65 78 74 52 65 70 20 76 61 6c 75 65 73 29 20 74  extRep values) t
353d0 68 65 6e 20 61 6c 6c 0a 2a 2a 20 6d 75 73 74 20  hen all.** must 
353e0 67 69 76 65 20 61 6e 20 65 71 75 69 76 61 6c 65  give an equivale
353f0 6e 74 20 61 6e 73 77 65 72 20 77 68 65 6e 20 69  nt answer when i
35400 6e 76 6f 6b 65 64 20 77 69 74 68 20 65 71 75 69  nvoked with equi
35410 76 61 6c 65 6e 74 20 73 74 72 69 6e 67 73 2e 0a  valent strings..
35420 2a 2a 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67  ** The collating
35430 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6f   function must o
35440 62 65 79 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  bey the followin
35450 67 20 70 72 6f 70 65 72 74 69 65 73 20 66 6f 72  g properties for
35460 20 61 6c 6c 0a 2a 2a 20 73 74 72 69 6e 67 73 20   all.** strings 
35470 41 2c 20 42 2c 20 61 6e 64 20 43 3a 0a 2a 2a 0a  A, B, and C:.**.
35480 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ol>.** <li> 
35490 49 66 20 41 3d 3d 42 20 74 68 65 6e 20 42 3d 3d  If A==B then B==
354a0 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d  A..** <li> If A=
354b0 3d 42 20 61 6e 64 20 42 3d 3d 43 20 74 68 65 6e  =B and B==C then
354c0 20 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e 20 49   A==C..** <li> I
354d0 66 20 41 26 6c 74 3b 42 20 54 48 45 4e 20 42 26  f A&lt;B THEN B&
354e0 67 74 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66  gt;A..** <li> If
354f0 20 41 26 6c 74 3b 42 20 61 6e 64 20 42 26 6c 74   A&lt;B and B&lt
35500 3b 43 20 74 68 65 6e 20 41 26 6c 74 3b 43 2e 0a  ;C then A&lt;C..
35510 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </ol>.**.** I
35520 66 20 61 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  f a collating fu
35530 6e 63 74 69 6f 6e 20 66 61 69 6c 73 20 61 6e 79  nction fails any
35540 20 6f 66 20 74 68 65 20 61 62 6f 76 65 20 63 6f   of the above co
35550 6e 73 74 72 61 69 6e 74 73 20 61 6e 64 20 74 68  nstraints and th
35560 61 74 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6e 67 20  at.** collating 
35570 66 75 6e 63 74 69 6f 6e 20 69 73 20 20 72 65 67  function is  reg
35580 69 73 74 65 72 65 64 20 61 6e 64 20 75 73 65 64  istered and used
35590 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
355a0 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a  ior of SQLite.**
355b0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
355c0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
355d0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
355e0 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69  on_v2() works li
355f0 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ke sqlite3_creat
35600 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a  e_collation().**
35610 20 77 69 74 68 20 74 68 65 20 61 64 64 69 74 69   with the additi
35620 6f 6e 20 74 68 61 74 20 74 68 65 20 78 44 65 73  on that the xDes
35630 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  troy callback is
35640 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 70 41 72 67   invoked on pArg
35650 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6c   when.** the col
35660 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
35670 69 73 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e  is deleted..** ^
35680 43 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  Collating functi
35690 6f 6e 73 20 61 72 65 20 64 65 6c 65 74 65 64 20  ons are deleted 
356a0 77 68 65 6e 20 74 68 65 79 20 61 72 65 20 6f 76  when they are ov
356b0 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65  erridden by late
356c0 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 74 68  r.** calls to th
356d0 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61  e collation crea
356e0 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f  tion functions o
356f0 72 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 64  r when the.** [d
35700 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
35710 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64 20 75 73  on] is closed us
35720 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  ing [sqlite3_clo
35730 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  se()]..**.** ^Th
35740 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62  e xDestroy callb
35750 61 63 6b 20 69 73 20 3c 75 3e 6e 6f 74 3c 2f 75  ack is <u>not</u
35760 3e 20 63 61 6c 6c 65 64 20 69 66 20 74 68 65 20  > called if the 
35770 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61  .** sqlite3_crea
35780 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
35790 29 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73  ) function fails
357a0 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  .  Applications 
357b0 74 68 61 74 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  that invoke.** s
357c0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
357d0 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 69 74  llation_v2() wit
357e0 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 44 65  h a non-NULL xDe
357f0 73 74 72 6f 79 20 61 72 67 75 6d 65 6e 74 20 73  stroy argument s
35800 68 6f 75 6c 64 20 0a 2a 2a 20 63 68 65 63 6b 20  hould .** check 
35810 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20  the return code 
35820 61 6e 64 20 64 69 73 70 6f 73 65 20 6f 66 20 74  and dispose of t
35830 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
35840 61 74 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  ata pointer.** t
35850 68 65 6d 73 65 6c 76 65 73 20 72 61 74 68 65 72  hemselves rather
35860 20 74 68 61 6e 20 65 78 70 65 63 74 69 6e 67 20   than expecting 
35870 53 51 4c 69 74 65 20 74 6f 20 64 65 61 6c 20 77  SQLite to deal w
35880 69 74 68 20 69 74 20 66 6f 72 20 74 68 65 6d 2e  ith it for them.
35890 0a 2a 2a 20 54 68 69 73 20 69 73 20 64 69 66 66  .** This is diff
358a0 65 72 65 6e 74 20 66 72 6f 6d 20 65 76 65 72 79  erent from every
358b0 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
358c0 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 69 6e  terface.  The in
358d0 63 6f 6e 73 69 73 74 65 6e 63 79 20 0a 2a 2a 20  consistency .** 
358e0 69 73 20 75 6e 66 6f 72 74 75 6e 61 74 65 20 62  is unfortunate b
358f0 75 74 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61  ut cannot be cha
35900 6e 67 65 64 20 77 69 74 68 6f 75 74 20 62 72 65  nged without bre
35910 61 6b 69 6e 67 20 62 61 63 6b 77 61 72 64 73 20  aking backwards 
35920 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  .** compatibilit
35930 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  y..**.** See als
35940 6f 3a 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  o:  [sqlite3_col
35950 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d  lation_needed()]
35960 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f   and [sqlite3_co
35970 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
35980 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
35990 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
359a0 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a  tion(.  sqlite3*
359b0 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  , .  const char 
359c0 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65  *zName, .  int e
359d0 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64  TextRep, .  void
359e0 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78   *pArg,.  int(*x
359f0 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69  Compare)(void*,i
35a00 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69  nt,const void*,i
35a10 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a  nt,const void*).
35a20 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
35a30 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
35a40 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  v2(.  sqlite3*, 
35a50 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
35a60 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65  Name, .  int eTe
35a70 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a  xtRep, .  void *
35a80 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f  pArg,.  int(*xCo
35a90 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74  mpare)(void*,int
35aa0 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74  ,const void*,int
35ab0 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20  ,const void*),. 
35ac0 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29   void(*xDestroy)
35ad0 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73  (void*).);.int s
35ae0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
35af0 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c  llation16(.  sql
35b00 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20  ite3*, .  const 
35b10 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69  void *zName,.  i
35b20 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20  nt eTextRep, .  
35b30 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e  void *pArg,.  in
35b40 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69  t(*xCompare)(voi
35b50 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
35b60 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
35b70 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  d*).);../*.** CA
35b80 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f  PI3REF: Collatio
35b90 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63  n Needed Callbac
35ba0 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f  ks.**.** ^To avo
35bb0 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67  id having to reg
35bc0 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74  ister all collat
35bd0 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65  ion sequences be
35be0 66 6f 72 65 20 61 20 64 61 74 61 62 61 73 65 0a  fore a database.
35bf0 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20  ** can be used, 
35c00 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63  a single callbac
35c10 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62  k function may b
35c20 65 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74  e registered wit
35c30 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61  h the.** [databa
35c40 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
35c50 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65  o be invoked whe
35c60 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69 6e  never an undefin
35c70 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20  ed collation.** 
35c80 73 65 71 75 65 6e 63 65 20 69 73 20 72 65 71 75  sequence is requ
35c90 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ired..**.** ^If 
35ca0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
35cb0 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67  registered using
35cc0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
35cd0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20  lation_needed() 
35ce0 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20  API,.** then it 
35cf0 69 73 20 70 61 73 73 65 64 20 74 68 65 20 6e 61  is passed the na
35d00 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 64  mes of undefined
35d10 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
35d20 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67 73 0a  nces as strings.
35d30 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54  ** encoded in UT
35d40 46 2d 38 2e 20 5e 49 66 20 73 71 6c 69 74 65 33  F-8. ^If sqlite3
35d50 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
35d60 64 31 36 28 29 20 69 73 20 75 73 65 64 2c 0a 2a  d16() is used,.*
35d70 2a 20 74 68 65 20 6e 61 6d 65 73 20 61 72 65 20  * the names are 
35d80 70 61 73 73 65 64 20 61 73 20 55 54 46 2d 31 36  passed as UTF-16
35d90 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69   in machine nati
35da0 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
35db0 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 65 69 74  * ^A call to eit
35dc0 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 72 65 70  her function rep
35dd0 6c 61 63 65 73 20 74 68 65 20 65 78 69 73 74 69  laces the existi
35de0 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65  ng collation-nee
35df0 64 65 64 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ded callback..**
35e00 0a 2a 2a 20 5e 28 57 68 65 6e 20 74 68 65 20 63  .** ^(When the c
35e10 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
35e20 65 64 2c 20 74 68 65 20 66 69 72 73 74 20 61 72  ed, the first ar
35e30 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73  gument passed is
35e40 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68   a copy.** of th
35e50 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
35e60 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  t to sqlite3_col
35e70 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20  lation_needed() 
35e80 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
35e90 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
35ea0 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ().  The second 
35eb0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
35ec0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
35ed0 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 74 68 69  ection.  The thi
35ee0 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f  rd argument is o
35ef0 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54  ne of [SQLITE_UT
35f00 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46  F8], [SQLITE_UTF
35f10 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51  16BE],.** or [SQ
35f20 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69  LITE_UTF16LE], i
35f30 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f  ndicating the mo
35f40 73 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72  st desirable for
35f50 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69  m of the collati
35f60 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66  on.** sequence f
35f70 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64  unction required
35f80 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  .  The fourth pa
35f90 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e  rameter is the n
35fa0 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65  ame of the.** re
35fb0 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  quired collation
35fc0 20 73 65 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a   sequence.)^.**.
35fd0 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  ** The callback 
35fe0 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20  function should 
35ff0 72 65 67 69 73 74 65 72 20 74 68 65 20 64 65 73  register the des
36000 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75  ired collation u
36010 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
36020 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
36030 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  n()], [sqlite3_c
36040 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
36050 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
36060 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
36070 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a  ation_v2()]..*/.
36080 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  int sqlite3_coll
36090 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20  ation_needed(.  
360a0 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69  sqlite3*, .  voi
360b0 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76  d*, .  void(*)(v
360c0 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e  oid*,sqlite3*,in
360d0 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74  t eTextRep,const
360e0 20 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73   char*).);.int s
360f0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
36100 5f 6e 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c  _needed16(.  sql
36110 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c  ite3*, .  void*,
36120 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  .  void(*)(void*
36130 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54  ,sqlite3*,int eT
36140 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69  extRep,const voi
36150 64 2a 29 0a 29 3b 0a 0a 23 69 66 64 65 66 20 53  d*).);..#ifdef S
36160 51 4c 49 54 45 5f 48 41 53 5f 43 4f 44 45 43 0a  QLITE_HAS_CODEC.
36170 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68  /*.** Specify th
36180 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63  e key for an enc
36190 72 79 70 74 65 64 20 64 61 74 61 62 61 73 65 2e  rypted database.
361a0 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73    This routine s
361b0 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c  hould be.** call
361c0 65 64 20 72 69 67 68 74 20 61 66 74 65 72 20 73  ed right after s
361d0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a  qlite3_open()..*
361e0 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f  *.** The code to
361f0 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20   implement this 
36200 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c  API is not avail
36210 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c  able in the publ
36220 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66  ic release.** of
36230 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20   SQLite..*/.int 
36240 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73  sqlite3_key(.  s
36250 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
36260 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
36270 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20   Database to be 
36280 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e  rekeyed */.  con
36290 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69  st void *pKey, i
362a0 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54  nt nKey     /* T
362b0 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 69 6e 74  he key */.);.int
362c0 20 73 71 6c 69 74 65 33 5f 6b 65 79 5f 76 32 28   sqlite3_key_v2(
362d0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
362e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
362f0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f    /* Database to
36300 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20   be rekeyed */. 
36310 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62   const char *zDb
36320 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20 20 20  Name,           
36330 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 64  /* Name of the d
36340 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
36350 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69  st void *pKey, i
36360 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54  nt nKey     /* T
36370 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a  he key */.);../*
36380 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b  .** Change the k
36390 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61  ey on an open da
363a0 74 61 62 61 73 65 2e 20 20 49 66 20 74 68 65 20  tabase.  If the 
363b0 63 75 72 72 65 6e 74 20 64 61 74 61 62 61 73 65  current database
363c0 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79   is not.** encry
363d0 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69  pted, this routi
363e0 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20  ne will encrypt 
363f0 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20  it.  If pNew==0 
36400 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a  or nNew==0, the.
36410 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73 20 64  ** database is d
36420 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  ecrypted..**.** 
36430 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c  The code to impl
36440 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69  ement this API i
36450 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20  s not available 
36460 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65  in the public re
36470 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69  lease.** of SQLi
36480 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  te..*/.int sqlit
36490 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69  e3_rekey(.  sqli
364a0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
364b0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
364c0 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b  tabase to be rek
364d0 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  eyed */.  const 
364e0 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20  void *pKey, int 
364f0 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20  nKey     /* The 
36500 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 69 6e  new key */.);.in
36510 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 5f  t sqlite3_rekey_
36520 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
36530 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  b,              
36540 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
36550 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a   to be rekeyed *
36560 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
36570 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20  zDbName,        
36580 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
36590 65 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20  e database */.  
365a0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79  const void *pKey
365b0 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f  , int nKey     /
365c0 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f  * The new key */
365d0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69  .);../*.** Speci
365e0 66 79 20 74 68 65 20 61 63 74 69 76 61 74 69 6f  fy the activatio
365f0 6e 20 6b 65 79 20 66 6f 72 20 61 20 53 45 45 20  n key for a SEE 
36600 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 73  database.  Unles
36610 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 2c  s .** activated,
36620 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 53 45 45   none of the SEE
36630 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77   routines will w
36640 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  ork..*/.void sql
36650 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f 73 65  ite3_activate_se
36660 65 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  e(.  const char 
36670 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20 20 20  *zPassPhrase    
36680 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f      /* Activatio
36690 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23  n phrase */.);.#
366a0 65 6e 64 69 66 0a 0a 23 69 66 64 65 66 20 53 51  endif..#ifdef SQ
366b0 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 45 52 4f  LITE_ENABLE_CERO
366c0 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20  D./*.** Specify 
366d0 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b  the activation k
366e0 65 79 20 66 6f 72 20 61 20 43 45 52 4f 44 20 64  ey for a CEROD d
366f0 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73  atabase.  Unless
36700 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20   .** activated, 
36710 6e 6f 6e 65 20 6f 66 20 74 68 65 20 43 45 52 4f  none of the CERO
36720 44 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20  D routines will 
36730 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  work..*/.void sq
36740 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f 63  lite3_activate_c
36750 65 72 6f 64 28 0a 20 20 63 6f 6e 73 74 20 63 68  erod(.  const ch
36760 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20  ar *zPassPhrase 
36770 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61         /* Activa
36780 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29  tion phrase */.)
36790 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  ;.#endif../*.** 
367a0 43 41 50 49 33 52 45 46 3a 20 53 75 73 70 65 6e  CAPI3REF: Suspen
367b0 64 20 45 78 65 63 75 74 69 6f 6e 20 46 6f 72 20  d Execution For 
367c0 41 20 53 68 6f 72 74 20 54 69 6d 65 0a 2a 2a 0a  A Short Time.**.
367d0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73  ** The sqlite3_s
367e0 6c 65 65 70 28 29 20 66 75 6e 63 74 69 6f 6e 20  leep() function 
367f0 63 61 75 73 65 73 20 74 68 65 20 63 75 72 72 65  causes the curre
36800 6e 74 20 74 68 72 65 61 64 20 74 6f 20 73 75 73  nt thread to sus
36810 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a  pend execution.*
36820 2a 20 66 6f 72 20 61 74 20 6c 65 61 73 74 20 61  * for at least a
36830 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69   number of milli
36840 73 65 63 6f 6e 64 73 20 73 70 65 63 69 66 69 65  seconds specifie
36850 64 20 69 6e 20 69 74 73 20 70 61 72 61 6d 65 74  d in its paramet
36860 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  er..**.** If the
36870 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
36880 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f  m does not suppo
36890 72 74 20 73 6c 65 65 70 20 72 65 71 75 65 73 74  rt sleep request
368a0 73 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73  s with.** millis
368b0 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c  econd time resol
368c0 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ution, then the 
368d0 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f 75  time will be rou
368e0 6e 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68  nded up to.** th
368f0 65 20 6e 65 61 72 65 73 74 20 73 65 63 6f 6e 64  e nearest second
36900 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  . The number of 
36910 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
36920 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a  sleep actually.*
36930 2a 20 72 65 71 75 65 73 74 65 64 20 66 72 6f 6d  * requested from
36940 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
36950 79 73 74 65 6d 20 69 73 20 72 65 74 75 72 6e 65  ystem is returne
36960 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  d..**.** ^SQLite
36970 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69 73   implements this
36980 20 69 6e 74 65 72 66 61 63 65 20 62 79 20 63 61   interface by ca
36990 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c 65 65 70  lling the xSleep
369a0 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20  ().** method of 
369b0 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
369c0 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
369d0 2e 20 20 49 66 20 74 68 65 20 78 53 6c 65 65 70  .  If the xSleep
369e0 28 29 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20  () method.** of 
369f0 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20  the default VFS 
36a00 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74  is not implement
36a10 65 64 20 63 6f 72 72 65 63 74 6c 79 2c 20 6f 72  ed correctly, or
36a20 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64   not implemented
36a30 20 61 74 0a 2a 2a 20 61 6c 6c 2c 20 74 68 65 6e   at.** all, then
36a40 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
36a50 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29   sqlite3_sleep()
36a60 20 6d 61 79 20 64 65 76 69 61 74 65 20 66 72 6f   may deviate fro
36a70 6d 20 74 68 65 20 64 65 73 63 72 69 70 74 69 6f  m the descriptio
36a80 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 70 72 65 76  n.** in the prev
36a90 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 73 2e  ious paragraphs.
36aa0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
36ab0 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  sleep(int);../*.
36ac0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d  ** CAPI3REF: Nam
36ad0 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20  e Of The Folder 
36ae0 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72  Holding Temporar
36af0 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28  y Files.**.** ^(
36b00 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76  If this global v
36b10 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20  ariable is made 
36b20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  to point to a st
36b30 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a  ring which is.**
36b40 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66   the name of a f
36b50 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69  older (a.k.a. di
36b60 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61  rectory), then a
36b70 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ll temporary fil
36b80 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79  es.** created by
36b90 20 53 51 4c 69 74 65 20 77 68 65 6e 20 75 73 69   SQLite when usi
36ba0 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e 20 5b 73  ng a built-in [s
36bb0 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 56 46 53  qlite3_vfs | VFS
36bc0 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 70 6c 61  ].** will be pla
36bd0 63 65 64 20 69 6e 20 74 68 61 74 20 64 69 72 65  ced in that dire
36be0 63 74 6f 72 79 2e 29 5e 20 20 5e 49 66 20 74 68  ctory.)^  ^If th
36bf0 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69  is variable.** i
36c00 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
36c10 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 70 65  , then SQLite pe
36c20 72 66 6f 72 6d 73 20 61 20 73 65 61 72 63 68 20  rforms a search 
36c30 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61  for an appropria
36c40 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20  te.** temporary 
36c50 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79 2e 0a  file directory..
36c60 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20  **.** It is not 
36c70 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20  safe to read or 
36c80 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69  modify this vari
36c90 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68 61  able in more tha
36ca0 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20  n one.** thread 
36cb0 61 74 20 61 20 74 69 6d 65 2e 20 20 49 74 20 69  at a time.  It i
36cc0 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65  s not safe to re
36cd0 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69  ad or modify thi
36ce0 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66  s variable.** if
36cf0 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
36d00 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e  nection] is bein
36d10 67 20 75 73 65 64 20 61 74 20 74 68 65 20 73 61  g used at the sa
36d20 6d 65 20 74 69 6d 65 20 69 6e 20 61 20 73 65 70  me time in a sep
36d30 61 72 61 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e  arate.** thread.
36d40 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74 65 6e 64  .** It is intend
36d50 65 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72  ed that this var
36d60 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63  iable be set onc
36d70 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20  e.** as part of 
36d80 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69  process initiali
36d90 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72  zation and befor
36da0 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74  e any SQLite int
36db0 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e  erface.** routin
36dc0 65 73 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c  es have been cal
36dd0 6c 65 64 20 61 6e 64 20 74 68 61 74 20 74 68 69  led and that thi
36de0 73 20 76 61 72 69 61 62 6c 65 20 72 65 6d 61 69  s variable remai
36df0 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74  n unchanged.** t
36e00 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a  hereafter..**.**
36e10 20 5e 54 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72   ^The [temp_stor
36e20 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67  e_directory prag
36e30 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20 74  ma] may modify t
36e40 68 69 73 20 76 61 72 69 61 62 6c 65 20 61 6e 64  his variable and
36e50 20 63 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20   cause.** it to 
36e60 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20  point to memory 
36e70 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
36e80 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20  qlite3_malloc]. 
36e90 20 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a   ^Furthermore,.*
36ea0 2a 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72  * the [temp_stor
36eb0 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67  e_directory prag
36ec0 6d 61 5d 20 61 6c 77 61 79 73 20 61 73 73 75 6d  ma] always assum
36ed0 65 73 20 74 68 61 74 20 61 6e 79 20 73 74 72 69  es that any stri
36ee0 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68 69 73 20  ng.** that this 
36ef0 76 61 72 69 61 62 6c 65 20 70 6f 69 6e 74 73 20  variable points 
36f00 74 6f 20 69 73 20 68 65 6c 64 20 69 6e 20 6d 65  to is held in me
36f10 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
36f20 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  om .** [sqlite3_
36f30 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20  malloc] and the 
36f40 70 72 61 67 6d 61 20 6d 61 79 20 61 74 74 65 6d  pragma may attem
36f50 70 74 20 74 6f 20 66 72 65 65 20 74 68 61 74 20  pt to free that 
36f60 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20  memory.** using 
36f70 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a  [sqlite3_free]..
36f80 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20 74 68 69  ** Hence, if thi
36f90 73 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 6f  s variable is mo
36fa0 64 69 66 69 65 64 20 64 69 72 65 63 74 6c 79 2c  dified directly,
36fb0 20 65 69 74 68 65 72 20 69 74 20 73 68 6f 75 6c   either it shoul
36fc0 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c  d be.** made NUL
36fd0 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20 70 6f 69  L or made to poi
36fe0 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74  nt to memory obt
36ff0 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
37000 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f  te3_malloc].** o
37010 72 20 65 6c 73 65 20 74 68 65 20 75 73 65 20 6f  r else the use o
37020 66 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72  f the [temp_stor
37030 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67  e_directory prag
37040 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65 20 61 76  ma] should be av
37050 6f 69 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  oided..**.** <b>
37060 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20  Note to Windows 
37070 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f  Runtime users:</
37080 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72  b>  The temporar
37090 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74  y directory must
370a0 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72   be set.** prior
370b0 20 74 6f 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   to calling [sql
370c0 69 74 65 33 5f 6f 70 65 6e 5d 20 6f 72 20 5b 73  ite3_open] or [s
370d0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 5d 2e  qlite3_open_v2].
370e0 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72    Otherwise, var
370f0 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73  ious.** features
37100 20 74 68 61 74 20 72 65 71 75 69 72 65 20 74 68   that require th
37110 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61  e use of tempora
37120 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69  ry files may fai
37130 6c 2e 20 20 48 65 72 65 20 69 73 20 61 6e 0a 2a  l.  Here is an.*
37140 2a 20 65 78 61 6d 70 6c 65 20 6f 66 20 68 6f 77  * example of how
37150 20 74 6f 20 64 6f 20 74 68 69 73 20 75 73 69 6e   to do this usin
37160 67 20 43 2b 2b 20 77 69 74 68 20 74 68 65 20 57  g C++ with the W
37170 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 3a 0a  indows Runtime:.
37180 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
37190 65 3e 3c 70 72 65 3e 0a 2a 2a 20 4c 50 43 57 53  e><pre>.** LPCWS
371a0 54 52 20 7a 50 61 74 68 20 3d 20 57 69 6e 64 6f  TR zPath = Windo
371b0 77 73 3a 3a 53 74 6f 72 61 67 65 3a 3a 41 70 70  ws::Storage::App
371c0 6c 69 63 61 74 69 6f 6e 44 61 74 61 3a 3a 43 75  licationData::Cu
371d0 72 72 65 6e 74 2d 3e 0a 2a 2a 20 26 6e 62 73 70  rrent->.** &nbsp
371e0 3b 20 20 20 20 20 54 65 6d 70 6f 72 61 72 79 46  ;     TemporaryF
371f0 6f 6c 64 65 72 2d 3e 50 61 74 68 2d 3e 44 61 74  older->Path->Dat
37200 61 28 29 3b 0a 2a 2a 20 63 68 61 72 20 7a 50 61  a();.** char zPa
37210 74 68 42 75 66 26 23 39 31 3b 4d 41 58 5f 50 41  thBuf&#91;MAX_PA
37220 54 48 20 2b 20 31 26 23 39 33 3b 3b 0a 2a 2a 20  TH + 1&#93;;.** 
37230 6d 65 6d 73 65 74 28 7a 50 61 74 68 42 75 66 2c  memset(zPathBuf,
37240 20 30 2c 20 73 69 7a 65 6f 66 28 7a 50 61 74 68   0, sizeof(zPath
37250 42 75 66 29 29 3b 0a 2a 2a 20 57 69 64 65 43 68  Buf));.** WideCh
37260 61 72 54 6f 4d 75 6c 74 69 42 79 74 65 28 43 50  arToMultiByte(CP
37270 5f 55 54 46 38 2c 20 30 2c 20 7a 50 61 74 68 2c  _UTF8, 0, zPath,
37280 20 2d 31 2c 20 7a 50 61 74 68 42 75 66 2c 20 73   -1, zPathBuf, s
37290 69 7a 65 6f 66 28 7a 50 61 74 68 42 75 66 29 2c  izeof(zPathBuf),
372a0 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20 20 20 4e  .** &nbsp;     N
372b0 55 4c 4c 2c 20 4e 55 4c 4c 29 3b 0a 2a 2a 20 73  ULL, NULL);.** s
372c0 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65  qlite3_temp_dire
372d0 63 74 6f 72 79 20 3d 20 73 71 6c 69 74 65 33 5f  ctory = sqlite3_
372e0 6d 70 72 69 6e 74 66 28 22 25 73 22 2c 20 7a 50  mprintf("%s", zP
372f0 61 74 68 42 75 66 29 3b 0a 2a 2a 20 3c 2f 70 72  athBuf);.** </pr
37300 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
37310 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e  */.SQLITE_EXTERN
37320 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 74   char *sqlite3_t
37330 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a  emp_directory;..
37340 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
37350 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64  Name Of The Fold
37360 65 72 20 48 6f 6c 64 69 6e 67 20 44 61 74 61 62  er Holding Datab
37370 61 73 65 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20  ase Files.**.** 
37380 5e 28 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c  ^(If this global
37390 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64   variable is mad
373a0 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20  e to point to a 
373b0 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a  string which is.
373c0 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61  ** the name of a
373d0 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20   folder (a.k.a. 
373e0 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e  directory), then
373f0 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20 66 69   all database fi
37400 6c 65 73 0a 2a 2a 20 73 70 65 63 69 66 69 65 64  les.** specified
37410 20 77 69 74 68 20 61 20 72 65 6c 61 74 69 76 65   with a relative
37420 20 70 61 74 68 6e 61 6d 65 20 61 6e 64 20 63 72   pathname and cr
37430 65 61 74 65 64 20 6f 72 20 61 63 63 65 73 73 65  eated or accesse
37440 64 20 62 79 0a 2a 2a 20 53 51 4c 69 74 65 20 77  d by.** SQLite w
37450 68 65 6e 20 75 73 69 6e 67 20 61 20 62 75 69 6c  hen using a buil
37460 74 2d 69 6e 20 77 69 6e 64 6f 77 73 20 5b 73 71  t-in windows [sq
37470 6c 69 74 65 33 5f 76 66 73 20 7c 20 56 46 53 5d  lite3_vfs | VFS]
37480 20 77 69 6c 6c 20 62 65 20 61 73 73 75 6d 65 64   will be assumed
37490 0a 2a 2a 20 74 6f 20 62 65 20 72 65 6c 61 74 69  .** to be relati
374a0 76 65 20 74 6f 20 74 68 61 74 20 64 69 72 65 63  ve to that direc
374b0 74 6f 72 79 2e 29 5e 20 5e 49 66 20 74 68 69 73  tory.)^ ^If this
374c0 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e   variable is a N
374d0 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c 20  ULL.** pointer, 
374e0 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75  then SQLite assu
374f0 6d 65 73 20 74 68 61 74 20 61 6c 6c 20 64 61 74  mes that all dat
37500 61 62 61 73 65 20 66 69 6c 65 73 20 73 70 65 63  abase files spec
37510 69 66 69 65 64 0a 2a 2a 20 77 69 74 68 20 61 20  ified.** with a 
37520 72 65 6c 61 74 69 76 65 20 70 61 74 68 6e 61 6d  relative pathnam
37530 65 20 61 72 65 20 72 65 6c 61 74 69 76 65 20 74  e are relative t
37540 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69  o the current di
37550 72 65 63 74 6f 72 79 0a 2a 2a 20 66 6f 72 20 74  rectory.** for t
37560 68 65 20 70 72 6f 63 65 73 73 2e 20 20 4f 6e 6c  he process.  Onl
37570 79 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46  y the windows VF
37580 53 20 6d 61 6b 65 73 20 75 73 65 20 6f 66 20 74  S makes use of t
37590 68 69 73 20 67 6c 6f 62 61 6c 0a 2a 2a 20 76 61  his global.** va
375a0 72 69 61 62 6c 65 3b 20 69 74 20 69 73 20 69 67  riable; it is ig
375b0 6e 6f 72 65 64 20 62 79 20 74 68 65 20 75 6e 69  nored by the uni
375c0 78 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 43 68 61  x VFS..**.** Cha
375d0 6e 67 69 6e 67 20 74 68 65 20 76 61 6c 75 65 20  nging the value 
375e0 6f 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  of this variable
375f0 20 77 68 69 6c 65 20 61 20 64 61 74 61 62 61 73   while a databas
37600 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 0a  e connection is.
37610 2a 2a 20 6f 70 65 6e 20 63 61 6e 20 72 65 73 75  ** open can resu
37620 6c 74 20 69 6e 20 61 20 63 6f 72 72 75 70 74 20  lt in a corrupt 
37630 64 61 74 61 62 61 73 65 2e 0a 2a 2a 0a 2a 2a 20  database..**.** 
37640 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
37650 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79  o read or modify
37660 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69   this variable i
37670 6e 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a  n more than one.
37680 2a 2a 20 74 68 72 65 61 64 20 61 74 20 61 20 74  ** thread at a t
37690 69 6d 65 2e 20 20 49 74 20 69 73 20 6e 6f 74 20  ime.  It is not 
376a0 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20  safe to read or 
376b0 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69  modify this vari
376c0 61 62 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61  able.** if a [da
376d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
376e0 6e 5d 20 69 73 20 62 65 69 6e 67 20 75 73 65 64  n] is being used
376f0 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
37700 65 20 69 6e 20 61 20 73 65 70 61 72 61 74 65 0a  e in a separate.
37710 2a 2a 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74  ** thread..** It
37720 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61   is intended tha
37730 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  t this variable 
37740 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61  be set once.** a
37750 73 20 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73  s part of proces
37760 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  s initialization
37770 20 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20   and before any 
37780 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
37790 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76  .** routines hav
377a0 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e  e been called an
377b0 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69  d that this vari
377c0 61 62 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63 68  able remain unch
377d0 61 6e 67 65 64 0a 2a 2a 20 74 68 65 72 65 61 66  anged.** thereaf
377e0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
377f0 5b 64 61 74 61 5f 73 74 6f 72 65 5f 64 69 72 65  [data_store_dire
37800 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d 61  ctory pragma] ma
37810 79 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61  y modify this va
37820 72 69 61 62 6c 65 20 61 6e 64 20 63 61 75 73 65  riable and cause
37830 0a 2a 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 20  .** it to point 
37840 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
37850 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
37860 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74  _malloc].  ^Furt
37870 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20  hermore,.** the 
37880 5b 64 61 74 61 5f 73 74 6f 72 65 5f 64 69 72 65  [data_store_dire
37890 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 6c  ctory pragma] al
378a0 77 61 79 73 20 61 73 73 75 6d 65 73 20 74 68 61  ways assumes tha
378b0 74 20 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20  t any string.** 
378c0 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62  that this variab
378d0 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20  le points to is 
378e0 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f  held in memory o
378f0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a  btained from .**
37900 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
37910 5d 20 61 6e 64 20 74 68 65 20 70 72 61 67 6d 61  ] and the pragma
37920 20 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20   may attempt to 
37930 66 72 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 79  free that memory
37940 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  .** using [sqlit
37950 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e  e3_free]..** Hen
37960 63 65 2c 20 69 66 20 74 68 69 73 20 76 61 72 69  ce, if this vari
37970 61 62 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 64  able is modified
37980 20 64 69 72 65 63 74 6c 79 2c 20 65 69 74 68 65   directly, eithe
37990 72 20 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a  r it should be.*
379a0 2a 20 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d  * made NULL or m
379b0 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
379c0 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
379d0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
379e0 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65  lloc].** or else
379f0 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 20   the use of the 
37a00 5b 64 61 74 61 5f 73 74 6f 72 65 5f 64 69 72 65  [data_store_dire
37a10 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 68  ctory pragma] sh
37a20 6f 75 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e  ould be avoided.
37a30 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52  .*/.SQLITE_EXTER
37a40 4e 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  N char *sqlite3_
37a50 64 61 74 61 5f 64 69 72 65 63 74 6f 72 79 3b 0a  data_directory;.
37a60 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
37a70 20 54 65 73 74 20 46 6f 72 20 41 75 74 6f 2d 43   Test For Auto-C
37a80 6f 6d 6d 69 74 20 4d 6f 64 65 0a 2a 2a 20 4b 45  ommit Mode.** KE
37a90 59 57 4f 52 44 53 3a 20 7b 61 75 74 6f 63 6f 6d  YWORDS: {autocom
37aa0 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20  mit mode}.**.** 
37ab0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74  ^The sqlite3_get
37ac0 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e  _autocommit() in
37ad0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
37ae0 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a  non-zero or.** z
37af0 65 72 6f 20 69 66 20 74 68 65 20 67 69 76 65 6e  ero if the given
37b00 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
37b10 74 69 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f  tion is or is no
37b20 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20  t in autocommit 
37b30 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74  mode,.** respect
37b40 69 76 65 6c 79 2e 20 20 5e 41 75 74 6f 63 6f 6d  ively.  ^Autocom
37b50 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62  mit mode is on b
37b60 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 5e 41  y default..** ^A
37b70 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69  utocommit mode i
37b80 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 61 20  s disabled by a 
37b90 5b 42 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e  [BEGIN] statemen
37ba0 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69  t..** ^Autocommi
37bb0 74 20 6d 6f 64 65 20 69 73 20 72 65 2d 65 6e 61  t mode is re-ena
37bc0 62 6c 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49  bled by a [COMMI
37bd0 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d  T] or [ROLLBACK]
37be0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61  ..**.** If certa
37bf0 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f  in kinds of erro
37c00 72 73 20 6f 63 63 75 72 20 6f 6e 20 61 20 73 74  rs occur on a st
37c10 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61  atement within a
37c20 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74   multi-statement
37c30 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  .** transaction 
37c40 28 65 72 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e  (errors includin
37c50 67 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c  g [SQLITE_FULL],
37c60 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c   [SQLITE_IOERR],
37c70 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  .** [SQLITE_NOME
37c80 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  M], [SQLITE_BUSY
37c90 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49  ], and [SQLITE_I
37ca0 4e 54 45 52 52 55 50 54 5d 29 20 74 68 65 6e 20  NTERRUPT]) then 
37cb0 74 68 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69  the.** transacti
37cc0 6f 6e 20 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c  on might be roll
37cd0 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69  ed back automati
37ce0 63 61 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79  cally.  The only
37cf0 20 77 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20   way to.** find 
37d00 6f 75 74 20 77 68 65 74 68 65 72 20 53 51 4c 69  out whether SQLi
37d10 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  te automatically
37d20 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68 65   rolled back the
37d30 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 61 66 74   transaction aft
37d40 65 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69  er.** an error i
37d50 73 20 74 6f 20 75 73 65 20 74 68 69 73 20 66 75  s to use this fu
37d60 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66  nction..**.** If
37d70 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20   another thread 
37d80 63 68 61 6e 67 65 73 20 74 68 65 20 61 75 74 6f  changes the auto
37d90 63 6f 6d 6d 69 74 20 73 74 61 74 75 73 20 6f 66  commit status of
37da0 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
37db0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c   connection whil
37dc0 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  e this routine i
37dd0 73 20 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20  s running, then 
37de0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
37df0 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64  .** is undefined
37e00 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
37e10 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28  _get_autocommit(
37e20 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
37e30 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64  * CAPI3REF: Find
37e40 20 54 68 65 20 44 61 74 61 62 61 73 65 20 48 61   The Database Ha
37e50 6e 64 6c 65 20 4f 66 20 41 20 50 72 65 70 61 72  ndle Of A Prepar
37e60 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a  ed Statement.**.
37e70 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
37e80 64 62 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72 66  db_handle interf
37e90 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
37ea0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
37eb0 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20  tion] handle.** 
37ec0 74 6f 20 77 68 69 63 68 20 61 20 5b 70 72 65 70  to which a [prep
37ed0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
37ee0 62 65 6c 6f 6e 67 73 2e 20 20 5e 54 68 65 20 5b  belongs.  ^The [
37ef0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
37f00 69 6f 6e 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64  ion].** returned
37f10 20 62 79 20 73 71 6c 69 74 65 33 5f 64 62 5f 68   by sqlite3_db_h
37f20 61 6e 64 6c 65 20 69 73 20 74 68 65 20 73 61 6d  andle is the sam
37f30 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
37f40 65 63 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20  ection].** that 
37f50 77 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72  was the first ar
37f60 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65  gument.** to the
37f70 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
37f80 65 5f 76 32 28 29 5d 20 63 61 6c 6c 20 28 6f 72  e_v2()] call (or
37f90 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 20 74   its variants) t
37fa0 68 61 74 20 77 61 73 20 75 73 65 64 20 74 6f 0a  hat was used to.
37fb0 2a 2a 20 63 72 65 61 74 65 20 74 68 65 20 73 74  ** create the st
37fc0 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 66  atement in the f
37fd0 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2f 0a 73  irst place..*/.s
37fe0 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f  qlite3 *sqlite3_
37ff0 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65  db_handle(sqlite
38000 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
38010 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 75 72   CAPI3REF: Retur
38020 6e 20 54 68 65 20 46 69 6c 65 6e 61 6d 65 20 46  n The Filename F
38030 6f 72 20 41 20 44 61 74 61 62 61 73 65 20 43 6f  or A Database Co
38040 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e  nnection.**.** ^
38050 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 66  The sqlite3_db_f
38060 69 6c 65 6e 61 6d 65 28 44 2c 4e 29 20 69 6e 74  ilename(D,N) int
38070 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
38080 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 69   pointer to a fi
38090 6c 65 6e 61 6d 65 0a 2a 2a 20 61 73 73 6f 63 69  lename.** associ
380a0 61 74 65 64 20 77 69 74 68 20 64 61 74 61 62 61  ated with databa
380b0 73 65 20 4e 20 6f 66 20 63 6f 6e 6e 65 63 74 69  se N of connecti
380c0 6f 6e 20 44 2e 20 20 5e 54 68 65 20 6d 61 69 6e  on D.  ^The main
380d0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a   database file.*
380e0 2a 20 68 61 73 20 74 68 65 20 6e 61 6d 65 20 22  * has the name "
380f0 6d 61 69 6e 22 2e 20 20 49 66 20 74 68 65 72 65  main".  If there
38100 20 69 73 20 6e 6f 20 61 74 74 61 63 68 65 64 20   is no attached 
38110 64 61 74 61 62 61 73 65 20 4e 20 6f 6e 20 74 68  database N on th
38120 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
38130 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 6f 72 20 69  nnection D, or i
38140 66 20 64 61 74 61 62 61 73 65 20 4e 20 69 73 20  f database N is 
38150 61 20 74 65 6d 70 6f 72 61 72 79 20 6f 72 20 69  a temporary or i
38160 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
38170 65 2c 20 74 68 65 6e 0a 2a 2a 20 61 20 4e 55 4c  e, then.** a NUL
38180 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
38190 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
381a0 65 20 66 69 6c 65 6e 61 6d 65 20 72 65 74 75 72  e filename retur
381b0 6e 65 64 20 62 79 20 74 68 69 73 20 66 75 6e 63  ned by this func
381c0 74 69 6f 6e 20 69 73 20 74 68 65 20 6f 75 74 70  tion is the outp
381d0 75 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 46 75  ut of the.** xFu
381e0 6c 6c 50 61 74 68 6e 61 6d 65 20 6d 65 74 68 6f  llPathname metho
381f0 64 20 6f 66 20 74 68 65 20 5b 56 46 53 5d 2e 20  d of the [VFS]. 
38200 20 5e 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73   ^In other words
38210 2c 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a  , the filename.*
38220 2a 20 77 69 6c 6c 20 62 65 20 61 6e 20 61 62 73  * will be an abs
38230 6f 6c 75 74 65 20 70 61 74 68 6e 61 6d 65 2c 20  olute pathname, 
38240 65 76 65 6e 20 69 66 20 74 68 65 20 66 69 6c 65  even if the file
38250 6e 61 6d 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20  name used.** to 
38260 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  open the databas
38270 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 77 61 73  e originally was
38280 20 61 20 55 52 49 20 6f 72 20 72 65 6c 61 74 69   a URI or relati
38290 76 65 20 70 61 74 68 6e 61 6d 65 2e 0a 2a 2f 0a  ve pathname..*/.
382a0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
382b0 74 65 33 5f 64 62 5f 66 69 6c 65 6e 61 6d 65 28  te3_db_filename(
382c0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 63 6f 6e  sqlite3 *db, con
382d0 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65  st char *zDbName
382e0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
382f0 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 69 66  EF: Determine if
38300 20 61 20 64 61 74 61 62 61 73 65 20 69 73 20 72   a database is r
38310 65 61 64 2d 6f 6e 6c 79 0a 2a 2a 0a 2a 2a 20 5e  ead-only.**.** ^
38320 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 72  The sqlite3_db_r
38330 65 61 64 6f 6e 6c 79 28 44 2c 4e 29 20 69 6e 74  eadonly(D,N) int
38340 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 31  erface returns 1
38350 20 69 66 20 74 68 65 20 64 61 74 61 62 61 73 65   if the database
38360 20 4e 0a 2a 2a 20 6f 66 20 63 6f 6e 6e 65 63 74   N.** of connect
38370 69 6f 6e 20 44 20 69 73 20 72 65 61 64 2d 6f 6e  ion D is read-on
38380 6c 79 2c 20 30 20 69 66 20 69 74 20 69 73 20 72  ly, 0 if it is r
38390 65 61 64 2f 77 72 69 74 65 2c 20 6f 72 20 2d 31  ead/write, or -1
383a0 20 69 66 20 4e 20 69 73 20 6e 6f 74 0a 2a 2a 20   if N is not.** 
383b0 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 64 61  the name of a da
383c0 74 61 62 61 73 65 20 6f 6e 20 63 6f 6e 6e 65 63  tabase on connec
383d0 74 69 6f 6e 20 44 2e 0a 2a 2f 0a 69 6e 74 20 73  tion D..*/.int s
383e0 71 6c 69 74 65 33 5f 64 62 5f 72 65 61 64 6f 6e  qlite3_db_readon
383f0 6c 79 28 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  ly(sqlite3 *db, 
38400 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e  const char *zDbN
38410 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ame);../*.** CAP
38420 49 33 52 45 46 3a 20 46 69 6e 64 20 74 68 65 20  I3REF: Find the 
38430 6e 65 78 74 20 70 72 65 70 61 72 65 64 20 73 74  next prepared st
38440 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54  atement.**.** ^T
38450 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65  his interface re
38460 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
38470 74 6f 20 74 68 65 20 6e 65 78 74 20 5b 70 72 65  to the next [pre
38480 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
38490 20 61 66 74 65 72 0a 2a 2a 20 70 53 74 6d 74 20   after.** pStmt 
384a0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
384b0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
384c0 6e 6e 65 63 74 69 6f 6e 5d 20 70 44 62 2e 20 20  nnection] pDb.  
384d0 5e 49 66 20 70 53 74 6d 74 20 69 73 20 4e 55 4c  ^If pStmt is NUL
384e0 4c 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 69  L.** then this i
384f0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
38500 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
38510 65 20 66 69 72 73 74 20 70 72 65 70 61 72 65 64  e first prepared
38520 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 61 73   statement.** as
38530 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
38540 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
38550 63 74 69 6f 6e 20 70 44 62 2e 20 20 5e 49 66 20  ction pDb.  ^If 
38560 6e 6f 20 70 72 65 70 61 72 65 64 20 73 74 61 74  no prepared stat
38570 65 6d 65 6e 74 0a 2a 2a 20 73 61 74 69 73 66 69  ement.** satisfi
38580 65 73 20 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e  es the condition
38590 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e  s of this routin
385a0 65 2c 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55  e, it returns NU
385b0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64  LL..**.** The [d
385c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
385d0 6f 6e 5d 20 70 6f 69 6e 74 65 72 20 44 20 69 6e  on] pointer D in
385e0 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73   a call to.** [s
385f0 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74  qlite3_next_stmt
38600 28 44 2c 53 29 5d 20 6d 75 73 74 20 72 65 66 65  (D,S)] must refe
38610 72 20 74 6f 20 61 6e 20 6f 70 65 6e 20 64 61 74  r to an open dat
38620 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
38630 69 6f 6e 20 61 6e 64 20 69 6e 20 70 61 72 74 69  ion and in parti
38640 63 75 6c 61 72 20 6d 75 73 74 20 6e 6f 74 20 62  cular must not b
38650 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
38660 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 73 74 6d  ..*/.sqlite3_stm
38670 74 20 2a 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f  t *sqlite3_next_
38680 73 74 6d 74 28 73 71 6c 69 74 65 33 20 2a 70 44  stmt(sqlite3 *pD
38690 62 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  b, sqlite3_stmt 
386a0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
386b0 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74  CAPI3REF: Commit
386c0 20 41 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f   And Rollback No
386d0 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62  tification Callb
386e0 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  acks.**.** ^The 
386f0 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68  sqlite3_commit_h
38700 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20  ook() interface 
38710 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
38720 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  back.** function
38730 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
38740 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61  henever a transa
38750 63 74 69 6f 6e 20 69 73 20 5b 43 4f 4d 4d 49 54  ction is [COMMIT
38760 20 7c 20 63 6f 6d 6d 69 74 74 65 64 5d 2e 0a 2a   | committed]..*
38770 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20  * ^Any callback 
38780 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75  set by a previou
38790 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  s call to sqlite
387a0 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a  3_commit_hook().
387b0 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ** for the same 
387c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  da