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

Artifact f801a04e1ebd1c7f958017661545422ada06b9ce:


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 69 73  3_close()].** is
23f0: 20 69 74 73 20 64 65 73 74 72 75 63 74 6f 72 2e   its destructor.
2400: 20 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79    There are many
2410: 20 6f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65   other interface
2420: 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73  s (such as.** [s
2430: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2440: 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  2()], [sqlite3_c
2450: 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
2460: 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
2470: 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
2480: 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74  )] to name but t
2490: 68 72 65 65 29 20 74 68 61 74 20 61 72 65 20 6d  hree) that are m
24a0: 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20  ethods on an.** 
24b0: 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a  sqlite3 object..
24c0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
24d0: 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65  t sqlite3 sqlite
24e0: 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  3;../*.** CAPI3R
24f0: 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67  EF: 64-Bit Integ
2500: 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57  er Types.** KEYW
2510: 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74  ORDS: sqlite_int
2520: 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  64 sqlite_uint64
2530: 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74  .**.** Because t
2540: 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73  here is no cross
2550: 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f  -platform way to
2560: 20 73 70 65 63 69 66 79 20 36 34 2d 62 69 74 20   specify 64-bit 
2570: 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a  integer types.**
2580: 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73   SQLite includes
2590: 20 74 79 70 65 64 65 66 73 20 66 6f 72 20 36 34   typedefs for 64
25a0: 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20  -bit signed and 
25b0: 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  unsigned integer
25c0: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  s..**.** The sql
25d0: 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73  ite3_int64 and s
25e0: 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72  qlite3_uint64 ar
25f0: 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20  e the preferred 
2600: 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73  type definitions
2610: 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f  ..** The sqlite_
2620: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
2630: 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 61 72  _uint64 types ar
2640: 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20  e supported for 
2650: 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d  backwards.** com
2660: 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e  patibility only.
2670: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2680: 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71  te3_int64 and sq
2690: 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73  lite_int64 types
26a0: 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67   can store integ
26b0: 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74  er values.** bet
26c0: 77 65 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36  ween -9223372036
26d0: 38 35 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39  854775808 and +9
26e0: 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38  2233720368547758
26f0: 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e  07 inclusive.  ^
2700: 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  The.** sqlite3_u
2710: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
2720: 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 63 61  _uint64 types ca
2730: 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20  n store integer 
2740: 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65  values .** betwe
2750: 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37  en 0 and +184467
2760: 34 34 30 37 33 37 30 39 35 35 31 36 31 35 20 69  44073709551615 i
2770: 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66  nclusive..*/.#if
2780: 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34  def SQLITE_INT64
2790: 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 20  _TYPE.  typedef 
27a0: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
27b0: 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  E sqlite_int64;.
27c0: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
27d0: 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ed SQLITE_INT64_
27e0: 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74  TYPE sqlite_uint
27f0: 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65  64;.#elif define
2800: 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64  d(_MSC_VER) || d
2810: 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44  efined(__BORLAND
2820: 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f  C__).  typedef _
2830: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e  _int64 sqlite_in
2840: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
2850: 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20  nsigned __int64 
2860: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
2870: 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c  else.  typedef l
2880: 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c  ong long int sql
2890: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70  ite_int64;.  typ
28a0: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f  edef unsigned lo
28b0: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69  ng long int sqli
28c0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69  te_uint64;.#endi
28d0: 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65  f.typedef sqlite
28e0: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69  _int64 sqlite3_i
28f0: 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71  nt64;.typedef sq
2900: 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69  lite_uint64 sqli
2910: 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a  te3_uint64;../*.
2920: 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20  ** If compiling 
2930: 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20  for a processor 
2940: 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74  that lacks float
2950: 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72  ing point suppor
2960: 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65  t,.** substitute
2970: 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f   integer for flo
2980: 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a  ating-point..*/.
2990: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d  #ifdef SQLITE_OM
29a0: 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e  IT_FLOATING_POIN
29b0: 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c  T.# define doubl
29c0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a  e sqlite3_int64.
29d0: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
29e0: 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20  PI3REF: Closing 
29f0: 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  A Database Conne
2a00: 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ction.**.** ^The
2a10: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2a20: 20 72 6f 75 74 69 6e 65 20 69 73 20 74 68 65 20   routine is the 
2a30: 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74  destructor for t
2a40: 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
2a50: 65 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74  ect..** ^Calls t
2a60: 6f 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  o sqlite3_close(
2a70: 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  ) return SQLITE_
2a80: 4f 4b 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74  OK if the [sqlit
2a90: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a  e3] object is.**
2aa0: 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65   successfully de
2ab0: 73 74 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20  stroyed and all 
2ac0: 61 73 73 6f 63 69 61 74 65 64 20 72 65 73 6f 75  associated resou
2ad0: 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f 63  rces are dealloc
2ae0: 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c  ated..**.** Appl
2af0: 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 5b 73  ications must [s
2b00: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20  qlite3_finalize 
2b10: 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20  | finalize] all 
2b20: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2b30: 65 6e 74 73 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  ents].** and [sq
2b40: 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65  lite3_blob_close
2b50: 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42   | close] all [B
2b60: 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 20 61 73 73  LOB handles] ass
2b70: 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20  ociated with.** 
2b80: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2b90: 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61 74  ject prior to at
2ba0: 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73  tempting to clos
2bb0: 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 20 20 5e  e the object.  ^
2bc0: 49 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6c  If.** sqlite3_cl
2bd0: 6f 73 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20  ose() is called 
2be0: 6f 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  on a [database c
2bf0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20  onnection] that 
2c00: 73 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75 74  still has.** out
2c10: 73 74 61 6e 64 69 6e 67 20 5b 70 72 65 70 61 72  standing [prepar
2c20: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 6f  ed statements] o
2c30: 72 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d  r [BLOB handles]
2c40: 2c 20 74 68 65 6e 20 69 74 20 72 65 74 75 72 6e  , then it return
2c50: 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 42 55 53 59  s.** SQLITE_BUSY
2c60: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 73 71 6c  ..**.** ^If [sql
2c70: 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 69 73  ite3_close()] is
2c80: 20 69 6e 76 6f 6b 65 64 20 77 68 69 6c 65 20 61   invoked while a
2c90: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
2ca0: 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61  open,.** the tra
2cb0: 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f  nsaction is auto
2cc0: 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64  matically rolled
2cd0: 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   back..**.** The
2ce0: 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   C parameter to 
2cf0: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43  [sqlite3_close(C
2d00: 29 5d 20 6d 75 73 74 20 62 65 20 65 69 74 68 65  )] must be eithe
2d10: 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e  r a NULL.** poin
2d20: 74 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74  ter or an [sqlit
2d30: 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74  e3] object point
2d40: 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  er obtained.** f
2d50: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  rom [sqlite3_ope
2d60: 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
2d70: 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20  pen16()], or.** 
2d80: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
2d90: 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65  ()], and not pre
2da0: 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a  viously closed..
2db0: 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69  ** ^Calling sqli
2dc0: 74 65 33 5f 63 6c 6f 73 65 28 29 20 77 69 74 68  te3_close() with
2dd0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
2de0: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 0a 2a  argument is a .*
2df0: 2a 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  * harmless no-op
2e00: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2e10: 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 20 2a  _close(sqlite3 *
2e20: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79  );../*.** The ty
2e30: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63  pe for a callbac
2e40: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  k function..** T
2e50: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e  his is legacy an
2e60: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49  d deprecated.  I
2e70: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f  t is included fo
2e80: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20  r historical.** 
2e90: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e  compatibility an
2ea0: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e  d is not documen
2eb0: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ted..*/.typedef 
2ec0: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61  int (*sqlite3_ca
2ed0: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
2ee0: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a  t,char**, char**
2ef0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2f00: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65  EF: One-Step Que
2f10: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74  ry Execution Int
2f20: 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54 68 65  erface.**.** The
2f30: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
2f40: 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63  interface is a c
2f50: 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70  onvenience wrapp
2f60: 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71  er around.** [sq
2f70: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2f80: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
2f90: 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ep()], and [sqli
2fa0: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c  te3_finalize()],
2fb0: 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20  .** that allows 
2fc0: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  an application t
2fd0: 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73  o run multiple s
2fe0: 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c  tatements of SQL
2ff0: 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69  .** without havi
3000: 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20  ng to use a lot 
3010: 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a  of C code. .**.*
3020: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
3030: 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20  xec() interface 
3040: 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  runs zero or mor
3050: 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c  e UTF-8 encoded,
3060: 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65  .** semicolon-se
3070: 70 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65  parate SQL state
3080: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74  ments passed int
3090: 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65  o its 2nd argume
30a0: 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f  nt,.** in the co
30b0: 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61  ntext of the [da
30c0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
30d0: 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20  n] passed in as 
30e0: 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d  its 1st.** argum
30f0: 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61  ent.  ^If the ca
3100: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
3110: 6f 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d  of the 3rd argum
3120: 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  ent to.** sqlite
3130: 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20  3_exec() is not 
3140: 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73  NULL, then it is
3150: 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63   invoked for eac
3160: 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20  h result row.** 
3170: 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68  coming out of th
3180: 65 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20  e evaluated SQL 
3190: 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68  statements.  ^Th
31a0: 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74  e 4th argument t
31b0: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
31c0: 63 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74  c() is relayed t
31d0: 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73  hrough to the 1s
31e0: 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61  t argument of ea
31f0: 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69  ch.** callback i
3200: 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20  nvocation.  ^If 
3210: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69  the callback poi
3220: 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  nter to sqlite3_
3230: 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c  exec().** is NUL
3240: 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62  L, then no callb
3250: 61 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f  ack is ever invo
3260: 6b 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72  ked and result r
3270: 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72  ows are.** ignor
3280: 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ed..**.** ^If an
3290: 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
32a0: 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74  ile evaluating t
32b0: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
32c0: 73 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a  s passed into.**
32d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c   sqlite3_exec(),
32e0: 20 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20   then execution 
32f0: 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73  of the current s
3300: 74 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61  tatement stops a
3310: 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  nd.** subsequent
3320: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
3330: 73 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68  skipped.  ^If th
3340: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
3350: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
3360: 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  ).** is not NULL
3370: 20 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20   then any error 
3380: 6d 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74  message is writt
3390: 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  en into memory o
33a0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
33b0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
33c0: 29 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61  )] and passed ba
33d0: 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35  ck through the 5
33e0: 74 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  th parameter..**
33f0: 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79   To avoid memory
3400: 20 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c   leaks, the appl
3410: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69  ication should i
3420: 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66  nvoke [sqlite3_f
3430: 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72  ree()].** on err
3440: 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
3450: 67 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f  gs returned thro
3460: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61  ugh the 5th para
3470: 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73  meter of.** of s
3480: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66  qlite3_exec() af
3490: 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65  ter the error me
34a0: 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
34b0: 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64  no longer needed
34c0: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68  ..** ^If the 5th
34d0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
34e0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
34f0: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20  not NULL and no 
3500: 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c  errors.** occur,
3510: 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78   then sqlite3_ex
3520: 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f  ec() sets the po
3530: 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68  inter in its 5th
3540: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
3550: 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74   NULL before ret
3560: 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49  urning..**.** ^I
3570: 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  f an sqlite3_exe
3580: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  c() callback ret
3590: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
35a0: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
35b0: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
35c0: 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52  urns SQLITE_ABOR
35d0: 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69  T without invoki
35e0: 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  ng the callback 
35f0: 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74  again and.** wit
3600: 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79  hout running any
3610: 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20   subsequent SQL 
3620: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
3630: 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d  * ^The 2nd argum
3640: 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
3650: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
3660: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ck function is t
3670: 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
3680: 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
3690: 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64  esult.  ^The 3rd
36a0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
36b0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
36c0: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  ** callback is a
36d0: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
36e0: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f  ers to strings o
36f0: 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72  btained as if fr
3700: 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  om.** [sqlite3_c
3710: 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f  olumn_text()], o
3720: 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75  ne for each colu
3730: 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d  mn.  ^If an elem
3740: 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75  ent of a.** resu
3750: 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74  lt row is NULL t
3760: 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
3770: 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69  nding string poi
3780: 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20  nter for the.** 
3790: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
37a0: 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c  allback is a NUL
37b0: 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65  L pointer.  ^The
37c0: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
37d0: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
37e0: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20  exec() callback 
37f0: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
3800: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
3810: 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a  gs where each.**
3820: 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74   entry represent
3830: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f  s the name of co
3840: 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75  rresponding resu
3850: 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74  lt column as obt
3860: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
3870: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
3880: 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  me()]..**.** ^If
3890: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
38a0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
38b0: 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ec() is a NULL p
38c0: 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65  ointer, a pointe
38d0: 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79  r.** to an empty
38e0: 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f   string, or a po
38f0: 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61  inter that conta
3900: 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70  ins only whitesp
3910: 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53  ace and/or .** S
3920: 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65  QL comments, the
3930: 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  n no SQL stateme
3940: 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65  nts are evaluate
3950: 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61  d and the databa
3960: 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61  se.** is not cha
3970: 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74  nged..**.** Rest
3980: 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20  rictions:.**.** 
3990: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
39a0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
39b0: 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 74 68  t insure that th
39c0: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20  e 1st parameter 
39d0: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
39e0: 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76  ).**      is a v
39f0: 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64  alid and open [d
3a00: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
3a10: 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  on]..** <li> The
3a20: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
3a30: 74 20 6e 6f 74 20 63 6c 6f 73 65 20 5b 64 61 74  t not close [dat
3a40: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3a50: 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a  ] specified by.*
3a60: 2a 20 20 20 20 20 20 74 68 65 20 31 73 74 20 70  *      the 1st p
3a70: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
3a80: 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65  te3_exec() while
3a90: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3aa0: 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c  is running..** <
3ab0: 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74  li> The applicat
3ac0: 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64  ion must not mod
3ad0: 69 66 79 20 74 68 65 20 53 51 4c 20 73 74 61 74  ify the SQL stat
3ae0: 65 6d 65 6e 74 20 74 65 78 74 20 70 61 73 73 65  ement text passe
3af0: 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74  d into.**      t
3b00: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
3b10: 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63   of sqlite3_exec
3b20: 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33  () while sqlite3
3b30: 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69  _exec() is runni
3b40: 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a  ng..** </ul>.*/.
3b50: 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63  int sqlite3_exec
3b60: 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20  (.  sqlite3*,   
3b70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3b80: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
3b90: 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  * An open databa
3ba0: 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  se */.  const ch
3bb0: 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20  ar *sql,        
3bc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3bd0: 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20     /* SQL to be 
3be0: 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69  evaluated */.  i
3bf0: 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76  nt (*callback)(v
3c00: 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c  oid*,int,char**,
3c10: 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c  char**),  /* Cal
3c20: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a  lback function *
3c30: 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20  /.  void *,     
3c40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3c50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
3c60: 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74  * 1st argument t
3c70: 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20  o callback */.  
3c80: 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20  char **errmsg   
3c90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3ca0: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72             /* Er
3cb0: 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20  ror msg written 
3cc0: 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  here */.);../*.*
3cd0: 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75  * CAPI3REF: Resu
3ce0: 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57  lt Codes.** KEYW
3cf0: 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20  ORDS: SQLITE_OK 
3d00: 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72  {error code} {er
3d10: 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45  ror codes}.** KE
3d20: 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20  YWORDS: {result 
3d30: 63 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f  code} {result co
3d40: 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20  des}.**.** Many 
3d50: 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73  SQLite functions
3d60: 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67   return an integ
3d70: 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66  er result code f
3d80: 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77  rom the set show
3d90: 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64  n.** here in ord
3da0: 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73  er to indicate s
3db0: 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72  uccess or failur
3dc0: 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72  e..**.** New err
3dd0: 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20  or codes may be 
3de0: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
3df0: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
3e00: 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  te..**.** See al
3e10: 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  so: [SQLITE_IOER
3e20: 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65  R_READ | extende
3e30: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2c  d result codes],
3e40: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 74 61  .** [sqlite3_vta
3e50: 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d  b_on_conflict()]
3e60: 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43   [SQLITE_ROLLBAC
3e70: 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  K | result codes
3e80: 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ]..*/.#define SQ
3e90: 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20  LITE_OK         
3ea0: 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73    0   /* Success
3eb0: 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a  ful result */./*
3ec0: 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72   beginning-of-er
3ed0: 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65  ror-codes */.#de
3ee0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f  fine SQLITE_ERRO
3ef0: 52 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20  R        1   /* 
3f00: 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73  SQL error or mis
3f10: 73 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f  sing database */
3f20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3f30: 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20  INTERNAL     2  
3f40: 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67   /* Internal log
3f50: 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69  ic error in SQLi
3f60: 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  te */.#define SQ
3f70: 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20  LITE_PERM       
3f80: 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20    3   /* Access 
3f90: 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65  permission denie
3fa0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
3fb0: 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20  ITE_ABORT       
3fc0: 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b   4   /* Callback
3fd0: 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74   routine request
3fe0: 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23  ed an abort */.#
3ff0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55  define SQLITE_BU
4000: 53 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f  SY         5   /
4010: 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66  * The database f
4020: 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f  ile is locked */
4030: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4040: 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20  LOCKED       6  
4050: 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74   /* A table in t
4060: 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c  he database is l
4070: 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ocked */.#define
4080: 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20   SQLITE_NOMEM   
4090: 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61       7   /* A ma
40a0: 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f  lloc() failed */
40b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
40c0: 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20  READONLY     8  
40d0: 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77   /* Attempt to w
40e0: 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20  rite a readonly 
40f0: 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66  database */.#def
4100: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52  ine SQLITE_INTER
4110: 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f  RUPT    9   /* O
4120: 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61  peration termina
4130: 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69  ted by sqlite3_i
4140: 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65  nterrupt()*/.#de
4150: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4160: 52 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20  R       10   /* 
4170: 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73  Some kind of dis
4180: 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75  k I/O error occu
4190: 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rred */.#define 
41a0: 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20  SQLITE_CORRUPT  
41b0: 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64     11   /* The d
41c0: 61 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61  atabase disk ima
41d0: 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20  ge is malformed 
41e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
41f0: 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32  E_NOTFOUND    12
4200: 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70     /* Unknown op
4210: 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33 5f  code in sqlite3_
4220: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a  file_control() *
4230: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4240: 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20  _FULL        13 
4250: 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66    /* Insertion f
4260: 61 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61  ailed because da
4270: 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a  tabase is full *
4280: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4290: 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20  _CANTOPEN    14 
42a0: 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f    /* Unable to o
42b0: 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  pen the database
42c0: 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65   file */.#define
42d0: 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c   SQLITE_PROTOCOL
42e0: 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74 61      15   /* Data
42f0: 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63  base lock protoc
4300: 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  ol error */.#def
4310: 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59  ine SQLITE_EMPTY
4320: 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44         16   /* D
4330: 61 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 79  atabase is empty
4340: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4350: 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31  TE_SCHEMA      1
4360: 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  7   /* The datab
4370: 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67  ase schema chang
4380: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4390: 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20  LITE_TOOBIG     
43a0: 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20   18   /* String 
43b0: 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20  or BLOB exceeds 
43c0: 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64  size limit */.#d
43d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
43e0: 53 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a  STRAINT  19   /*
43f0: 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f   Abort due to co
4400: 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
4410: 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  on */.#define SQ
4420: 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20  LITE_MISMATCH   
4430: 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79   20   /* Data ty
4440: 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23  pe mismatch */.#
4450: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49  define SQLITE_MI
4460: 53 55 53 45 20 20 20 20 20 20 32 31 20 20 20 2f  SUSE      21   /
4470: 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 69  * Library used i
4480: 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64  ncorrectly */.#d
4490: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c  efine SQLITE_NOL
44a0: 46 53 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a  FS       22   /*
44b0: 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 65   Uses OS feature
44c0: 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20  s not supported 
44d0: 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69  on host */.#defi
44e0: 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20  ne SQLITE_AUTH  
44f0: 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75        23   /* Au
4500: 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69  thorization deni
4510: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4520: 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20  LITE_FORMAT     
4530: 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61   24   /* Auxilia
4540: 72 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d  ry database form
4550: 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  at error */.#def
4560: 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45  ine SQLITE_RANGE
4570: 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32         25   /* 2
4580: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
4590: 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74  sqlite3_bind out
45a0: 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65   of range */.#de
45b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41  fine SQLITE_NOTA
45c0: 44 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20  DB      26   /* 
45d0: 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74  File opened that
45e0: 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61   is not a databa
45f0: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69  se file */.#defi
4600: 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20  ne SQLITE_ROW   
4610: 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71        100  /* sq
4620: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
4630: 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61   another row rea
4640: 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  dy */.#define SQ
4650: 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20  LITE_DONE       
4660: 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33   101  /* sqlite3
4670: 5f 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69  _step() has fini
4680: 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a  shed executing *
4690: 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f  /./* end-of-erro
46a0: 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a  r-codes */../*.*
46b0: 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 65  * CAPI3REF: Exte
46c0: 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65  nded Result Code
46d0: 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
46e0: 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
46f0: 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65  ode} {extended e
4700: 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b  rror codes}.** K
4710: 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64  EYWORDS: {extend
4720: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20  ed result code} 
4730: 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  {extended result
4740: 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e   codes}.**.** In
4750: 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e   its default con
4760: 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69  figuration, SQLi
4770: 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20  te API routines 
4780: 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36  return one of 26
4790: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c   integer.** [SQL
47a0: 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20  ITE_OK | result 
47b0: 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72  codes].  However
47c0: 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73  , experience has
47d0: 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79   shown that many
47e0: 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73   of.** these res
47f0: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f  ult codes are to
4800: 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64  o coarse-grained
4810: 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70  .  They do not p
4820: 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63  rovide as.** muc
4830: 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  h information ab
4840: 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20  out problems as 
4850: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68  programmers migh
4860: 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65  t like.  In an e
4870: 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72  ffort to.** addr
4880: 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20  ess this, newer 
4890: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
48a0: 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e  te (version 3.3.
48b0: 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63  8 and later) inc
48c0: 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20  lude.** support 
48d0: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72  for additional r
48e0: 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74  esult codes that
48f0: 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65   provide more de
4900: 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69  tailed informati
4910: 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f  on.** about erro
4920: 72 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64  rs. The extended
4930: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
4940: 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73  e enabled or dis
4950: 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65  abled.** on a pe
4960: 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  r database conne
4970: 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e  ction basis usin
4980: 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
4990: 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
49a0: 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a  t_codes()] API..
49b0: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68  **.** Some of th
49c0: 65 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65  e available exte
49d0: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
49e0: 73 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 72  s are listed her
49f0: 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78  e..** One may ex
4a00: 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20  pect the number 
4a10: 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  of extended resu
4a20: 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65  lt codes will be
4a30: 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20   expand.** over 
4a40: 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20  time.  Software 
4a50: 74 68 61 74 20 75 73 65 73 20 65 78 74 65 6e 64  that uses extend
4a60: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
4a70: 73 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a  should expect.**
4a80: 20 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75   to see new resu
4a90: 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75  lt codes in futu
4aa0: 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
4ab0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  QLite..**.** The
4ac0: 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c   SQLITE_OK resul
4ad0: 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65  t code will neve
4ae0: 72 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20  r be extended.  
4af0: 49 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a  It will always.*
4b00: 2a 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72  * be exactly zer
4b10: 6f 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  o..*/.#define SQ
4b20: 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20  LITE_IOERR_READ 
4b30: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
4b40: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c  LITE_IOERR | (1<
4b50: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4b60: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f  ITE_IOERR_SHORT_
4b70: 52 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c  READ        (SQL
4b80: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c  ITE_IOERR | (2<<
4b90: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4ba0: 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20  TE_IOERR_WRITE  
4bb0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4bc0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38  TE_IOERR | (3<<8
4bd0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4be0: 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20  E_IOERR_FSYNC   
4bf0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
4c00: 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29  E_IOERR | (4<<8)
4c10: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4c20: 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43  _IOERR_DIR_FSYNC
4c30: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4c40: 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29  _IOERR | (5<<8))
4c50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4c60: 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20  IOERR_TRUNCATE  
4c70: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4c80: 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a  IOERR | (6<<8)).
4c90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4ca0: 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20  OERR_FSTAT      
4cb0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4cc0: 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23  OERR | (7<<8)).#
4cd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4ce0: 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20  ERR_UNLOCK      
4cf0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4d00: 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64  ERR | (8<<8)).#d
4d10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4d20: 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20  RR_RDLOCK       
4d30: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4d40: 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65  RR | (9<<8)).#de
4d50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4d60: 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  R_DELETE        
4d70: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4d80: 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65  R | (10<<8)).#de
4d90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4da0: 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  R_BLOCKED       
4db0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4dc0: 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65  R | (11<<8)).#de
4dd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4de0: 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20  R_NOMEM         
4df0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4e00: 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65  R | (12<<8)).#de
4e10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4e20: 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20  R_ACCESS        
4e30: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4e40: 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65  R | (13<<8)).#de
4e50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4e60: 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c  R_CHECKRESERVEDL
4e70: 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52  OCK (SQLITE_IOER
4e80: 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65  R | (14<<8)).#de
4e90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4ea0: 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20  R_LOCK          
4eb0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4ec0: 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65  R | (15<<8)).#de
4ed0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4ee0: 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20  R_CLOSE         
4ef0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4f00: 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65  R | (16<<8)).#de
4f10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4f20: 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20  R_DIR_CLOSE     
4f30: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4f40: 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65  R | (17<<8)).#de
4f50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4f60: 52 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20  R_SHMOPEN       
4f70: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4f80: 52 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65  R | (18<<8)).#de
4f90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4fa0: 52 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20  R_SHMSIZE       
4fb0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4fc0: 52 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65  R | (19<<8)).#de
4fd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4fe0: 52 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20  R_SHMLOCK       
4ff0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5000: 52 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65  R | (20<<8)).#de
5010: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5020: 52 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20  R_SHMMAP        
5030: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5040: 52 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65  R | (21<<8)).#de
5050: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5060: 52 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20  R_SEEK          
5070: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5080: 52 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65  R | (22<<8)).#de
5090: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
50a0: 45 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20  ED_SHAREDCACHE  
50b0: 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b      (SQLITE_LOCK
50c0: 45 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64  ED |  (1<<8)).#d
50d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
50e0: 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20  Y_RECOVERY      
50f0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
5100: 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23  Y   |  (1<<8)).#
5110: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
5120: 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52  NTOPEN_NOTEMPDIR
5130: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
5140: 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29  NTOPEN | (1<<8))
5150: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5160: 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20  CANTOPEN_ISDIR  
5170: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5180: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38  CANTOPEN | (2<<8
5190: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
51a0: 45 5f 43 4f 52 52 55 50 54 5f 56 54 41 42 20 20  E_CORRUPT_VTAB  
51b0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
51c0: 45 5f 43 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c  E_CORRUPT | (1<<
51d0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
51e0: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f  TE_READONLY_RECO
51f0: 56 45 52 59 20 20 20 20 20 20 20 28 53 51 4c 49  VERY       (SQLI
5200: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31  TE_READONLY | (1
5210: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5220: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41  LITE_READONLY_CA
5230: 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20 28 53 51  NTLOCK       (SQ
5240: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20  LITE_READONLY | 
5250: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
5260: 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c  SQLITE_ABORT_ROL
5270: 4c 42 41 43 4b 20 20 20 20 20 20 20 20 20 20 28  LBACK          (
5280: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28  SQLITE_ABORT | (
5290: 32 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41  2<<8))../*.** CA
52a0: 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f  PI3REF: Flags Fo
52b0: 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72  r File Open Oper
52c0: 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ations.**.** The
52d0: 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 72  se bit values ar
52e0: 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75  e intended for u
52f0: 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64  se in the.** 3rd
5300: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
5310: 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  e [sqlite3_open_
5320: 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  v2()] interface 
5330: 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74  and.** in the 4t
5340: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
5350: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
5360: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a  xOpen] method..*
5370: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5380: 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20  _OPEN_READONLY  
5390: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
53a0: 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  1  /* Ok for sql
53b0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
53c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
53d0: 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20  _OPEN_READWRITE 
53e0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
53f0: 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  2  /* Ok for sql
5400: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
5410: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5420: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20  _OPEN_CREATE    
5430: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
5440: 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  4  /* Ok for sql
5450: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
5460: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5470: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
5480: 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30  OSE    0x0000000
5490: 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  8  /* VFS only *
54a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
54b0: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20  _OPEN_EXCLUSIVE 
54c0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31         0x0000001
54d0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
54e0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
54f0: 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20  _OPEN_AUTOPROXY 
5500: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32         0x0000002
5510: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
5520: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5530: 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20  _OPEN_URI       
5540: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34         0x0000004
5550: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
5560: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
5570: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5580: 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20  _OPEN_MEMORY    
5590: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38         0x0000008
55a0: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
55b0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
55c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
55d0: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20  _OPEN_MAIN_DB   
55e0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30         0x0000010
55f0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
5600: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5610: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20  _OPEN_TEMP_DB   
5620: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30         0x0000020
5630: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
5640: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5650: 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f  _OPEN_TRANSIENT_
5660: 44 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30  DB     0x0000040
5670: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
5680: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5690: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e  _OPEN_MAIN_JOURN
56a0: 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30  AL     0x0000080
56b0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
56c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
56d0: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e  _OPEN_TEMP_JOURN
56e0: 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30  AL     0x0000100
56f0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
5700: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5710: 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c  _OPEN_SUBJOURNAL
5720: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30         0x0000200
5730: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
5740: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5750: 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55  _OPEN_MASTER_JOU
5760: 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30  RNAL   0x0000400
5770: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
5780: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5790: 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20  _OPEN_NOMUTEX   
57a0: 20 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30         0x0000800
57b0: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
57c0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
57d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
57e0: 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20  _OPEN_FULLMUTEX 
57f0: 20 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30         0x0001000
5800: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
5810: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
5820: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5830: 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
5840: 45 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30  E      0x0002000
5850: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
5860: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
5870: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5880: 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
5890: 48 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30  HE     0x0004000
58a0: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
58b0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
58c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
58d0: 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20  _OPEN_WAL       
58e0: 20 20 20 20 20 20 20 30 78 30 30 30 38 30 30 30         0x0008000
58f0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
5900: 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20  /../* Reserved: 
5910: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5920: 20 20 20 20 20 20 20 20 30 78 30 30 46 30 30 30          0x00F000
5930: 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  00 */../*.** CAP
5940: 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68  I3REF: Device Ch
5950: 61 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a  aracteristics.**
5960: 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 43  .** The xDeviceC
5970: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d  haracteristics m
5980: 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71  ethod of the [sq
5990: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
59a0: 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75  ].** object retu
59b0: 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77  rns an integer w
59c0: 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72  hich is a vector
59d0: 20 6f 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a   of the these.**
59e0: 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72   bit values expr
59f0: 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61  essing I/O chara
5a00: 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68  cteristics of th
5a10: 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a  e mass storage.*
5a20: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f  * device that ho
5a30: 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61  lds the file tha
5a40: 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  t the [sqlite3_i
5a50: 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65  o_methods].** re
5a60: 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54  fers to..**.** T
5a70: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
5a80: 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20  ATOMIC property 
5a90: 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77  means that all w
5aa0: 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20  rites of.** any 
5ab0: 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e  size are atomic.
5ac0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
5ad0: 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c  AP_ATOMICnnn val
5ae0: 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74  ues.** mean that
5af0: 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b   writes of block
5b00: 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62  s that are nnn b
5b10: 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64  ytes in size and
5b20: 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20  .** are aligned 
5b30: 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68  to an address wh
5b40: 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ich is an intege
5b50: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a  r multiple of.**
5b60: 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e   nnn are atomic.
5b70: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
5b80: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76  AP_SAFE_APPEND v
5b90: 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68  alue means.** th
5ba0: 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20  at when data is 
5bb0: 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69  appended to a fi
5bc0: 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20  le, the data is 
5bd0: 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73  appended.** firs
5be0: 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20  t then the size 
5bf0: 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65  of the file is e
5c00: 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74  xtended, never t
5c10: 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20  he other.** way 
5c20: 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c  around.  The SQL
5c30: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
5c40: 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65  TIAL property me
5c50: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f  ans that.** info
5c60: 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74  rmation is writt
5c70: 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68  en to disk in th
5c80: 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20  e same order as 
5c90: 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69  calls.** to xWri
5ca0: 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54  te().  The SQLIT
5cb0: 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46  E_IOCAP_POWERSAF
5cc0: 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70  E_OVERWRITE prop
5cd0: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
5ce0: 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20  ** after reboot 
5cf0: 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73  following a cras
5d00: 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c  h or power loss,
5d10: 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20   the only bytes 
5d20: 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61  in a.** file tha
5d30: 74 20 77 65 72 65 20 77 72 69 74 74 65 6e 20 61  t were written a
5d40: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
5d50: 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61  n level might ha
5d60: 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e  ve changed.** an
5d70: 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20  d that adjacent 
5d80: 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65  bytes, even byte
5d90: 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  s within the sam
5da0: 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20  e sector are.** 
5db0: 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65  guaranteed to be
5dc0: 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2f 0a 23   unchanged..*/.#
5dd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5de0: 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20  CAP_ATOMIC      
5df0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
5e00: 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51  00001.#define SQ
5e10: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5e20: 43 35 31 32 20 20 20 20 20 20 20 20 20 20 20 20  C512            
5e30: 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65    0x00000002.#de
5e40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
5e50: 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20  P_ATOMIC1K      
5e60: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5e70: 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  004.#define SQLI
5e80: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32  TE_IOCAP_ATOMIC2
5e90: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
5ea0: 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69  0x00000008.#defi
5eb0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5ec0: 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20  ATOMIC4K        
5ed0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31         0x0000001
5ee0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
5ef0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20  _IOCAP_ATOMIC8K 
5f00: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
5f10: 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65  00000020.#define
5f20: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5f30: 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20 20  OMIC16K         
5f40: 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0a       0x00000040.
5f50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5f60: 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20  OCAP_ATOMIC32K  
5f70: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
5f80: 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53  000080.#define S
5f90: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5fa0: 49 43 36 34 4b 20 20 20 20 20 20 20 20 20 20 20  IC64K           
5fb0: 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 64     0x00000100.#d
5fc0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
5fd0: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20  AP_SAFE_APPEND  
5fe0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5ff0: 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0200.#define SQL
6000: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
6010: 54 49 41 4c 20 20 20 20 20 20 20 20 20 20 20 20  TIAL            
6020: 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65 66   0x00000400.#def
6030: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6040: 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45  _UNDELETABLE_WHE
6050: 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38  N_OPEN  0x000008
6060: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
6070: 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46  E_IOCAP_POWERSAF
6080: 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 30  E_OVERWRITE    0
6090: 78 30 30 30 30 31 30 30 30 0a 0a 2f 2a 0a 2a 2a  x00001000../*.**
60a0: 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20   CAPI3REF: File 
60b0: 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a  Locking Levels.*
60c0: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
60d0: 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e   one of these in
60e0: 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20  teger values as 
60f0: 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72  the second.** ar
6100: 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20  gument to calls 
6110: 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20  it makes to the 
6120: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c  xLock() and xUnl
6130: 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a  ock() methods.**
6140: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
6150: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
6160: 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ct..*/.#define S
6170: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20  QLITE_LOCK_NONE 
6180: 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69           0.#defi
6190: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  ne SQLITE_LOCK_S
61a0: 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23  HARED        1.#
61b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
61c0: 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20  CK_RESERVED     
61d0: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
61e0: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20  E_LOCK_PENDING  
61f0: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
6200: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
6210: 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a  SIVE     4../*.*
6220: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63  * CAPI3REF: Sync
6230: 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65  hronization Type
6240: 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65   Flags.**.** Whe
6250: 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73  n SQLite invokes
6260: 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74   the xSync() met
6270: 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71  hod of an.** [sq
6280: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
6290: 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73  ] object it uses
62a0: 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f   a combination o
62b0: 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67  f.** these integ
62c0: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65  er values as the
62d0: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
62e0: 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
62f0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54   SQLITE_SYNC_DAT
6300: 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73  AONLY flag is us
6310: 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61  ed, it means tha
6320: 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70  t the.** sync op
6330: 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65  eration only nee
6340: 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61  ds to flush data
6350: 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65   to mass storage
6360: 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f  .  Inode.** info
6370: 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74  rmation need not
6380: 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20   be flushed. If 
6390: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62  the lower four b
63a0: 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a  its of the flag.
63b0: 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f  ** equal SQLITE_
63c0: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61  SYNC_NORMAL, tha
63d0: 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e  t means to use n
63e0: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65  ormal fsync() se
63f0: 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74  mantics..** If t
6400: 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69  he lower four bi
6410: 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f  ts equal SQLITE_
6420: 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20  SYNC_FULL, that 
6430: 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20  means.** to use 
6440: 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66  Mac OS X style f
6450: 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20  ullsync instead 
6460: 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a  of fsync()..**.*
6470: 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65  * Do not confuse
6480: 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   the SQLITE_SYNC
6490: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49  _NORMAL and SQLI
64a0: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61  TE_SYNC_FULL fla
64b0: 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  gs.** with the [
64c0: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
64d0: 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b  us]=NORMAL and [
64e0: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
64f0: 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74  us]=FULL.** sett
6500: 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63  ings.  The [sync
6510: 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20  hronous pragma] 
6520: 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20  determines when 
6530: 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20  calls to the.** 
6540: 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64  xSync VFS method
6550: 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69   occur and appli
6560: 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72  es uniformly acr
6570: 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d  oss all platform
6580: 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  s..** The SQLITE
6590: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64  _SYNC_NORMAL and
65a0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
65b0: 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e  L flags determin
65c0: 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74  e how.** energet
65d0: 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f  ic or rigorous o
65e0: 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73  r forceful the s
65f0: 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61  ync operations a
6600: 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d  re and.** only m
6610: 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63 65  ake a difference
6620: 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20   on Mac OSX for 
6630: 74 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69  the default SQLi
6640: 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69  te code..** (Thi
6650: 72 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70  rd-party VFS imp
6660: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67  lementations mig
6670: 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65  ht also make the
6680: 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20   distinction.** 
6690: 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53  between SQLITE_S
66a0: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
66b0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c  QLITE_SYNC_FULL,
66c0: 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a   but among the.*
66d0: 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  * operating syst
66e0: 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70  ems natively sup
66f0: 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65  ported by SQLite
6700: 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a  , only Mac OSX.*
6710: 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20 74 68  * cares about th
6720: 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a  e difference.).*
6730: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6740: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20  _SYNC_NORMAL    
6750: 20 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 66      0x00002.#def
6760: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
6770: 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78  FULL          0x
6780: 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51  00003.#define SQ
6790: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
67a0: 4c 59 20 20 20 20 20 20 30 78 30 30 30 31 30 0a  LY      0x00010.
67b0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
67c0: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70   OS Interface Op
67d0: 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a  en File Handle.*
67e0: 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33  *.** An [sqlite3
67f0: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65  _file] object re
6800: 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e  presents an open
6810: 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a   file in the .**
6820: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20   [sqlite3_vfs | 
6830: 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79  OS interface lay
6840: 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c  er].  Individual
6850: 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a   OS interface.**
6860: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
6870: 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f   will.** want to
6880: 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f   subclass this o
6890: 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69  bject by appendi
68a0: 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69  ng additional fi
68b0: 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69  elds.** for thei
68c0: 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20  r own use.  The 
68d0: 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69  pMethods entry i
68e0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
68f0: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f  n.** [sqlite3_io
6900: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
6910: 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65   that defines me
6920: 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72  thods for perfor
6930: 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72  ming.** I/O oper
6940: 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70  ations on the op
6950: 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65  en file..*/.type
6960: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
6970: 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f  e3_file sqlite3_
6980: 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c  file;.struct sql
6990: 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f  ite3_file {.  co
69a0: 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74  nst struct sqlit
69b0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70  e3_io_methods *p
69c0: 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74  Methods;  /* Met
69d0: 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e  hods for an open
69e0: 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a   file */.};../*.
69f0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
6a00: 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56  Interface File V
6a10: 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f  irtual Methods O
6a20: 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72  bject.**.** Ever
6a30: 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79  y file opened by
6a40: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
6a50: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20  s.xOpen] method 
6a60: 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20  populates an.** 
6a70: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
6a80: 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20  bject (or, more 
6a90: 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63  commonly, a subc
6aa0: 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  lass of the.** [
6ab0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
6ac0: 6a 65 63 74 29 20 77 69 74 68 20 61 20 70 6f 69  ject) with a poi
6ad0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
6ae0: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
6af0: 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65  ct..** This obje
6b00: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d  ct defines the m
6b10: 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70  ethods used to p
6b20: 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f  erform various o
6b30: 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61  perations.** aga
6b40: 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69  inst the open fi
6b50: 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 62  le represented b
6b60: 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  y the [sqlite3_f
6b70: 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a  ile] object..**.
6b80: 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74  ** If the [sqlit
6b90: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65  e3_vfs.xOpen] me
6ba0: 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71  thod sets the sq
6bb0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
6bc0: 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20  ods element .** 
6bd0: 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  to a non-NULL po
6be0: 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  inter, then the 
6bf0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6c00: 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64  ds.xClose method
6c10: 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b  .** may be invok
6c20: 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b  ed even if the [
6c30: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
6c40: 6e 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61 74  n] reported that
6c50: 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65   it failed.  The
6c60: 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20  .** only way to 
6c70: 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74  prevent a call t
6c80: 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69  o xClose followi
6c90: 6e 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c  ng a failed [sql
6ca0: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a  ite3_vfs.xOpen].
6cb0: 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73  ** is for the [s
6cc0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
6cd0: 5d 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c  ] to set the sql
6ce0: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
6cf0: 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f  ds element.** to
6d00: 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   NULL..**.** The
6d10: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
6d20: 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20  to xSync may be 
6d30: 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53  one of [SQLITE_S
6d40: 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a  YNC_NORMAL] or.*
6d50: 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  * [SQLITE_SYNC_F
6d60: 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74  ULL].  The first
6d70: 20 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e   choice is the n
6d80: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a  ormal fsync()..*
6d90: 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f  * The second cho
6da0: 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20  ice is a Mac OS 
6db0: 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63  X style fullsync
6dc0: 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53  .  The [SQLITE_S
6dd0: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a  YNC_DATAONLY].**
6de0: 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65   flag may be ORe
6df0: 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65  d in to indicate
6e00: 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64   that only the d
6e10: 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a  ata of the file.
6e20: 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69  ** and not its i
6e30: 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65  node needs to be
6e40: 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   synced..**.** T
6e50: 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  he integer value
6e60: 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64  s to xLock() and
6e70: 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f   xUnlock() are o
6e80: 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  ne of.** <ul>.**
6e90: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
6ea0: 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69  CK_NONE],.** <li
6eb0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  > [SQLITE_LOCK_S
6ec0: 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  HARED],.** <li> 
6ed0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53  [SQLITE_LOCK_RES
6ee0: 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  ERVED],.** <li> 
6ef0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e  [SQLITE_LOCK_PEN
6f00: 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69  DING], or.** <li
6f10: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  > [SQLITE_LOCK_E
6f20: 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f  XCLUSIVE]..** </
6f30: 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69  ul>.** xLock() i
6f40: 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63  ncreases the loc
6f50: 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63  k. xUnlock() dec
6f60: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e  reases the lock.
6f70: 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65  .** The xCheckRe
6f80: 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74  servedLock() met
6f90: 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68  hod checks wheth
6fa0: 65 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20  er any database 
6fb0: 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65  connection,.** e
6fc0: 69 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72  ither in this pr
6fd0: 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65  ocess or in some
6fe0: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20   other process, 
6ff0: 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53  is holding a RES
7000: 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e  ERVED,.** PENDIN
7010: 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20  G, or EXCLUSIVE 
7020: 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65  lock on the file
7030: 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72  .  It returns tr
7040: 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20  ue.** if such a 
7050: 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20  lock exists and 
7060: 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e  false otherwise.
7070: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65  .**.** The xFile
7080: 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64  Control() method
7090: 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e   is a generic in
70a0: 74 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c  terface that all
70b0: 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46  ows custom.** VF
70c0: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
70d0: 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f  s to directly co
70e0: 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69  ntrol an open fi
70f0: 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  le using the.** 
7100: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
7110: 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61  ntrol()] interfa
7120: 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ce.  The second 
7130: 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73  "op" argument is
7140: 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f   an.** integer o
7150: 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72  pcode.  The thir
7160: 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  d argument is a 
7170: 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20  generic pointer 
7180: 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70  intended to.** p
7190: 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74  oint to a struct
71a0: 75 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e  ure that may con
71b0: 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f  tain arguments o
71c0: 72 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68  r space in which
71d0: 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74   to.** write ret
71e0: 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74  urn values.  Pot
71f0: 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20  ential uses for 
7200: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d  xFileControl() m
7210: 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74  ight be.** funct
7220: 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62  ions to enable b
7230: 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69  locking locks wi
7240: 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20  th timeouts, to 
7250: 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f  change the.** lo
7260: 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28  cking strategy (
7270: 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75  for example to u
7280: 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b  se dot-file lock
7290: 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a  s), to inquire.*
72a0: 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74  * about the stat
72b0: 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72  us of a lock, or
72c0: 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20   to break stale 
72d0: 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69  locks.  The SQLi
72e0: 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72  te.** core reser
72f0: 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20  ves all opcodes 
7300: 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f  less than 100 fo
7310: 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a  r its own use..*
7320: 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  * A [SQLITE_FCNT
7330: 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69  L_LOCKSTATE | li
7340: 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c  st of opcodes] l
7350: 65 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20  ess than 100 is 
7360: 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70  available..** Ap
7370: 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
7380: 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20  define a custom 
7390: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
73a0: 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f  hod should use o
73b0: 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65  pcodes.** greate
73c0: 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76  r than 100 to av
73d0: 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20  oid conflicts.  
73e0: 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
73f0: 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65  ons should.** re
7400: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54  turn [SQLITE_NOT
7410: 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20  FOUND] for file 
7420: 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20  control opcodes 
7430: 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74  that they do not
7440: 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a  .** recognize..*
7450: 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72  *.** The xSector
7460: 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65  Size() method re
7470: 74 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72  turns the sector
7480: 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20   size of the.** 
7490: 64 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65  device that unde
74a0: 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20  rlies the file. 
74b0: 20 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65   The sector size
74c0: 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d   is the.** minim
74d0: 75 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61  um write that ca
74e0: 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77  n be performed w
74f0: 69 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e  ithout disturbin
7500: 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73  g.** other bytes
7510: 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54   in the file.  T
7520: 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63  he xDeviceCharac
7530: 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d  teristics().** m
7540: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20  ethod returns a 
7550: 62 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72  bit vector descr
7560: 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20  ibing behaviors 
7570: 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c  of the.** underl
7580: 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a  ying device:.**.
7590: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
75a0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
75b0: 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  OMIC].** <li> [S
75c0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
75d0: 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC512].** <li> [
75e0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
75f0: 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC1K].** <li> [
7600: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7610: 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC2K].** <li> [
7620: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7630: 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC4K].** <li> [
7640: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7650: 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC8K].** <li> [
7660: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7670: 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC16K].** <li> 
7680: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
7690: 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC32K].** <li>
76a0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
76b0: 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC64K].** <li
76c0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
76d0: 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20  SAFE_APPEND].** 
76e0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
76f0: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a  AP_SEQUENTIAL].*
7700: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68  * </ul>.**.** Th
7710: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
7720: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d  TOMIC property m
7730: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72  eans that all wr
7740: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73  ites of.** any s
7750: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  ize are atomic. 
7760: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
7770: 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75  P_ATOMICnnn valu
7780: 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20  es.** mean that 
7790: 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73  writes of blocks
77a0: 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79   that are nnn by
77b0: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a  tes in size and.
77c0: 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74  ** are aligned t
77d0: 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69  o an address whi
77e0: 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ch is an integer
77f0: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20   multiple of.** 
7800: 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  nnn are atomic. 
7810: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
7820: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61  P_SAFE_APPEND va
7830: 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61  lue means.** tha
7840: 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61  t when data is a
7850: 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c  ppended to a fil
7860: 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61  e, the data is a
7870: 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74  ppended.** first
7880: 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f   then the size o
7890: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78  f the file is ex
78a0: 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68  tended, never th
78b0: 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61  e other.** way a
78c0: 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49  round.  The SQLI
78d0: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
78e0: 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61  IAL property mea
78f0: 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72  ns that.** infor
7900: 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65  mation is writte
7910: 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65  n to disk in the
7920: 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63   same order as c
7930: 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74  alls.** to xWrit
7940: 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52  e()..**.** If xR
7950: 65 61 64 28 29 20 72 65 74 75 72 6e 73 20 53 51  ead() returns SQ
7960: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54  LITE_IOERR_SHORT
7970: 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c  _READ it must al
7980: 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68  so fill.** in th
7990: 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e  e unread portion
79a0: 73 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20  s of the buffer 
79b0: 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56  with zeros.  A V
79c0: 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73  FS that.** fails
79d0: 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68   to zero-fill sh
79e0: 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68 74 20  ort reads might 
79f0: 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48  seem to work.  H
7a00: 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75  owever,.** failu
7a10: 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20  re to zero-fill 
7a20: 73 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c  short reads will
7a30: 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64   eventually lead
7a40: 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20   to.** database 
7a50: 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74  corruption..*/.t
7a60: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
7a70: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
7a80: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
7a90: 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ods;.struct sqli
7aa0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b  te3_io_methods {
7ab0: 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b  .  int iVersion;
7ac0: 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29  .  int (*xClose)
7ad0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
7ae0: 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28  .  int (*xRead)(
7af0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76  sqlite3_file*, v
7b00: 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20  oid*, int iAmt, 
7b10: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f  sqlite3_int64 iO
7b20: 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57  fst);.  int (*xW
7b30: 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69  rite)(sqlite3_fi
7b40: 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  le*, const void*
7b50: 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69  , int iAmt, sqli
7b60: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29  te3_int64 iOfst)
7b70: 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63  ;.  int (*xTrunc
7b80: 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ate)(sqlite3_fil
7b90: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
7ba0: 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28  4 size);.  int (
7bb0: 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xSync)(sqlite3_
7bc0: 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73  file*, int flags
7bd0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65  );.  int (*xFile
7be0: 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69  Size)(sqlite3_fi
7bf0: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  le*, sqlite3_int
7c00: 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e  64 *pSize);.  in
7c10: 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74  t (*xLock)(sqlit
7c20: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a  e3_file*, int);.
7c30: 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29    int (*xUnlock)
7c40: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
7c50: 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  int);.  int (*xC
7c60: 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b  heckReservedLock
7c70: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
7c80: 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a   int *pResOut);.
7c90: 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e    int (*xFileCon
7ca0: 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69  trol)(sqlite3_fi
7cb0: 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69  le*, int op, voi
7cc0: 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20  d *pArg);.  int 
7cd0: 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73  (*xSectorSize)(s
7ce0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
7cf0: 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68   int (*xDeviceCh
7d00: 61 72 61 63 74 65 72 69 73 74 69 63 73 29 28 73  aracteristics)(s
7d10: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
7d20: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76   /* Methods abov
7d30: 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20  e are valid for 
7d40: 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69  version 1 */.  i
7d50: 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71  nt (*xShmMap)(sq
7d60: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
7d70: 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20   iPg, int pgsz, 
7d80: 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69  int, void volati
7d90: 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  le**);.  int (*x
7da0: 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33  ShmLock)(sqlite3
7db0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73  _file*, int offs
7dc0: 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66  et, int n, int f
7dd0: 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a  lags);.  void (*
7de0: 78 53 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c  xShmBarrier)(sql
7df0: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69  ite3_file*);.  i
7e00: 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28  nt (*xShmUnmap)(
7e10: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
7e20: 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a  nt deleteFlag);.
7e30: 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f    /* Methods abo
7e40: 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72  ve are valid for
7e50: 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20   version 2 */.  
7e60: 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65  /* Additional me
7e70: 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64  thods may be add
7e80: 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
7e90: 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  eases */.};../*.
7ea0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61  ** CAPI3REF: Sta
7eb0: 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72  ndard File Contr
7ec0: 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a  ol Opcodes.**.**
7ed0: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
7ee0: 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63  onstants are opc
7ef0: 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69  odes for the xFi
7f00: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
7f10: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
7f20: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
7f30: 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74  object and for t
7f40: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
7f50: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69  _control()].** i
7f60: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
7f70: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
7f80: 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63  L_LOCKSTATE] opc
7f90: 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20  ode is used for 
7fa0: 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73  debugging.  This
7fb0: 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65  .** opcode cause
7fc0: 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  s the xFileContr
7fd0: 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69  ol method to wri
7fe0: 74 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 73  te the current s
7ff0: 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c  tate of.** the l
8000: 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c  ock (one of [SQL
8010: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20  ITE_LOCK_NONE], 
8020: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41  [SQLITE_LOCK_SHA
8030: 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  RED],.** [SQLITE
8040: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c  _LOCK_RESERVED],
8050: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45   [SQLITE_LOCK_PE
8060: 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49  NDING], or [SQLI
8070: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
8080: 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69  E]).** into an i
8090: 6e 74 65 67 65 72 20 74 68 61 74 20 74 68 65 20  nteger that the 
80a0: 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f  pArg argument po
80b0: 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61  ints to. This ca
80c0: 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75  pability.** is u
80d0: 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69  sed during testi
80e0: 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64  ng and only need
80f0: 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  s to be supporte
8100: 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45  d when SQLITE_TE
8110: 53 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64  ST.** is defined
8120: 2e 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  ..** <ul>.** <li
8130: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
8140: 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54  SIZE_HINT]].** T
8150: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
8160: 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f  _SIZE_HINT] opco
8170: 64 65 20 69 73 20 75 73 65 64 20 62 79 20 53 51  de is used by SQ
8180: 4c 69 74 65 20 74 6f 20 67 69 76 65 20 74 68 65  Lite to give the
8190: 20 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20   VFS.** layer a 
81a0: 68 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67  hint of how larg
81b0: 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  e the database f
81c0: 69 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f  ile will grow to
81d0: 20 62 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a   be during the.*
81e0: 2a 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61  * current transa
81f0: 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e  ction.  This hin
8200: 74 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74  t is not guarant
8210: 65 65 64 20 74 6f 20 62 65 20 61 63 63 75 72 61  eed to be accura
8220: 74 65 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20  te but it.** is 
8230: 6f 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68  often close.  Th
8240: 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53  e underlying VFS
8250: 20 6d 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f   might choose to
8260: 20 70 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74   preallocate dat
8270: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70  abase.** file sp
8280: 61 63 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69  ace based on thi
8290: 73 20 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20  s hint in order 
82a0: 74 6f 20 68 65 6c 70 20 77 72 69 74 65 73 20 74  to help writes t
82b0: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  o the database.*
82c0: 2a 20 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65  * file run faste
82d0: 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  r..**.** <li>[[S
82e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e  QLITE_FCNTL_CHUN
82f0: 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20  K_SIZE]].** The 
8300: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48  [SQLITE_FCNTL_CH
8310: 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65  UNK_SIZE] opcode
8320: 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 71 75   is used to requ
8330: 65 73 74 20 74 68 61 74 20 74 68 65 20 56 46 53  est that the VFS
8340: 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 20  .** extends and 
8350: 74 72 75 6e 63 61 74 65 73 20 74 68 65 20 64 61  truncates the da
8360: 74 61 62 61 73 65 20 66 69 6c 65 20 69 6e 20 63  tabase file in c
8370: 68 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 20  hunks of a size 
8380: 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20  specified.** by 
8390: 74 68 65 20 75 73 65 72 2e 20 54 68 65 20 66 6f  the user. The fo
83a0: 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  urth argument to
83b0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
83c0: 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64  ontrol()] should
83d0: 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e   .** point to an
83e0: 20 69 6e 74 65 67 65 72 20 28 74 79 70 65 20 69   integer (type i
83f0: 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  nt) containing t
8400: 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a  he new chunk-siz
8410: 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20  e to use.** for 
8420: 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61  the nominated da
8430: 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69  tabase. Allocati
8440: 6e 67 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  ng database file
8450: 20 73 70 61 63 65 20 69 6e 20 6c 61 72 67 65 0a   space in large.
8460: 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61 79 20 31  ** chunks (say 1
8470: 4d 42 20 61 74 20 61 20 74 69 6d 65 29 2c 20 6d  MB at a time), m
8480: 61 79 20 72 65 64 75 63 65 20 66 69 6c 65 2d 73  ay reduce file-s
8490: 79 73 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 74  ystem fragmentat
84a0: 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f  ion and.** impro
84b0: 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f  ve performance o
84c0: 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a  n some systems..
84d0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
84e0: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f  TE_FCNTL_FILE_PO
84f0: 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b  INTER]].** The [
8500: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c  SQLITE_FCNTL_FIL
8510: 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64  E_POINTER] opcod
8520: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74  e is used to obt
8530: 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  ain a pointer.**
8540: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
8550: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73  _file] object as
8560: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
8570: 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62  particular datab
8580: 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
8590: 6e 2e 20 20 53 65 65 20 74 68 65 20 5b 73 71 6c  n.  See the [sql
85a0: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
85b0: 6c 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69  l()] documentati
85c0: 6f 6e 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69  on for.** additi
85d0: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
85e0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
85f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f  LITE_FCNTL_SYNC_
8600: 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 5e 28 54  OMITTED]].** ^(T
8610: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
8620: 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 20 6f  _SYNC_OMITTED] o
8630: 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74  pcode is generat
8640: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79  ed internally by
8650: 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 73  .** SQLite and s
8660: 65 6e 74 20 74 6f 20 61 6c 6c 20 56 46 53 65 73  ent to all VFSes
8670: 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 61 20 63   in place of a c
8680: 61 6c 6c 20 74 6f 20 74 68 65 20 78 53 79 6e 63  all to the xSync
8690: 20 6d 65 74 68 6f 64 0a 2a 2a 20 77 68 65 6e 20   method.** when 
86a0: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
86b0: 6e 65 63 74 69 6f 6e 20 68 61 73 20 5b 50 52 41  nection has [PRA
86c0: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d  GMA synchronous]
86d0: 20 73 65 74 20 74 6f 20 4f 46 46 2e 29 5e 0a 2a   set to OFF.)^.*
86e0: 2a 20 53 6f 6d 65 20 73 70 65 63 69 61 6c 69 7a  * Some specializ
86f0: 65 64 20 56 46 53 65 73 20 6e 65 65 64 20 74 68  ed VFSes need th
8700: 69 73 20 73 69 67 6e 61 6c 20 69 6e 20 6f 72 64  is signal in ord
8710: 65 72 20 74 6f 20 6f 70 65 72 61 74 65 20 63 6f  er to operate co
8720: 72 72 65 63 74 6c 79 0a 2a 2a 20 77 68 65 6e 20  rrectly.** when 
8730: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e  [PRAGMA synchron
8740: 6f 75 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e  ous | PRAGMA syn
8750: 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 73  chronous=OFF] is
8760: 20 73 65 74 2c 20 62 75 74 20 6d 6f 73 74 20 0a   set, but most .
8770: 2a 2a 20 56 46 53 65 73 20 64 6f 20 6e 6f 74 20  ** VFSes do not 
8780: 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c  need this signal
8790: 20 61 6e 64 20 73 68 6f 75 6c 64 20 73 69 6c 65   and should sile
87a0: 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73  ntly ignore this
87b0: 20 6f 70 63 6f 64 65 2e 0a 2a 2a 20 41 70 70 6c   opcode..** Appl
87c0: 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
87d0: 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65  not call [sqlite
87e0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
87f0: 5d 20 77 69 74 68 20 74 68 69 73 0a 2a 2a 20 6f  ] with this.** o
8800: 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73  pcode as doing s
8810: 6f 20 6d 61 79 20 64 69 73 72 75 70 74 20 74 68  o may disrupt th
8820: 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74  e operation of t
8830: 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56  he specialized V
8840: 46 53 65 73 0a 2a 2a 20 74 68 61 74 20 64 6f 20  FSes.** that do 
8850: 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a  require it.  .**
8860: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
8870: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f  _FCNTL_WIN32_AV_
8880: 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20  RETRY]].** ^The 
8890: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49  [SQLITE_FCNTL_WI
88a0: 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70  N32_AV_RETRY] op
88b0: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
88c0: 63 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61  configure automa
88d0: 74 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75  tic.** retry cou
88e0: 6e 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c  nts and interval
88f0: 73 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69  s for certain di
8900: 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e  sk I/O operation
8910: 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e  s for the.** win
8920: 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72  dows [VFS] in or
8930: 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72  der to provide r
8940: 6f 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65  obustness in the
8950: 20 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20   presence of.** 
8960: 61 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72  anti-virus progr
8970: 61 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74  ams.  By default
8980: 2c 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46  , the windows VF
8990: 53 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c  S will retry fil
89a0: 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20  e read,.** file 
89b0: 77 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20  write, and file 
89c0: 64 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e  delete operation
89d0: 73 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73  s up to 10 times
89e0: 2c 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a  , with a delay.*
89f0: 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63  * of 25 millisec
8a00: 6f 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65 20  onds before the 
8a10: 66 69 72 73 74 20 72 65 74 72 79 20 61 6e 64 20  first retry and 
8a20: 77 69 74 68 20 74 68 65 20 64 65 6c 61 79 20 69  with the delay i
8a30: 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20  ncreasing.** by 
8a40: 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35  an additional 25
8a50: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69   milliseconds wi
8a60: 74 68 20 65 61 63 68 20 73 75 62 73 65 71 75 65  th each subseque
8a70: 6e 74 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a  nt retry.  This.
8a80: 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73  ** opcode allows
8a90: 20 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65   these two value
8aa0: 73 20 28 31 30 20 72 65 74 72 69 65 73 20 61 6e  s (10 retries an
8ab0: 64 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  d 25 millisecond
8ac0: 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74  s of delay).** t
8ad0: 6f 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20  o be adjusted.  
8ae0: 54 68 65 20 76 61 6c 75 65 73 20 61 72 65 20 63  The values are c
8af0: 68 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64  hanged for all d
8b00: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
8b10: 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68  ons.** within th
8b20: 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20  e same process. 
8b30: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
8b40: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
8b50: 20 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a   array of two.**
8b60: 20 69 6e 74 65 67 65 72 73 20 77 68 65 72 65 20   integers where 
8b70: 74 68 65 20 66 69 72 73 74 20 69 6e 74 65 67 65  the first intege
8b80: 72 20 69 20 74 68 65 20 6e 65 77 20 72 65 74 72  r i the new retr
8b90: 79 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20  y count and the 
8ba0: 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65  second.** intege
8bb0: 72 20 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20  r is the delay. 
8bc0: 20 49 66 20 65 69 74 68 65 72 20 69 6e 74 65 67   If either integ
8bd0: 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  er is negative, 
8be0: 74 68 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67  then the setting
8bf0: 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  .** is not chang
8c00: 65 64 20 62 75 74 20 69 6e 73 74 65 61 64 20 74  ed but instead t
8c10: 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f  he prior value o
8c20: 66 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 69  f that setting i
8c30: 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74  s written.** int
8c40: 6f 20 74 68 65 20 61 72 72 61 79 20 65 6e 74 72  o the array entr
8c50: 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20  y, allowing the 
8c60: 63 75 72 72 65 6e 74 20 72 65 74 72 79 20 73 65  current retry se
8c70: 74 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20  ttings to be.** 
8c80: 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54  interrogated.  T
8c90: 68 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d  he zDbName param
8ca0: 65 74 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e  eter is ignored.
8cb0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
8cc0: 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53  ITE_FCNTL_PERSIS
8cd0: 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20  T_WAL]].** ^The 
8ce0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45  [SQLITE_FCNTL_PE
8cf0: 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64  RSIST_WAL] opcod
8d00: 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74  e is used to set
8d10: 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a   or query the.**
8d20: 20 70 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c   persistent [WAL
8d30: 20 7c 20 57 72 69 74 65 20 41 68 65 61 64 20 4c   | Write Ahead L
8d40: 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79  og] setting.  By
8d50: 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75   default, the au
8d60: 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65  xiliary.** write
8d70: 20 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73   ahead log and s
8d80: 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c  hared memory fil
8d90: 65 73 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e  es used for tran
8da0: 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a  saction control.
8db0: 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63  ** are automatic
8dc0: 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65  ally deleted whe
8dd0: 6e 20 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e  n the latest con
8de0: 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64  nection to the d
8df0: 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65  atabase.** close
8e00: 73 2e 20 20 53 65 74 74 69 6e 67 20 70 65 72 73  s.  Setting pers
8e10: 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20  istent WAL mode 
8e20: 63 61 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c  causes those fil
8e30: 65 73 20 74 6f 20 70 65 72 73 69 73 74 20 61 66  es to persist af
8e40: 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50  ter.** close.  P
8e50: 65 72 73 69 73 74 69 6e 67 20 74 68 65 20 66 69  ersisting the fi
8e60: 6c 65 73 20 69 73 20 75 73 65 66 75 6c 20 77 68  les is useful wh
8e70: 65 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73  en other process
8e80: 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a  es that do not.*
8e90: 2a 20 68 61 76 65 20 77 72 69 74 65 20 70 65 72  * have write per
8ea0: 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64  mission on the d
8eb0: 69 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e  irectory contain
8ec0: 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65  ing the database
8ed0: 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f   file want.** to
8ee0: 20 72 65 61 64 20 74 68 65 20 64 61 74 61 62 61   read the databa
8ef0: 73 65 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20  se file, as the 
8f00: 57 41 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d  WAL and shared m
8f10: 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74  emory files must
8f20: 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64   exist.** in ord
8f30: 65 72 20 66 6f 72 20 74 68 65 20 64 61 74 61 62  er for the datab
8f40: 61 73 65 20 74 6f 20 62 65 20 72 65 61 64 61 62  ase to be readab
8f50: 6c 65 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20  le.  The fourth 
8f60: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
8f70: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
8f80: 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69  ntrol()] for thi
8f90: 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20  s opcode should 
8fa0: 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
8fb0: 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54  an integer..** T
8fc0: 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30  hat integer is 0
8fd0: 20 74 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73   to disable pers
8fe0: 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20  istent WAL mode 
8ff0: 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70  or 1 to enable p
9000: 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c  ersistent.** WAL
9010: 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69   mode.  If the i
9020: 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68  nteger is -1, th
9030: 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69  en it is overwri
9040: 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75  tten with the cu
9050: 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72  rrent.** WAL per
9060: 73 69 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67  sistence setting
9070: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
9080: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52  LITE_FCNTL_POWER
9090: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d  SAFE_OVERWRITE]]
90a0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
90b0: 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45  _FCNTL_POWERSAFE
90c0: 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f  _OVERWRITE] opco
90d0: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65  de is used to se
90e0: 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a  t or query the.*
90f0: 2a 20 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f  * persistent "po
9100: 77 65 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74  wersafe-overwrit
9110: 65 22 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74  e" or "PSOW" set
9120: 74 69 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20  ting.  The PSOW 
9130: 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72  setting.** deter
9140: 6d 69 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54  mines the [SQLIT
9150: 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46  E_IOCAP_POWERSAF
9160: 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74  E_OVERWRITE] bit
9170: 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69   of the.** xDevi
9180: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
9190: 73 20 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66  s methods. The f
91a0: 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
91b0: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  to.** [sqlite3_f
91c0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66  ile_control()] f
91d0: 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73  or this opcode s
91e0: 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74  hould be a point
91f0: 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
9200: 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65  ..** That intege
9210: 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  r is 0 to disabl
9220: 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f  e zero-damage mo
9230: 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c  de or 1 to enabl
9240: 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a  e zero-damage.**
9250: 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69   mode.  If the i
9260: 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68  nteger is -1, th
9270: 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69  en it is overwri
9280: 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75  tten with the cu
9290: 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61  rrent.** zero-da
92a0: 6d 61 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e  mage mode settin
92b0: 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  g..**.** <li>[[S
92c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
92d0: 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20  WRITE]].** ^The 
92e0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56  [SQLITE_FCNTL_OV
92f0: 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20  ERWRITE] opcode 
9300: 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51  is invoked by SQ
9310: 4c 69 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69  Lite after openi
9320: 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72  ng.** a write tr
9330: 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64  ansaction to ind
9340: 69 63 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65  icate that, unle
9350: 73 73 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20  ss it is rolled 
9360: 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a  back for some.**
9370: 20 72 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74   reason, the ent
9380: 69 72 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  ire database fil
9390: 65 20 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72  e will be overwr
93a0: 69 74 74 65 6e 20 62 79 20 74 68 65 20 63 75 72  itten by the cur
93b0: 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63  rent .** transac
93c0: 74 69 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73  tion. This is us
93d0: 65 64 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65  ed by VACUUM ope
93e0: 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c  rations..**.** <
93f0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
9400: 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e  L_VFSNAME]].** ^
9410: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
9420: 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64  L_VFSNAME] opcod
9430: 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
9440: 20 6f 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65   obtain the name
9450: 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53  s of.** all [VFS
9460: 65 73 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73  es] in the VFS s
9470: 74 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73  tack.  The names
9480: 20 61 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20   are of all VFS 
9490: 73 68 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a  shims and the.**
94a0: 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65   final bottom-le
94b0: 76 65 6c 20 56 46 53 20 61 72 65 20 77 72 69 74  vel VFS are writ
94c0: 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  ten into memory 
94d0: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a  obtained from .*
94e0: 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
94f0: 63 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73  c()] and the res
9500: 75 6c 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e  ult is stored in
9510: 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61   the char* varia
9520: 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  ble.** that the 
9530: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
9540: 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c   of [sqlite3_fil
9550: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69  e_control()] poi
9560: 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63  nts to..** The c
9570: 61 6c 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73  aller is respons
9580: 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67  ible for freeing
9590: 20 74 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e   the memory when
95a0: 20 64 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a   done.  As with.
95b0: 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74  ** all file-cont
95c0: 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65  rol actions, the
95d0: 72 65 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74  re is no guarant
95e0: 65 65 20 74 68 61 74 20 74 68 69 73 20 77 69 6c  ee that this wil
95f0: 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f  l actually.** do
9600: 20 61 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c   anything.  Call
9610: 65 72 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69  ers should initi
9620: 61 6c 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20  alize the char* 
9630: 76 61 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55  variable to a NU
9640: 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e  LL.** pointer in
9650: 20 63 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d   case this file-
9660: 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69  control is not i
9670: 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69  mplemented.  Thi
9680: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a  s file-control.*
9690: 2a 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f  * is intended fo
96a0: 72 20 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65  r diagnostic use
96b0: 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   only..**.** <li
96c0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
96d0: 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65  PRAGMA]].** ^Whe
96e0: 6e 65 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d  never a [PRAGMA]
96f0: 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61   statement is pa
9700: 72 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45  rsed, an [SQLITE
9710: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a  _FCNTL_PRAGMA] .
9720: 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  ** file control 
9730: 69 73 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f  is sent to the o
9740: 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  pen [sqlite3_fil
9750: 65 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73  e] object corres
9760: 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68  ponding.** to th
9770: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
9780: 74 6f 20 77 68 69 63 68 20 74 68 65 20 70 72 61  to which the pra
9790: 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65  gma statement re
97a0: 66 65 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d  fers. ^The argum
97b0: 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53  ent.** to the [S
97c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
97d0: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  MA] file control
97e0: 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a   is an array of.
97f0: 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73  ** pointers to s
9800: 74 72 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20  trings (char**) 
9810: 69 6e 20 77 68 69 63 68 20 74 68 65 20 73 65 63  in which the sec
9820: 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74  ond element of t
9830: 68 65 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74  he array.** is t
9840: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70  he name of the p
9850: 72 61 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68  ragma and the th
9860: 69 72 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74  ird element is t
9870: 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  he argument to t
9880: 68 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20  he.** pragma or 
9890: 4e 55 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67  NULL if the prag
98a0: 6d 61 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65  ma has no argume
98b0: 6e 74 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65  nt.  ^The handle
98c0: 72 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c  r for an.** [SQL
98d0: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
98e0: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63  ] file control c
98f0: 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61  an optionally ma
9900: 6b 65 20 74 68 65 20 66 69 72 73 74 20 65 6c 65  ke the first ele
9910: 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63  ment.** of the c
9920: 68 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70  har** argument p
9930: 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67  oint to a string
9940: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
9950: 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
9960: 29 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75  )].** or the equ
9970: 69 76 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74  ivalent and that
9980: 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63   string will bec
9990: 6f 6d 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f  ome the result o
99a0: 66 20 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a  f the pragma or.
99b0: 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  ** the error mes
99c0: 73 61 67 65 20 69 66 20 74 68 65 20 70 72 61 67  sage if the prag
99d0: 6d 61 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68  ma fails. ^If th
99e0: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e  e.** [SQLITE_FCN
99f0: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20  TL_PRAGMA] file 
9a00: 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20  control returns 
9a10: 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44  [SQLITE_NOTFOUND
9a20: 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a  ], then normal .
9a30: 2a 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63  ** [PRAGMA] proc
9a40: 65 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73  essing continues
9a50: 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49  .  ^If the [SQLI
9a60: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
9a70: 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  .** file control
9a80: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
9a90: 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70  _OK], then the p
9aa0: 61 72 73 65 72 20 61 73 73 75 6d 65 73 20 74 68  arser assumes th
9ab0: 61 74 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61  at the.** VFS ha
9ac0: 73 20 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52  s handled the PR
9ad0: 41 47 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20  AGMA itself and 
9ae0: 74 68 65 20 70 61 72 73 65 72 20 67 65 6e 65 72  the parser gener
9af0: 61 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20  ates a no-op.** 
9b00: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
9b10: 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51  nt.  ^If the [SQ
9b20: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
9b30: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
9b40: 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72  returns.** any r
9b50: 65 73 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72  esult code other
9b60: 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b   than [SQLITE_OK
9b70: 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54  ] or [SQLITE_NOT
9b80: 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61  FOUND], that mea
9b90: 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56  ns.** that the V
9ba0: 46 53 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61  FS encountered a
9bb0: 6e 20 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61  n error while ha
9bc0: 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47  ndling the [PRAG
9bd0: 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63  MA] and the.** c
9be0: 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68  ompilation of th
9bf0: 65 20 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77  e PRAGMA fails w
9c00: 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e  ith an error.  ^
9c10: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
9c20: 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c  L_PRAGMA].** fil
9c30: 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73  e control occurs
9c40: 20 61 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e   at the beginnin
9c50: 67 20 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74  g of pragma stat
9c60: 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61  ement analysis a
9c70: 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61  nd so.** it is a
9c80: 62 6c 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20  ble to override 
9c90: 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41  built-in [PRAGMA
9ca0: 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  ] statements..**
9cb0: 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </ul>.*/.#defin
9cc0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c  e SQLITE_FCNTL_L
9cd0: 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20  OCKSTATE        
9ce0: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
9cf0: 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b   SQLITE_GET_LOCK
9d00: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20  PROXYFILE       
9d10: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
9d20: 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50  SQLITE_SET_LOCKP
9d30: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 20  ROXYFILE        
9d40: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
9d50: 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f  QLITE_LAST_ERRNO
9d60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
9d70: 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
9d80: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f  LITE_FCNTL_SIZE_
9d90: 48 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20  HINT            
9da0: 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c     5.#define SQL
9db0: 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f  ITE_FCNTL_CHUNK_
9dc0: 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20  SIZE            
9dd0: 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    6.#define SQLI
9de0: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f  TE_FCNTL_FILE_PO
9df0: 49 4e 54 45 52 20 20 20 20 20 20 20 20 20 20 20  INTER           
9e00: 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   7.#define SQLIT
9e10: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49  E_FCNTL_SYNC_OMI
9e20: 54 54 45 44 20 20 20 20 20 20 20 20 20 20 20 20  TTED            
9e30: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
9e40: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f  _FCNTL_WIN32_AV_
9e50: 52 45 54 52 59 20 20 20 20 20 20 20 20 20 20 39  RETRY          9
9e60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9e70: 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41  FCNTL_PERSIST_WA
9e80: 4c 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a  L            10.
9e90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
9ea0: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 20 20  CNTL_OVERWRITE  
9eb0: 20 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 23              11.#
9ec0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
9ed0: 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20 20  NTL_VFSNAME     
9ee0: 20 20 20 20 20 20 20 20 20 20 20 31 32 0a 23 64             12.#d
9ef0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
9f00: 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  TL_POWERSAFE_OVE
9f10: 52 57 52 49 54 45 20 20 20 20 31 33 0a 23 64 65  RWRITE    13.#de
9f20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
9f30: 4c 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20  L_PRAGMA        
9f40: 20 20 20 20 20 20 20 20 20 31 34 0a 0a 2f 2a 0a           14../*.
9f50: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74  ** CAPI3REF: Mut
9f60: 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20  ex Handle.**.** 
9f70: 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65  The mutex module
9f80: 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64   within SQLite d
9f90: 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f  efines [sqlite3_
9fa0: 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a  mutex] to be an.
9fb0: 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70 65  ** abstract type
9fc0: 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a   for a mutex obj
9fd0: 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65  ect.  The SQLite
9fe0: 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b   core never look
9ff0: 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65  s.** at the inte
a000: 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74  rnal representat
a010: 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  ion of an [sqlit
a020: 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f  e3_mutex].  It o
a030: 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74  nly.** deals wit
a040: 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68  h pointers to th
a050: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
a060: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
a070: 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65 61  Mutexes are crea
a080: 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
a090: 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
a0a0: 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  ]..*/.typedef st
a0b0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74  ruct sqlite3_mut
a0c0: 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ex sqlite3_mutex
a0d0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
a0e0: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
a0f0: 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20  Object.**.** An 
a100: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
a110: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
a120: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
a130: 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
a140: 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63  .** the SQLite c
a150: 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65  ore and the unde
a160: 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67  rlying operating
a170: 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76   system.  The "v
a180: 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  fs".** in the na
a190: 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74  me of the object
a1a0: 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72   stands for "vir
a1b0: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
a1c0: 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b  ".  See.** the [
a1d0: 56 46 53 20 7c 20 56 46 53 20 64 6f 63 75 6d 65  VFS | VFS docume
a1e0: 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72  ntation] for fur
a1f0: 74 68 65 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  ther information
a200: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75  ..**.** The valu
a210: 65 20 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f  e of the iVersio
a220: 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69  n field is initi
a230: 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62  ally 1 but may b
a240: 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66  e larger in.** f
a250: 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
a260: 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74  f SQLite.  Addit
a270: 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79  ional fields may
a280: 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20   be appended to 
a290: 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77  this.** object w
a2a0: 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e  hen the iVersion
a2b0: 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61   value is increa
a2c0: 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20  sed.  Note that 
a2d0: 74 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a  the structure.**
a2e0: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
a2f0: 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67  vfs object chang
a300: 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61  es in the transa
a310: 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a  ction between.**
a320: 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
a330: 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20  3.5.9 and 3.6.0 
a340: 61 6e 64 20 79 65 74 20 74 68 65 20 69 56 65 72  and yet the iVer
a350: 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e  sion field was n
a360: 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a  ot.** modified..
a370: 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69  **.** The szOsFi
a380: 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 20  le field is the 
a390: 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63  size of the subc
a3a0: 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f  lassed [sqlite3_
a3b0: 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75  file].** structu
a3c0: 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73 20  re used by this 
a3d0: 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65  VFS.  mxPathname
a3e0: 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20   is the maximum 
a3f0: 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70  length of.** a p
a400: 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20  athname in this 
a410: 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73  VFS..**.** Regis
a420: 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66  tered sqlite3_vf
a430: 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65  s objects are ke
a440: 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c  pt on a linked l
a450: 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a  ist formed by.**
a460: 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74   the pNext point
a470: 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  er.  The [sqlite
a480: 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29  3_vfs_register()
a490: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
a4a0: 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72  3_vfs_unregister
a4b0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ()] interfaces m
a4c0: 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a  anage this list.
a4d0: 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73  ** in a thread-s
a4e0: 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73  afe way.  The [s
a4f0: 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28  qlite3_vfs_find(
a500: 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  )] interface.** 
a510: 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 73  searches the lis
a520: 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65 20  t.  Neither the 
a530: 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65  application code
a540: 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20   nor the VFS.** 
a550: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73  implementation s
a560: 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e  hould use the pN
a570: 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ext pointer..**.
a580: 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 65  ** The pNext fie
a590: 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66  ld is the only f
a5a0: 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69  ield in the sqli
a5b0: 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63  te3_vfs.** struc
a5c0: 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74 65  ture that SQLite
a5d0: 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66   will ever modif
a5e0: 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  y.  SQLite will 
a5f0: 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f  only access.** o
a600: 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69  r modify this fi
a610: 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e  eld while holdin
a620: 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 73  g a particular s
a630: 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20  tatic mutex..** 
a640: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
a650: 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64  should never mod
a660: 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74  ify anything wit
a670: 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hin the sqlite3_
a680: 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e  vfs.** object on
a690: 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61  ce the object ha
a6a0: 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72 65  s been registere
a6b0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61  d..**.** The zNa
a6c0: 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74  me field holds t
a6d0: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56  he name of the V
a6e0: 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20  FS module.  The 
a6f0: 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20  name must.** be 
a700: 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c  unique across al
a710: 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a  l VFS modules..*
a720: 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76  *.** [[sqlite3_v
a730: 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53  fs.xOpen]].** ^S
a740: 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73  QLite guarantees
a750: 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e   that the zFilen
a760: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ame parameter to
a770: 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74   xOpen.** is eit
a780: 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  her a NULL point
a790: 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74  er or string obt
a7a0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46  ained.** from xF
a7b0: 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69  ullPathname() wi
a7c0: 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73  th an optional s
a7d0: 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20  uffix added..** 
a7e0: 5e 49 66 20 61 20 73 75 66 66 69 78 20 69 73 20  ^If a suffix is 
a7f0: 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69  added to the zFi
a800: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
a810: 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e  , it will.** con
a820: 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65  sist of a single
a830: 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 20 66   "-" character f
a840: 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f  ollowed by no mo
a850: 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c  re than.** 11 al
a860: 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f  phanumeric and/o
a870: 72 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 73  r "-" characters
a880: 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72  ..** ^SQLite fur
a890: 74 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20  ther guarantees 
a8a0: 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69  that.** the stri
a8b0: 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64  ng will be valid
a8c0: 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75   and unchanged u
a8d0: 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73  ntil xClose() is
a8e0: 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61  .** called. Beca
a8f0: 75 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69  use of the previ
a900: 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a  ous sentence,.**
a910: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
a920: 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73  le] can safely s
a930: 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74  tore a pointer t
a940: 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d  o the.** filenam
a950: 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f  e if it needs to
a960: 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69   remember the fi
a970: 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20  lename for some 
a980: 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68  reason..** If th
a990: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
a9a0: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69  meter to xOpen i
a9b0: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
a9c0: 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d   then xOpen.** m
a9d0: 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f  ust invent its o
a9e0: 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d  wn temporary nam
a9f0: 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20  e for the file. 
aa00: 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a   ^Whenever the .
aa10: 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72  ** xFilename par
aa20: 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69  ameter is NULL i
aa30: 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74  t will also be t
aa40: 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
aa50: 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65  .** flags parame
aa60: 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65  ter will include
aa70: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
aa80: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a  LETEONCLOSE]..**
aa90: 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72  .** The flags ar
aaa0: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28  gument to xOpen(
aab0: 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62  ) includes all b
aac0: 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68  its set in.** th
aad0: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
aae0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
aaf0: 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20  n_v2()].  Or if 
ab00: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
ab10: 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
ab20: 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65  open16()] is use
ab30: 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e  d, then flags in
ab40: 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a  cludes at least.
ab50: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
ab60: 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
ab70: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
ab80: 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28  ]. .** If xOpen(
ab90: 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72  ) opens a file r
aba0: 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74  ead-only then it
abb0: 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73   sets *pOutFlags
abc0: 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b   to.** include [
abd0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
abe0: 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69  ONLY].  Other bi
abf0: 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73  ts in *pOutFlags
ac00: 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a   may be set..**.
ac10: 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c  ** ^(SQLite will
ac20: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
ac30: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
ac40: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
ac50: 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70  n().** call, dep
ac60: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62  ending on the ob
ac70: 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65  ject being opene
ac80: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  d:.**.** <ul>.**
ac90: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
aca0: 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20  PEN_MAIN_DB].** 
acb0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
acc0: 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d  EN_MAIN_JOURNAL]
acd0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
ace0: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a  E_OPEN_TEMP_DB].
acf0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
ad00: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e  _OPEN_TEMP_JOURN
ad10: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
ad20: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49  LITE_OPEN_TRANSI
ad30: 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  ENT_DB].** <li> 
ad40: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55   [SQLITE_OPEN_SU
ad50: 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  BJOURNAL].** <li
ad60: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
ad70: 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a  MASTER_JOURNAL].
ad80: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
ad90: 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f  _OPEN_WAL].** </
ada0: 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ul>)^.**.** The 
adb0: 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65  file I/O impleme
adc0: 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20  ntation can use 
add0: 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20  the object type 
ade0: 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e  flags to.** chan
adf0: 67 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65  ge the way it de
ae00: 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20  als with files. 
ae10: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e   For example, an
ae20: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
ae30: 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61  that does not ca
ae40: 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72  re about crash r
ae50: 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62  ecovery or rollb
ae60: 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a  ack might make.*
ae70: 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20  * the open of a 
ae80: 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e  journal file a n
ae90: 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f  o-op.  Writes to
aea0: 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f   this journal wo
aeb0: 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e  uld.** also be n
aec0: 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61  o-ops, and any a
aed0: 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74  ttempt to read t
aee0: 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64  he journal would
aef0: 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54   return.** SQLIT
af00: 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65  E_IOERR.  Or the
af10: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
af20: 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20  might recognize 
af30: 74 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a  that a database.
af40: 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20  ** file will be 
af50: 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e  doing page-align
af60: 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20  ed sector reads 
af70: 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20  and writes in a 
af80: 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20  random.** order 
af90: 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49  and set up its I
afa0: 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63  /O subsystem acc
afb0: 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ordingly..**.** 
afc0: 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73  SQLite might als
afd0: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
afe0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
aff0: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65   to the xOpen me
b000: 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  thod:.**.** <ul>
b010: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
b020: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
b030: 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  OSE].** <li> [SQ
b040: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
b050: 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  IVE].** </ul>.**
b060: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
b070: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
b080: 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74  SE] flag means t
b090: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62  he file should b
b0a0: 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65  e.** deleted whe
b0b0: 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20  n it is closed. 
b0c0: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50   ^The [SQLITE_OP
b0d0: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
b0e0: 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74  ].** will be set
b0f0: 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61   for TEMP databa
b100: 73 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f  ses and their jo
b110: 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e  urnals, transien
b120: 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20  t.** databases, 
b130: 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e  and subjournals.
b140: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  .**.** ^The [SQL
b150: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
b160: 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61  VE] flag is alwa
b170: 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75  ys used in conju
b180: 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74  nction.** with t
b190: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
b1a0: 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68  CREATE] flag, wh
b1b0: 69 63 68 20 61 72 65 20 62 6f 74 68 20 64 69 72  ich are both dir
b1c0: 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f  ectly.** analogo
b1d0: 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c  us to the O_EXCL
b1e0: 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61   and O_CREAT fla
b1f0: 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20  gs of the POSIX 
b200: 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20  open().** API.  
b210: 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  The SQLITE_OPEN_
b220: 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20  EXCLUSIVE flag, 
b230: 77 68 65 6e 20 70 61 69 72 65 64 20 77 69 74 68  when paired with
b240: 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f   the .** SQLITE_
b250: 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20  OPEN_CREATE, is 
b260: 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65  used to indicate
b270: 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c   that file shoul
b280: 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63  d always.** be c
b290: 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74  reated, and that
b2a0: 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20   it is an error 
b2b0: 69 66 20 69 74 20 61 6c 72 65 61 64 79 20 65 78  if it already ex
b2c0: 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c  ists..** It is <
b2d0: 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74  i>not</i> used t
b2e0: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65 20 66  o indicate the f
b2f0: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70  ile should be op
b300: 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63  ened .** for exc
b310: 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a  lusive access..*
b320: 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73  *.** ^At least s
b330: 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66  zOsFile bytes of
b340: 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f   memory are allo
b350: 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a  cated by SQLite.
b360: 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20  ** to hold the  
b370: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73  [sqlite3_file] s
b380: 74 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20  tructure passed 
b390: 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  as the third.** 
b3a0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
b3b0: 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65  n.  The xOpen me
b3c0: 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61  thod does not ha
b3d0: 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74  ve to.** allocat
b3e0: 65 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b  e the structure;
b3f0: 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20   it should just 
b400: 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74  fill it in.  Not
b410: 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f  e that.** the xO
b420: 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20  pen method must 
b430: 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  set the sqlite3_
b440: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f  file.pMethods to
b450: 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c   either.** a val
b460: 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  id [sqlite3_io_m
b470: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f  ethods] object o
b480: 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65  r to NULL.  xOpe
b490: 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69  n must do.** thi
b4a0: 73 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70  s even if the op
b4b0: 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74  en fails.  SQLit
b4c0: 65 20 65 78 70 65 63 74 73 20 74 68 61 74 20 74  e expects that t
b4d0: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
b4e0: 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d  pMethods.** elem
b4f0: 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69  ent will be vali
b500: 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65  d after xOpen re
b510: 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73  turns regardless
b520: 20 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 0a   of the success.
b530: 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66  ** or failure of
b540: 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e   the xOpen call.
b550: 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33  .**.** [[sqlite3
b560: 5f 76 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a  _vfs.xAccess]].*
b570: 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67  * ^The flags arg
b580: 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73  ument to xAccess
b590: 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54  () may be [SQLIT
b5a0: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d  E_ACCESS_EXISTS]
b5b0: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20  .** to test for 
b5c0: 74 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66  the existence of
b5d0: 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c   a file, or [SQL
b5e0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
b5f0: 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74  RITE] to.** test
b600: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20   whether a file 
b610: 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  is readable and 
b620: 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51  writable, or [SQ
b630: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
b640: 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65  ].** to test whe
b650: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61  ther a file is a
b660: 74 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65  t least readable
b670: 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e  .   The file can
b680: 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f   be a.** directo
b690: 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  ry..**.** ^SQLit
b6a0: 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c  e will always al
b6b0: 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20  locate at least 
b6c0: 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74  mxPathname+1 byt
b6d0: 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75  es for the.** ou
b6e0: 74 70 75 74 20 62 75 66 66 65 72 20 78 46 75 6c  tput buffer xFul
b6f0: 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20  lPathname.  The 
b700: 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68  exact size of th
b710: 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a  e output buffer.
b720: 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65  ** is also passe
b730: 64 20 61 73 20 61 20 70 61 72 61 6d 65 74 65 72  d as a parameter
b740: 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64   to both  method
b750: 73 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75 74  s. If the output
b760: 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f   buffer.** is no
b770: 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20  t large enough, 
b780: 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  [SQLITE_CANTOPEN
b790: 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75  ] should be retu
b7a0: 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73  rned. Since this
b7b0: 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61   is.** handled a
b7c0: 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20  s a fatal error 
b7d0: 62 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69  by SQLite, vfs i
b7e0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73  mplementations s
b7f0: 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a  hould endeavor.*
b800: 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69  * to prevent thi
b810: 73 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50  s by setting mxP
b820: 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66  athname to a suf
b830: 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20  ficiently large 
b840: 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  value..**.** The
b850: 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20   xRandomness(), 
b860: 78 53 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65  xSleep(), xCurre
b870: 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43  ntTime(), and xC
b880: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
b890: 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  ).** interfaces 
b8a0: 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  are not strictly
b8b0: 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66   a part of the f
b8c0: 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74  ilesystem, but t
b8d0: 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75  hey are.** inclu
b8e0: 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73  ded in the VFS s
b8f0: 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d  tructure for com
b900: 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68  pleteness..** Th
b910: 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20  e xRandomness() 
b920: 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74  function attempt
b930: 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74  s to return nByt
b940: 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67  es bytes.** of g
b950: 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64  ood-quality rand
b960: 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74  omness into zOut
b970: 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61  .  The return va
b980: 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63  lue is.** the ac
b990: 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62  tual number of b
b9a0: 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
b9b0: 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20  ss obtained..** 
b9c0: 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74  The xSleep() met
b9d0: 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63  hod causes the c
b9e0: 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f  alling thread to
b9f0: 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a   sleep for at.**
ba00: 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65   least the numbe
ba10: 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64  r of microsecond
ba20: 73 20 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78  s given.  ^The x
ba30: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a  CurrentTime().**
ba40: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
ba50: 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d  a Julian Day Num
ba60: 62 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72  ber for the curr
ba70: 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d  ent date and tim
ba80: 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69  e as.** a floati
ba90: 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a  ng point value..
baa0: 2a 2a 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74  ** ^The xCurrent
bab0: 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68  TimeInt64() meth
bac0: 6f 64 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61  od returns, as a
bad0: 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a  n integer, the J
bae0: 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d  ulian.** Day Num
baf0: 62 65 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62  ber multiplied b
bb00: 79 20 38 36 34 30 30 30 30 30 20 28 74 68 65 20  y 86400000 (the 
bb10: 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73  number of millis
bb20: 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20  econds in .** a 
bb30: 32 34 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a  24-hour day).  .
bb40: 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
bb50: 75 73 65 20 74 68 65 20 78 43 75 72 72 65 6e 74  use the xCurrent
bb60: 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68  TimeInt64() meth
bb70: 6f 64 20 74 6f 20 67 65 74 20 74 68 65 20 63 75  od to get the cu
bb80: 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e  rrent.** date an
bb90: 64 20 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d  d time if that m
bba0: 65 74 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62  ethod is availab
bbb0: 6c 65 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20  le (if iVersion 
bbc0: 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61  is 2 or .** grea
bbd0: 74 65 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63  ter and the func
bbe0: 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
bbf0: 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69  not NULL) and wi
bc00: 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20  ll fall back.** 
bc10: 74 6f 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  to xCurrentTime(
bc20: 29 20 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d  ) if xCurrentTim
bc30: 65 49 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76  eInt64() is unav
bc40: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e  ailable..**.** ^
bc50: 54 68 65 20 78 53 65 74 53 79 73 74 65 6d 43 61  The xSetSystemCa
bc60: 6c 6c 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d  ll(), xGetSystem
bc70: 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73  Call(), and xNes
bc80: 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e  tSystemCall() in
bc90: 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20  terfaces.** are 
bca0: 6e 6f 74 20 75 73 65 64 20 62 79 20 74 68 65 20  not used by the 
bcb0: 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68  SQLite core.  Th
bcc0: 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74  ese optional int
bcd0: 65 72 66 61 63 65 73 20 61 72 65 20 70 72 6f 76  erfaces are prov
bce0: 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20  ided.** by some 
bcf0: 56 46 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74  VFSes to facilit
bd00: 61 74 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74  ate testing of t
bd10: 68 65 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20  he VFS code. By 
bd20: 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73  overriding .** s
bd30: 79 73 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68  ystem calls with
bd40: 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72   functions under
bd50: 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20   its control, a 
bd60: 74 65 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e  test program can
bd70: 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75  .** simulate fau
bd80: 6c 74 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f  lts and error co
bd90: 6e 64 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f  nditions that wo
bda0: 75 6c 64 20 6f 74 68 65 72 77 69 73 65 20 62 65  uld otherwise be
bdb0: 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72   difficult.** or
bdc0: 20 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69   impossible to i
bdd0: 6e 64 75 63 65 2e 20 20 54 68 65 20 73 65 74 20  nduce.  The set 
bde0: 6f 66 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20  of system calls 
bdf0: 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72  that can be over
be00: 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73  ridden.** varies
be10: 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f   from one VFS to
be20: 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72   another, and fr
be30: 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f  om one version o
be40: 66 20 74 68 65 20 73 61 6d 65 20 56 46 53 20 74  f the same VFS t
be50: 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20  o the.** next.  
be60: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
be70: 74 20 75 73 65 20 74 68 65 73 65 20 69 6e 74 65  t use these inte
be80: 72 66 61 63 65 73 20 6d 75 73 74 20 62 65 20 70  rfaces must be p
be90: 72 65 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a  repared for any.
bea0: 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65  ** or all of the
beb0: 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f  se interfaces to
bec0: 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20   be NULL or for 
bed0: 74 68 65 69 72 20 62 65 68 61 76 69 6f 72 20 74  their behavior t
bee0: 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d  o change.** from
bef0: 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20   one release to 
bf00: 74 68 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69  the next.  Appli
bf10: 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74  cations must not
bf20: 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65   attempt to acce
bf30: 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65  ss.** any of the
bf40: 73 65 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68  se methods if th
bf50: 65 20 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68  e iVersion of th
bf60: 65 20 56 46 53 20 69 73 20 6c 65 73 73 20 74 68  e VFS is less th
bf70: 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  an 3..*/.typedef
bf80: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
bf90: 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b  vfs sqlite3_vfs;
bfa0: 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a  .typedef void (*
bfb0: 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f  sqlite3_syscall_
bfc0: 70 74 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75  ptr)(void);.stru
bfd0: 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b  ct sqlite3_vfs {
bfe0: 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b  .  int iVersion;
bff0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
c000: 74 72 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e  tructure version
c010: 20 6e 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74   number (current
c020: 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73  ly 3) */.  int s
c030: 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20  zOsFile;        
c040: 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73      /* Size of s
c050: 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65  ubclassed sqlite
c060: 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  3_file */.  int 
c070: 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20  mxPathname;     
c080: 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
c090: 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65  file pathname le
c0a0: 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65  ngth */.  sqlite
c0b0: 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20  3_vfs *pNext;   
c0c0: 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73     /* Next regis
c0d0: 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63  tered VFS */.  c
c0e0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
c0f0: 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20  ;       /* Name 
c100: 6f 66 20 74 68 69 73 20 76 69 72 74 75 61 6c 20  of this virtual 
c110: 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20  file system */. 
c120: 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b   void *pAppData;
c130: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69            /* Poi
c140: 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74  nter to applicat
c150: 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74  ion-specific dat
c160: 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70  a */.  int (*xOp
c170: 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  en)(sqlite3_vfs*
c180: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
c190: 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c  ame, sqlite3_fil
c1a0: 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  e*,.            
c1b0: 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e     int flags, in
c1c0: 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20  t *pOutFlags);. 
c1d0: 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28   int (*xDelete)(
c1e0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
c1f0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
c200: 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20   int syncDir);. 
c210: 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28   int (*xAccess)(
c220: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
c230: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
c240: 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20   int flags, int 
c250: 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74  *pResOut);.  int
c260: 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65   (*xFullPathname
c270: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
c280: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
c290: 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61  e, int nOut, cha
c2a0: 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64  r *zOut);.  void
c2b0: 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c   *(*xDlOpen)(sql
c2c0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
c2d0: 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65   char *zFilename
c2e0: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45  );.  void (*xDlE
c2f0: 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66  rror)(sqlite3_vf
c300: 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63  s*, int nByte, c
c310: 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20  har *zErrMsg);. 
c320: 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d   void (*(*xDlSym
c330: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76  )(sqlite3_vfs*,v
c340: 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  oid*, const char
c350: 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64   *zSymbol))(void
c360: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43  );.  void (*xDlC
c370: 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lose)(sqlite3_vf
c380: 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e  s*, void*);.  in
c390: 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29  t (*xRandomness)
c3a0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
c3b0: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
c3c0: 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  zOut);.  int (*x
c3d0: 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76  Sleep)(sqlite3_v
c3e0: 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65  fs*, int microse
c3f0: 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a  conds);.  int (*
c400: 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71  xCurrentTime)(sq
c410: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62  lite3_vfs*, doub
c420: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47  le*);.  int (*xG
c430: 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c  etLastError)(sql
c440: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20  ite3_vfs*, int, 
c450: 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20  char *);.  /*.  
c460: 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61  ** The methods a
c470: 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73  bove are in vers
c480: 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c  ion 1 of the sql
c490: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20  ite_vfs object. 
c4a0: 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20   ** definition. 
c4b0: 20 54 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c   Those that foll
c4c0: 6f 77 20 61 72 65 20 61 64 64 65 64 20 69 6e 20  ow are added in 
c4d0: 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74  version 2 or lat
c4e0: 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  er.  */.  int (*
c4f0: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
c500: 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  4)(sqlite3_vfs*,
c510: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29   sqlite3_int64*)
c520: 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20  ;.  /*.  ** The 
c530: 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  methods above ar
c540: 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20  e in versions 1 
c550: 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c  and 2 of the sql
c560: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a  ite_vfs object..
c570: 20 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77    ** Those below
c580: 20 61 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e   are for version
c590: 20 33 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a   3 and greater..
c5a0: 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65    */.  int (*xSe
c5b0: 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c  tSystemCall)(sql
c5c0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
c5d0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71   char *zName, sq
c5e0: 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74  lite3_syscall_pt
c5f0: 72 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79  r);.  sqlite3_sy
c600: 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74  scall_ptr (*xGet
c610: 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
c620: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
c630: 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20  char *zName);.  
c640: 63 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e  const char *(*xN
c650: 65 78 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  extSystemCall)(s
c660: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
c670: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
c680: 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d  .  /*.  ** The m
c690: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
c6a0: 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74   in versions 1 t
c6b0: 68 72 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20  hrough 3 of the 
c6c0: 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
c6d0: 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c  t..  ** New fiel
c6e0: 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64  ds may be append
c6f0: 65 64 20 69 6e 20 66 69 67 75 72 65 20 76 65 72  ed in figure ver
c700: 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72  sions.  The iVer
c710: 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20  sion.  ** value 
c720: 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77  will increment w
c730: 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70  henever this hap
c740: 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a  pens. .  */.};..
c750: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
c760: 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41  Flags for the xA
c770: 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64  ccess VFS method
c780: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
c790: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63  eger constants c
c7a0: 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68  an be used as th
c7b0: 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
c7c0: 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63  r to.** the xAcc
c7d0: 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e  ess method of an
c7e0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
c7f0: 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65 74  bject.  They det
c800: 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b  ermine.** what k
c810: 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f  ind of permissio
c820: 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ns the xAccess m
c830: 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67  ethod is looking
c840: 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51   for..** With SQ
c850: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
c860: 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TS, the xAccess 
c870: 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79  method.** simply
c880: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
c890: 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e  the file exists.
c8a0: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
c8b0: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
c8c0: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
c8d0: 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77  thod.** checks w
c8e0: 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64  hether the named
c8f0: 20 64 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f   directory is bo
c900: 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  th readable and 
c910: 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20  writable.** (in 
c920: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20  other words, if 
c930: 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64  files can be add
c940: 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64  ed, removed, and
c950: 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a   renamed within.
c960: 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f 72 79  ** the directory
c970: 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  )..** The SQLITE
c980: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
c990: 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75  E constant is cu
c9a0: 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c  rrently used onl
c9b0: 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d  y by the.** [tem
c9c0: 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
c9d0: 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67  y pragma], thoug
c9e0: 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61  h this could cha
c9f0: 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a  nge in a future.
ca00: 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  ** release of SQ
ca10: 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51  Lite..** With SQ
ca20: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
ca30: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
ca40: 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77  thod.** checks w
ca50: 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20  hether the file 
ca60: 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68  is readable.  Th
ca70: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
ca80: 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73  READ constant is
ca90: 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e  .** currently un
caa0: 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20  used, though it 
cab0: 6d 69 67 68 74 20 62 65 20 75 73 65 64 20 69 6e  might be used in
cac0: 20 61 20 66 75 74 75 72 65 20 72 65 6c 65 61 73   a future releas
cad0: 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a  e of.** SQLite..
cae0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
caf0: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20  E_ACCESS_EXISTS 
cb00: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
cb10: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
cb20: 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64  RITE 1   /* Used
cb30: 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f   by PRAGMA temp_
cb40: 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
cb50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
cb60: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20 20  E_ACCESS_READ   
cb70: 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64     2   /* Unused
cb80: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
cb90: 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74  REF: Flags for t
cba0: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20  he xShmLock VFS 
cbb0: 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65  method.**.** The
cbc0: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
cbd0: 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65 20  ants define the 
cbe0: 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20  various locking 
cbf0: 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c  operations.** al
cc00: 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78 53 68  lowed by the xSh
cc10: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20  mLock method of 
cc20: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
cc30: 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f  ods].  The.** fo
cc40: 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20  llowing are the 
cc50: 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69  only legal combi
cc60: 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73  nations of flags
cc70: 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c   to the.** xShmL
cc80: 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a  ock method:.**.*
cc90: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
cca0: 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
ccb0: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  | SQLITE_SHM_SHA
ccc0: 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  RED.** <li>  SQL
ccd0: 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53  ITE_SHM_LOCK | S
cce0: 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53  QLITE_SHM_EXCLUS
ccf0: 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  IVE.** <li>  SQL
cd00: 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c  ITE_SHM_UNLOCK |
cd10: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
cd20: 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  ED.** <li>  SQLI
cd30: 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20  TE_SHM_UNLOCK | 
cd40: 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55  SQLITE_SHM_EXCLU
cd50: 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  SIVE.** </ul>.**
cd60: 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69  .** When unlocki
cd70: 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41  ng, the same SHA
cd80: 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45  RED or EXCLUSIVE
cd90: 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75   flag must be su
cda0: 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73  pplied as.** was
cdb0: 20 67 69 76 65 6e 20 6e 6f 20 74 68 65 20 63 6f   given no the co
cdc0: 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b  rresponding lock
cdd0: 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  .  .**.** The xS
cde0: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61  hmLock method ca
cdf0: 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74  n transition bet
ce00: 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e  ween unlocked an
ce10: 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62  d SHARED or.** b
ce20: 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20  etween unlocked 
ce30: 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20  and EXCLUSIVE.  
ce40: 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69  It cannot transi
ce50: 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41  tion between SHA
ce60: 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55  RED.** and EXCLU
ce70: 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  SIVE..*/.#define
ce80: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
ce90: 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65 66 69  CK       1.#defi
cea0: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  ne SQLITE_SHM_LO
ceb0: 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23 64 65  CK         2.#de
cec0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
ced0: 53 48 41 52 45 44 20 20 20 20 20 20 20 34 0a 23  SHARED       4.#
cee0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
cef0: 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 38  M_EXCLUSIVE    8
cf00: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
cf10: 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f  : Maximum xShmLo
cf20: 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54  ck index.**.** T
cf30: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
cf40: 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69  od on [sqlite3_i
cf50: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75  o_methods] may u
cf60: 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74  se values.** bet
cf70: 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20  ween 0 and this 
cf80: 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69  upper bound as i
cf90: 74 73 20 22 6f 66 66 73 65 74 22 20 61 72 67 75  ts "offset" argu
cfa0: 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  ment..** The SQL
cfb0: 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65  ite core will ne
cfc0: 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61  ver attempt to a
cfd0: 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73  cquire or releas
cfe0: 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73  e a.** lock outs
cff0: 69 64 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67  ide of this rang
d000: 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e.*/.#define SQL
d010: 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20  ITE_SHM_NLOCK   
d020: 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43       8.../*.** C
d030: 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c  API3REF: Initial
d040: 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c  ize The SQLite L
d050: 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68  ibrary.**.** ^Th
d060: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
d070: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69  lize() routine i
d080: 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a  nitializes the.*
d090: 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  * SQLite library
d0a0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
d0b0: 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69  shutdown() routi
d0c0: 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65  ne.** deallocate
d0d0: 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20  s any resources 
d0e0: 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61  that were alloca
d0f0: 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69  ted by sqlite3_i
d100: 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20  nitialize()..** 
d110: 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
d120: 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61  re designed to a
d130: 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e  id in process in
d140: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64  itialization and
d150: 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20  .** shutdown on 
d160: 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73  embedded systems
d170: 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61  .  Workstation a
d180: 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e  pplications usin
d190: 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d  g.** SQLite norm
d1a0: 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64  ally do not need
d1b0: 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65   to invoke eithe
d1c0: 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  r of these routi
d1d0: 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c  nes..**.** A cal
d1e0: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69  l to sqlite3_ini
d1f0: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20  tialize() is an 
d200: 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c  "effective" call
d210: 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65   if it is.** the
d220: 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69   first time sqli
d230: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
d240: 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69   is invoked duri
d250: 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20  ng the lifetime 
d260: 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73  of.** the proces
d270: 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 74  s, or if it is t
d280: 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71  he first time sq
d290: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
d2a0: 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
d2b0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c   following a cal
d2c0: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
d2d0: 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79  tdown().  ^(Only
d2e0: 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61   an effective ca
d2f0: 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  ll.** of sqlite3
d300: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f  _initialize() do
d310: 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a  es any initializ
d320: 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65  ation.  All othe
d330: 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68  r calls.** are h
d340: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29  armless no-ops.)
d350: 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ^.**.** A call t
d360: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
d370: 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  wn() is an "effe
d380: 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
d390: 74 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a  t is the first.*
d3a0: 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  * call to sqlite
d3b0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e  3_shutdown() sin
d3c0: 63 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69  ce the last sqli
d3d0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
d3e0: 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20  .  ^(Only.** an 
d3f0: 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74  effective call t
d400: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
d410: 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65  wn() does any de
d420: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a  initialization..
d430: 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c  ** All other val
d440: 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  id calls to sqli
d450: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61  te3_shutdown() a
d460: 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  re harmless no-o
d470: 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ps.)^.**.** The 
d480: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
d490: 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ze() interface i
d4a0: 73 20 74 68 72 65 61 64 73 61 66 65 2c 20 62 75  s threadsafe, bu
d4b0: 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  t sqlite3_shutdo
d4c0: 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20  wn().** is not. 
d4d0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75   The sqlite3_shu
d4e0: 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63  tdown() interfac
d4f0: 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63  e must only be c
d500: 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20  alled from a.** 
d510: 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20  single thread.  
d520: 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61  All open [databa
d530: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
d540: 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61  must be closed a
d550: 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20  nd all.** other 
d560: 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73  SQLite resources
d570: 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63   must be dealloc
d580: 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e  ated prior to in
d590: 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  voking.** sqlite
d5a0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a  3_shutdown()..**
d5b0: 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20  .** Among other 
d5c0: 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33  things, ^sqlite3
d5d0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69  _initialize() wi
d5e0: 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c  ll invoke.** sql
d5f0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
d600: 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c   Similarly, ^sql
d610: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
d620: 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73  ** will invoke s
d630: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e  qlite3_os_end().
d640: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
d650: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
d660: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
d670: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
d680: 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20  success..** ^If 
d690: 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c  for some reason,
d6a0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
d6b0: 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20  ize() is unable 
d6c0: 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a  to initialize.**
d6d0: 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 65   the library (pe
d6e0: 72 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 62  rhaps it is unab
d6f0: 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61  le to allocate a
d700: 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 65   needed resource
d710: 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75   such.** as a mu
d720: 74 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 20  tex) it returns 
d730: 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
d740: 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
d750: 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  TE_OK]..**.** ^T
d760: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
d770: 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
d780: 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e  is called intern
d790: 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68  ally by many oth
d7a0: 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  er.** SQLite int
d7b0: 65 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 20  erfaces so that 
d7c0: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75  an application u
d7d0: 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20  sually does not 
d7e0: 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b  need to.** invok
d7f0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
d800: 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e  lize() directly.
d810: 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b    For example, [
d820: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a  sqlite3_open()].
d830: 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33  ** calls sqlite3
d840: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f  _initialize() so
d850: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
d860: 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f  ary will be auto
d870: 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69  matically.** ini
d880: 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73  tialized when [s
d890: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69  qlite3_open()] i
d8a0: 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68  s called if it h
d8b0: 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61  as not be initia
d8c0: 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79  lized.** already
d8d0: 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20  .  ^However, if 
d8e0: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
d8f0: 65 64 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ed with the [SQL
d900: 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49  ITE_OMIT_AUTOINI
d910: 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  T].** compile-ti
d920: 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20  me option, then 
d930: 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61  the automatic ca
d940: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  lls to sqlite3_i
d950: 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61  nitialize().** a
d960: 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74  re omitted and t
d970: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
d980: 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  ust call sqlite3
d990: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69  _initialize() di
d9a0: 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20  rectly.** prior 
d9b0: 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68  to using any oth
d9c0: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
d9d0: 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75  ace.  For maximu
d9e0: 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a  m portability,.*
d9f0: 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  * it is recommen
da00: 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61  ded that applica
da10: 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76  tions always inv
da20: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  oke sqlite3_init
da30: 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65  ialize().** dire
da40: 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73  ctly prior to us
da50: 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
da60: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
da70: 20 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   Future releases
da80: 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61  .** of SQLite ma
da90: 79 20 72 65 71 75 69 72 65 20 74 68 69 73 2e 20  y require this. 
daa0: 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
dab0: 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 78   the behavior ex
dac0: 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20  hibited.** when 
dad0: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
dae0: 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
daf0: 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d  OMIT_AUTOINIT] m
db00: 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a  ight become the.
db10: 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61 76  ** default behav
db20: 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75  ior in some futu
db30: 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  re release of SQ
db40: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
db50: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
db60: 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f  ) routine does o
db70: 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20  perating-system 
db80: 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74  specific.** init
db90: 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68  ialization of th
dba0: 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
dbb0: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  .  The sqlite3_o
dbc0: 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69  s_end().** routi
dbd0: 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66  ne undoes the ef
dbe0: 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f  fect of sqlite3_
dbf0: 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69  os_init().  Typi
dc00: 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72  cal tasks.** per
dc10: 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65 20  formed by these 
dc20: 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65  routines include
dc30: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64   allocation or d
dc40: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
dc50: 66 20 73 74 61 74 69 63 20 72 65 73 6f 75 72 63  f static resourc
dc60: 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  es, initializati
dc70: 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72  on of global var
dc80: 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69  iables,.** setti
dc90: 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c 74 20  ng up a default 
dca0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f  [sqlite3_vfs] mo
dcb0: 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67  dule, or setting
dcc0: 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74   up.** a default
dcd0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75   configuration u
dce0: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f  sing [sqlite3_co
dcf0: 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  nfig()]..**.** T
dd00: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
dd10: 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f  hould never invo
dd20: 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69 74 65  ke either sqlite
dd30: 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f  3_os_init().** o
dd40: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  r sqlite3_os_end
dd50: 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68  () directly.  Th
dd60: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
dd70: 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65  ould only invoke
dd80: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  .** sqlite3_init
dd90: 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c  ialize() and sql
dda0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
ddb0: 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73    The sqlite3_os
ddc0: 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72  _init().** inter
ddd0: 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61  face is called a
dde0: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20  utomatically by 
ddf0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
de00: 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  ze() and.** sqli
de10: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20  te3_os_end() is 
de20: 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65  called by sqlite
de30: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41  3_shutdown().  A
de40: 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d  ppropriate.** im
de50: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f  plementations fo
de60: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  r sqlite3_os_ini
de70: 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
de80: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20  os_end().** are 
de90: 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
dea0: 65 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d  e when it is com
deb0: 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20  piled for Unix, 
dec0: 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32  Windows, or OS/2
ded0: 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f  ..** When [custo
dee0: 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74  m builds | built
def0: 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66   for other platf
df00: 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20  orms].** (using 
df10: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f  the [SQLITE_OS_O
df20: 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d  THER=1] compile-
df30: 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20  time.** option) 
df40: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
df50: 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 75  must supply a su
df60: 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  itable implement
df70: 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c  ation for.** sql
df80: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
df90: 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
dfa0: 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61  d().  An applica
dfb0: 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a  tion-supplied.**
dfc0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
dfd0: 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
dfe0: 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  it() or sqlite3_
dff0: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74  os_end().** must
e000: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
e010: 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61  OK] on success a
e020: 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65  nd some other [e
e030: 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a  rror code] upon.
e040: 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69  ** failure..*/.i
e050: 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  nt sqlite3_initi
e060: 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74  alize(void);.int
e070: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
e080: 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  n(void);.int sql
e090: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69  ite3_os_init(voi
e0a0: 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
e0b0: 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f  os_end(void);../
e0c0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
e0d0: 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53  onfiguring The S
e0e0: 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a  QLite Library.**
e0f0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
e100: 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
e110: 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61  ce is used to ma
e120: 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67  ke global config
e130: 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67  uration.** chang
e140: 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20  es to SQLite in 
e150: 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51  order to tune SQ
e160: 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63  Lite to the spec
e170: 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a  ific needs of.**
e180: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
e190: 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63  .  The default c
e1a0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20  onfiguration is 
e1b0: 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
e1c0: 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74  most.** applicat
e1d0: 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73  ions and so this
e1e0: 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61   routine is usua
e1f0: 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72  lly not necessar
e200: 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f  y.  It is.** pro
e210: 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74  vided to support
e220: 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f   rare applicatio
e230: 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20  ns with unusual 
e240: 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  needs..**.** The
e250: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
e260: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  ) interface is n
e270: 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 20  ot threadsafe.  
e280: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a  The application.
e290: 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74  ** must insure t
e2a0: 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c  hat no other SQL
e2b0: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61  ite interfaces a
e2c0: 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74  re invoked by ot
e2d0: 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77  her.** threads w
e2e0: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e  hile sqlite3_con
e2f0: 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  fig() is running
e300: 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20  .  Furthermore, 
e310: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
e320: 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  .** may only be 
e330: 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f  invoked prior to
e340: 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c   library initial
e350: 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a  ization using.**
e360: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
e370: 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72  lize()] or after
e380: 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71   shutdown by [sq
e390: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
e3a0: 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  ]..** ^If sqlite
e3b0: 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61  3_config() is ca
e3c0: 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69  lled after [sqli
e3d0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
e3e0: 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20  ] and before.** 
e3f0: 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
e400: 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c  n()] then it wil
e410: 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  l return SQLITE_
e420: 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c  MISUSE..** Note,
e430: 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e   however, that ^
e440: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
e450: 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61   can be called a
e460: 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a  s part of the.**
e470: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
e480: 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  of an applicatio
e490: 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74  n-defined [sqlit
e4a0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a  e3_os_init()]..*
e4b0: 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
e4c0: 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
e4d0: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61  e3_config() is a
e4e0: 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f  n integer.** [co
e4f0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
e500: 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69  on] that determi
e510: 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70  nes.** what prop
e520: 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69  erty of SQLite i
e530: 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72  s to be configur
e540: 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20  ed.  Subsequent 
e550: 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72  arguments.** var
e560: 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  y depending on t
e570: 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f  he [configuratio
e580: 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20  n option].** in 
e590: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
e5a0: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20  nt..**.** ^When 
e5b0: 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  a configuration 
e5c0: 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73  option is set, s
e5d0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
e5e0: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
e5f0: 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  OK]..** ^If the 
e600: 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77  option is unknow
e610: 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75  n or SQLite is u
e620: 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  nable to set the
e630: 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20   option.** then 
e640: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  this routine ret
e650: 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20  urns a non-zero 
e660: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f  [error code]..*/
e670: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  .int sqlite3_con
e680: 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a  fig(int, ...);..
e690: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
e6a0: 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 61  Configure databa
e6b0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a  se connections.*
e6c0: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
e6d0: 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  _db_config() int
e6e0: 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74  erface is used t
e6f0: 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61  o make configura
e700: 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20  tion.** changes 
e710: 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  to a [database c
e720: 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65  onnection].  The
e730: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 69   interface is si
e740: 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c  milar to.** [sql
e750: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65  ite3_config()] e
e760: 78 63 65 70 74 20 74 68 61 74 20 74 68 65 20 63  xcept that the c
e770: 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20  hanges apply to 
e780: 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74  a single.** [dat
e790: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
e7a0: 5d 20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20  ] (specified in 
e7b0: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
e7c0: 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  nt)..**.** The s
e7d0: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
e7e0: 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  o sqlite3_db_con
e7f0: 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73  fig(D,V,...)  is
e800: 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
e810: 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
e820: 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69  DE | configurati
e830: 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e  on verb] - an in
e840: 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74  teger code .** t
e850: 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 68  hat indicates wh
e860: 61 74 20 61 73 70 65 63 74 20 6f 66 20 74 68 65  at aspect of the
e870: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
e880: 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20  ction] is being 
e890: 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53  configured..** S
e8a0: 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65  ubsequent argume
e8b0: 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e 64 69  nts vary dependi
e8c0: 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67  ng on the config
e8d0: 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a  uration verb..**
e8e0: 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71  .** ^Calls to sq
e8f0: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
e900: 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  ) return SQLITE_
e910: 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  OK if and only i
e920: 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73  f.** the call is
e930: 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63   considered succ
e940: 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73  essful..*/.int s
e950: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
e960: 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f  (sqlite3*, int o
e970: 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20  p, ...);../*.** 
e980: 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
e990: 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74   Allocation Rout
e9a0: 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  ines.**.** An in
e9b0: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
e9c0: 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68  bject defines th
e9d0: 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77  e interface betw
e9e0: 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e  een SQLite.** an
e9f0: 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f  d low-level memo
ea00: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
ea10: 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  utines..**.** Th
ea20: 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  is object is use
ea30: 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c  d in only one pl
ea40: 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74  ace in the SQLit
ea50: 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20  e interface..** 
ea60: 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  A pointer to an 
ea70: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
ea80: 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20 61   object is the a
ea90: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73  rgument to.** [s
eaa0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
eab0: 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67   when the config
eac0: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69  uration option i
ead0: 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  s.** [SQLITE_CON
eae0: 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b  FIG_MALLOC] or [
eaf0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
eb00: 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42  TMALLOC].  .** B
eb10: 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e  y creating an in
eb20: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
eb30: 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73  bject.** and pas
eb40: 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69  sing it to [sqli
eb50: 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c  te3_config]([SQL
eb60: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
eb70: 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f  C]).** during co
eb80: 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20  nfiguration, an 
eb90: 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20  application can 
eba0: 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72  specify an alter
ebb0: 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79  native.** memory
ebc0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73   allocation subs
ebd0: 79 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65  ystem for SQLite
ebe0: 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20   to use for all 
ebf0: 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69  of its.** dynami
ec00: 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a  c memory needs..
ec10: 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
ec20: 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74  SQLite comes wit
ec30: 68 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74  h several [built
ec40: 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  -in memory alloc
ec50: 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61  ators].** that a
ec60: 72 65 20 70 65 72 66 65 63 74 6c 79 20 61 64 65  re perfectly ade
ec70: 71 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76  quate for the ov
ec80: 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72  erwhelming major
ec90: 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69  ity of applicati
eca0: 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20  ons.** and that 
ecb0: 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f  this object is o
ecc0: 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20  nly useful to a 
ecd0: 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66  tiny minority of
ece0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
ecf0: 20 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65   with specialize
ed00: 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  d memory allocat
ed10: 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73  ion requirements
ed20: 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  .  This object i
ed30: 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64  s.** also used d
ed40: 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66  uring testing of
ed50: 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72   SQLite in order
ed60: 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61   to specify an a
ed70: 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65  lternative.** me
ed80: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74  mory allocator t
ed90: 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65  hat simulates me
eda0: 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f  mory out-of-memo
edb0: 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e  ry conditions in
edc0: 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72  .** order to ver
edd0: 69 66 79 20 74 68 61 74 20 53 51 4c 69 74 65 20  ify that SQLite 
ede0: 72 65 63 6f 76 65 72 73 20 67 72 61 63 65 66 75  recovers gracefu
edf0: 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a  lly from such.**
ee00: 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a   conditions..**.
ee10: 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20  ** The xMalloc, 
ee20: 78 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46  xRealloc, and xF
ee30: 72 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74  ree methods must
ee40: 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a   work like the.*
ee50: 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c  * malloc(), real
ee60: 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
ee70: 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20   functions from 
ee80: 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
ee90: 69 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69  ibrary..** ^SQLi
eea0: 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  te guarantees th
eeb0: 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  at the second ar
eec0: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65  gument to.** xRe
eed0: 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20  alloc is always 
eee0: 61 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  a value returned
eef0: 20 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c   by a prior call
ef00: 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a   to xRoundup..**
ef10: 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64  .** xSize should
ef20: 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f   return the allo
ef30: 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20  cated size of a 
ef40: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
ef50: 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  n.** previously 
ef60: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d  obtained from xM
ef70: 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f  alloc or xReallo
ef80: 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65  c.  The allocate
ef90: 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77  d size.** is alw
efa0: 61 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20  ays at least as 
efb0: 62 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65  big as the reque
efc0: 73 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61  sted size but ma
efd0: 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a  y be larger..**.
efe0: 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20  ** The xRoundup 
eff0: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77  method returns w
f000: 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65  hat would be the
f010: 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20   allocated size 
f020: 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61  of.** a memory a
f030: 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20  llocation given 
f040: 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71  a particular req
f050: 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f  uested size.  Mo
f060: 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  st memory.** all
f070: 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70  ocators round up
f080: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
f090: 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20  ons at least to 
f0a0: 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c  the next multipl
f0b0: 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65  e.** of 8.  Some
f0c0: 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e   allocators roun
f0d0: 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72  d up to a larger
f0e0: 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20   multiple or to 
f0f0: 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a  a power of 2..**
f100: 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c   Every memory al
f110: 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74  location request
f120: 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75   coming in throu
f130: 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  gh [sqlite3_mall
f140: 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c  oc()].** or [sql
f150: 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20  ite3_realloc()] 
f160: 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75  first calls xRou
f170: 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64  ndup.  If xRound
f180: 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a  up returns 0, .*
f190: 2a 20 74 68 61 74 20 63 61 75 73 65 73 20 74 68  * that causes th
f1a0: 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
f1b0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
f1c0: 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a  n to fail..**.**
f1d0: 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   The xInit metho
f1e0: 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68  d initializes th
f1f0: 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
f200: 6f 72 2e 20 20 28 46 6f 72 20 65 78 61 6d 70 6c  or.  (For exampl
f210: 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61  e,.** it might a
f220: 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75  llocate any requ
f230: 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69  ire mutexes or i
f240: 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e  nitialize intern
f250: 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63  al data.** struc
f260: 74 75 72 65 73 2e 20 20 54 68 65 20 78 53 68 75  tures.  The xShu
f270: 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20  tdown method is 
f280: 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63  invoked (indirec
f290: 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  tly) by.** [sqli
f2a0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
f2b0: 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c  and should deall
f2c0: 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72  ocate any resour
f2d0: 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20  ces acquired.** 
f2e0: 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70  by xInit.  The p
f2f0: 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20  AppData pointer 
f300: 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 6f  is used as the o
f310: 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f  nly parameter to
f320: 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53  .** xInit and xS
f330: 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53  hutdown..**.** S
f340: 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20  QLite holds the 
f350: 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54  [SQLITE_MUTEX_ST
f360: 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74  ATIC_MASTER] mut
f370: 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b  ex when it invok
f380: 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20  es.** the xInit 
f390: 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78  method, so the x
f3a0: 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64  Init method need
f3b0: 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73 61   not be threadsa
f3c0: 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75  fe.  The.** xShu
f3d0: 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20  tdown method is 
f3e0: 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d  only called from
f3f0: 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
f400: 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73  wn()] so it does
f410: 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  .** not need to 
f420: 62 65 20 74 68 72 65 61 64 73 61 66 65 20 65 69  be threadsafe ei
f430: 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f  ther.  For all o
f440: 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51  ther methods, SQ
f450: 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68  Lite.** holds th
f460: 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  e [SQLITE_MUTEX_
f470: 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65  STATIC_MEM] mute
f480: 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  x as long as the
f490: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
f4a0: 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f  IG_MEMSTATUS] co
f4b0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
f4c0: 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20  on is turned on 
f4d0: 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20  (which.** it is 
f4e0: 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20  by default) and 
f4f0: 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61  so the methods a
f500: 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  re automatically
f510: 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20   serialized..** 
f520: 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c  However, if [SQL
f530: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
f540: 41 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65  ATUS] is disable
f550: 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65  d, then the othe
f560: 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73  r.** methods mus
f570: 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20  t be threadsafe 
f580: 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65  or else make the
f590: 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65  ir own arrangeme
f5a0: 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61  nts for.** seria
f5b0: 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  lization..**.** 
f5c0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65  SQLite will neve
f5d0: 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29  r invoke xInit()
f5e0: 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20   more than once 
f5f0: 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72  without an inter
f600: 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74  vening.** call t
f610: 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a  o xShutdown()..*
f620: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
f630: 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
f640: 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d  hods sqlite3_mem
f650: 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74  _methods;.struct
f660: 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
f670: 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28  hods {.  void *(
f680: 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20  *xMalloc)(int); 
f690: 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72          /* Memor
f6a0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e  y allocation fun
f6b0: 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ction */.  void 
f6c0: 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b  (*xFree)(void*);
f6d0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65            /* Fre
f6e0: 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  e a prior alloca
f6f0: 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  tion */.  void *
f700: 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64  (*xRealloc)(void
f710: 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69  *,int);  /* Resi
f720: 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e  ze an allocation
f730: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a   */.  int (*xSiz
f740: 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  e)(void*);      
f750: 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74       /* Return t
f760: 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c  he size of an al
f770: 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e  location */.  in
f780: 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e  t (*xRoundup)(in
f790: 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  t);          /* 
f7a0: 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73 74  Round up request
f7b0: 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74   size to allocat
f7c0: 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e  ion size */.  in
f7d0: 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a  t (*xInit)(void*
f7e0: 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  );           /* 
f7f0: 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d  Initialize the m
f800: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
f810: 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75  */.  void (*xShu
f820: 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20  tdown)(void*);  
f830: 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c      /* Deinitial
f840: 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ize the memory a
f850: 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f  llocator */.  vo
f860: 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
f870: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
f880: 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69  Argument to xIni
f890: 74 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77  t() and xShutdow
f8a0: 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  n() */.};../*.**
f8b0: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
f8c0: 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73  guration Options
f8d0: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63  .** KEYWORDS: {c
f8e0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
f8f0: 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ion}.**.** These
f900: 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74   constants are t
f910: 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74  he available int
f920: 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69  eger configurati
f930: 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a  on options that.
f940: 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64  ** can be passed
f950: 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
f960: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73  gument to the [s
f970: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
f980: 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
f990: 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74  * New configurat
f9a0: 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20  ion options may 
f9b0: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
f9c0: 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
f9d0: 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69  QLite..** Existi
f9e0: 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
f9f0: 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62   options might b
fa00: 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20  e discontinued. 
fa10: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   Applications.**
fa20: 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68   should check th
fa30: 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72  e return code fr
fa40: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  om [sqlite3_conf
fa50: 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75  ig()] to make su
fa60: 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63  re that.** the c
fa70: 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65  all worked.  The
fa80: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
fa90: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69  ()] interface wi
faa0: 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e  ll return a.** n
fab0: 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
fac0: 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e  ode] if a discon
fad0: 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70  tinued or unsupp
fae0: 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74  orted configurat
faf0: 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73  ion option.** is
fb00: 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
fb10: 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  <dl>.** [[SQLITE
fb20: 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
fb30: 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  READ]] <dt>SQLIT
fb40: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
fb50: 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  HREAD</dt>.** <d
fb60: 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61  d>There are no a
fb70: 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
fb80: 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20   option.  ^This 
fb90: 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a  option sets the.
fba0: 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ** [threading mo
fbb0: 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68  de] to Single-th
fbc0: 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20  read.  In other 
fbd0: 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c  words, it disabl
fbe0: 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69  es.** all mutexi
fbf0: 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69  ng and puts SQLi
fc00: 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77  te into a mode w
fc10: 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79  here it can only
fc20: 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61   be used.** by a
fc30: 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20   single thread. 
fc40: 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20    ^If SQLite is 
fc50: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
fc60: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
fc70: 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
fc80: 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
fc90: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
fca0: 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73  on then.** it is
fcb0: 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
fcc0: 20 63 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72   change the [thr
fcd0: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f  eading mode] fro
fce0: 6d 20 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a  m its default.**
fcf0: 20 76 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65   value of Single
fd00: 2d 74 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b  -thread and so [
fd10: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
fd20: 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a  ] will return .*
fd30: 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  * [SQLITE_ERROR]
fd40: 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20   if called with 
fd50: 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
fd60: 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a  G_SINGLETHREAD.*
fd70: 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
fd80: 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  option.</dd>.**.
fd90: 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
fda0: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d  IG_MULTITHREAD]]
fdb0: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
fdc0: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f  IG_MULTITHREAD</
fdd0: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
fde0: 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
fdf0: 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
fe00: 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
fe10: 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
fe20: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
fe30: 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49  Multi-thread.  I
fe40: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
fe50: 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75  t disables.** mu
fe60: 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62  texing on [datab
fe70: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
fe80: 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
fe90: 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73  atement] objects
fea0: 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
feb0: 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69  tion is responsi
fec0: 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a  ble for serializ
fed0: 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a  ing access to.**
fee0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
fef0: 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65  ctions] and [pre
ff00: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
ff10: 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75  ].  But other mu
ff20: 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61  texes.** are ena
ff30: 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c  bled so that SQL
ff40: 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65  ite will be safe
ff50: 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c   to use in a mul
ff60: 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65  ti-threaded.** e
ff70: 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f  nvironment as lo
ff80: 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72  ng as no two thr
ff90: 65 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20  eads attempt to 
ffa0: 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  use the same.** 
ffb0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
ffc0: 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d  tion] at the sam
ffd0: 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c  e time.  ^If SQL
ffe0: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
fff0: 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
10000 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
10010 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
10020 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
10030 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
10040 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73  * it is not poss
10050 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20  ible to set the 
10060 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68  Multi-thread [th
10070 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e  reading mode] an
10080 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
10090 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
100a0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
100b0 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
100c0 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
100d0 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
100e0 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  AD configuration
100f0 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a   option.</dd>.**
10100 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
10110 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d  FIG_SERIALIZED]]
10120 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
10130 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64  IG_SERIALIZED</d
10140 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20  t>.** <dd>There 
10150 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73  are no arguments
10160 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e   to this option.
10170 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73    ^This option s
10180 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65  ets the.** [thre
10190 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53  ading mode] to S
101a0 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74  erialized. In ot
101b0 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20  her words, this 
101c0 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a  option enables.*
101d0 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e  * all mutexes in
101e0 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63 75  cluding the recu
101f0 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73  rsive.** mutexes
10200 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
10210 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70  nnection] and [p
10220 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
10230 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49  t] objects..** I
10240 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69  n this mode (whi
10250 63 68 20 69 73 20 74 68 65 20 64 65 66 61 75 6c  ch is the defaul
10260 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73  t when SQLite is
10270 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
10280 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  * [SQLITE_THREAD
10290 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c  SAFE=1]) the SQL
102a0 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c  ite library will
102b0 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a   itself serializ
102c0 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b  e access.** to [
102d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
102e0 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61  ions] and [prepa
102f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20  red statements] 
10300 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61  so that the.** a
10310 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72  pplication is fr
10320 65 65 20 74 6f 20 75 73 65 20 74 68 65 20 73 61  ee to use the sa
10330 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  me [database con
10340 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a  nection] or the.
10350 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65  ** same [prepare
10360 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20  d statement] in 
10370 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
10380 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  s at the same ti
10390 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74  me..** ^If SQLit
103a0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
103b0 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
103c0 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
103d0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
103e0 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
103f0 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
10400 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62  it is not possib
10410 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 53 65  le to set the Se
10420 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
10430 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a  ing mode] and.**
10440 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
10450 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
10460 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
10470 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68  f called with th
10480 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46  e.** SQLITE_CONF
10490 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f  IG_SERIALIZED co
104a0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
104b0 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  on.</dd>.**.** [
104c0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
104d0 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49  ALLOC]] <dt>SQLI
104e0 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
104f0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
10500 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
10510 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
10520 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
10530 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
10540 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
10550 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
10560 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
10570 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73    The argument s
10580 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65  pecifies.** alte
10590 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65  rnative low-leve
105a0 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
105b0 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ion routines to 
105c0 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65  be used in place
105d0 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72   of.** the memor
105e0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
105f0 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f  tines built into
10600 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69   SQLite.)^ ^SQLi
10610 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20  te makes.** its 
10620 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
10630 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20   of the content 
10640 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
10650 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
10660 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65  ucture.** before
10670 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
10680 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74  nfig()] call ret
10690 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  urns.</dd>.**.**
106a0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
106b0 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74  _GETMALLOC]] <dt
106c0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
106d0 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a  ETMALLOC</dt>.**
106e0 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
106f0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
10700 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
10710 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
10720 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
10730 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
10740 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
10750 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 5b 73  ructure.  The [s
10760 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
10770 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  ds].** structure
10780 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
10790 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65  the currently de
107a0 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  fined memory all
107b0 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
107c0 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69  .)^.** This opti
107d0 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  on can be used t
107e0 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64  o overload the d
107f0 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c  efault memory al
10800 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74  location.** rout
10810 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70  ines with a wrap
10820 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74  per that simulat
10830 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ions memory allo
10840 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f  cation failure o
10850 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f  r.** tracks memo
10860 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78  ry usage, for ex
10870 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a  ample. </dd>.**.
10880 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
10890 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c  IG_MEMSTATUS]] <
108a0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
108b0 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a  _MEMSTATUS</dt>.
108c0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
108d0 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c  tion takes singl
108e0 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79  e argument of ty
108f0 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65  pe int, interpre
10900 74 65 64 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f  ted as a .** boo
10910 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62  lean, which enab
10920 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
10930 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f  the collection o
10940 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  f memory allocat
10950 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73 74 69  ion .** statisti
10960 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72  cs. ^(When memor
10970 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
10980 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61  tistics are disa
10990 62 6c 65 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f  bled, the .** fo
109a0 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69  llowing SQLite i
109b0 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65  nterfaces become
109c0 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c   non-operational
109d0 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20  :.**   <ul>.**  
109e0 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d   <li> [sqlite3_m
109f0 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a  emory_used()].**
10a00 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
10a10 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
10a20 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  r()].**   <li> [
10a30 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
10a40 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20  p_limit64()].** 
10a50 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
10a60 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c  status()].**   <
10a70 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72  /ul>)^.** ^Memor
10a80 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
10a90 74 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 62  tistics are enab
10aa0 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 75  led by default u
10ab0 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a  nless SQLite is.
10ac0 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  ** compiled with
10ad0 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54   [SQLITE_DEFAULT
10ae0 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e  _MEMSTATUS]=0 in
10af0 20 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f   which case memo
10b00 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
10b10 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
10b20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
10b30 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ult..** </dd>.**
10b40 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
10b50 46 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64  FIG_SCRATCH]] <d
10b60 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
10b70 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20  SCRATCH</dt>.** 
10b80 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
10b90 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74  n specifies a st
10ba0 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66  atic memory buff
10bb0 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  er that SQLite c
10bc0 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63  an use for.** sc
10bd0 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54  ratch memory.  T
10be0 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
10bf0 72 67 75 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69  rguments:  A poi
10c00 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a  nter an 8-byte.*
10c10 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79  * aligned memory
10c20 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69   buffer from whi
10c30 63 68 20 74 68 65 20 73 63 72 61 74 63 68 20 61  ch the scratch a
10c40 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20  llocations will 
10c50 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65  be.** drawn, the
10c60 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63   size of each sc
10c70 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e  ratch allocation
10c80 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68   (sz),.** and th
10c90 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
10ca0 20 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f   of scratch allo
10cb0 63 61 74 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68  cations (N).  Th
10cc0 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  e sz.** argument
10cd0 20 6d 75 73 74 20 62 65 20 61 20 6d 75 6c 74 69   must be a multi
10ce0 70 6c 65 20 6f 66 20 31 36 2e 0a 2a 2a 20 54 68  ple of 16..** Th
10cf0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
10d00 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74   must be a point
10d10 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  er to an 8-byte 
10d20 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a  aligned buffer.*
10d30 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a  * of at least sz
10d40 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  *N bytes of memo
10d50 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  ry..** ^SQLite w
10d60 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20  ill use no more 
10d70 74 68 61 6e 20 74 77 6f 20 73 63 72 61 74 63 68  than two scratch
10d80 20 62 75 66 66 65 72 73 20 70 65 72 20 74 68 72   buffers per thr
10d90 65 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73 68  ead.  So.** N sh
10da0 6f 75 6c 64 20 62 65 20 73 65 74 20 74 6f 20 74  ould be set to t
10db0 77 69 63 65 20 74 68 65 20 65 78 70 65 63 74 65  wice the expecte
10dc0 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  d maximum number
10dd0 20 6f 66 20 74 68 72 65 61 64 73 2e 0a 2a 2a 20   of threads..** 
10de0 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76  ^SQLite will nev
10df0 65 72 20 72 65 71 75 69 72 65 20 61 20 73 63 72  er require a scr
10e00 61 74 63 68 20 62 75 66 66 65 72 20 74 68 61 74  atch buffer that
10e10 20 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a   is more than 6.
10e20 2a 2a 20 74 69 6d 65 73 20 74 68 65 20 64 61 74  ** times the dat
10e30 61 62 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e  abase page size.
10e40 20 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64   ^If SQLite need
10e50 73 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e  s needs addition
10e60 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65  al.** scratch me
10e70 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74  mory beyond what
10e80 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20   is provided by 
10e90 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69  this configurati
10ea0 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20  on option, then 
10eb0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
10ec0 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75  loc()] will be u
10ed0 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68  sed to obtain th
10ee0 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e  e memory needed.
10ef0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
10f00 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
10f10 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49  CACHE]] <dt>SQLI
10f20 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
10f30 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  CHE</dt>.** <dd>
10f40 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70   ^This option sp
10f50 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63  ecifies a static
10f60 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
10f70 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75  hat SQLite can u
10f80 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61  se for.** the da
10f90 74 61 62 61 73 65 20 70 61 67 65 20 63 61 63 68  tabase page cach
10fa0 65 20 77 69 74 68 20 74 68 65 20 64 65 66 61 75  e with the defau
10fb0 6c 74 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  lt page cache im
10fc0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a  plementation.  .
10fd0 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72  ** This configur
10fe0 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74  ation should not
10ff0 20 62 65 20 75 73 65 64 20 69 66 20 61 6e 20 61   be used if an a
11000 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
11010 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20  e page.** cache 
11020 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
11030 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74  s loaded using t
11040 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
11050 5f 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 2e  _PCACHE2 option.
11060 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68  .** There are th
11070 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ree arguments to
11080 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20   this option: A 
11090 70 6f 69 6e 74 65 72 20 74 6f 20 38 2d 62 79 74  pointer to 8-byt
110a0 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d  e aligned.** mem
110b0 6f 72 79 2c 20 74 68 65 20 73 69 7a 65 20 6f 66  ory, the size of
110c0 20 65 61 63 68 20 70 61 67 65 20 62 75 66 66 65   each page buffe
110d0 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20  r (sz), and the 
110e0 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20  number of pages 
110f0 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61  (N)..** The sz a
11100 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62  rgument should b
11110 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  e the size of th
11120 65 20 6c 61 72 67 65 73 74 20 64 61 74 61 62 61  e largest databa
11130 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f  se page.** (a po
11140 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65  wer of two betwe
11150 65 6e 20 35 31 32 20 61 6e 64 20 33 32 37 36 38  en 512 and 32768
11160 29 20 70 6c 75 73 20 61 20 6c 69 74 74 6c 65 20  ) plus a little 
11170 65 78 74 72 61 20 66 6f 72 20 65 61 63 68 0a 2a  extra for each.*
11180 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e 20 20  * page header.  
11190 5e 54 68 65 20 70 61 67 65 20 68 65 61 64 65 72  ^The page header
111a0 20 73 69 7a 65 20 69 73 20 32 30 20 74 6f 20 34   size is 20 to 4
111b0 30 20 62 79 74 65 73 20 64 65 70 65 6e 64 69 6e  0 bytes dependin
111c0 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f 73 74  g on.** the host
111d0 20 61 72 63 68 69 74 65 63 74 75 72 65 2e 20 20   architecture.  
111e0 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c  ^It is harmless,
111f0 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20   apart from the 
11200 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a  wasted memory,.*
11210 2a 20 74 6f 20 6d 61 6b 65 20 73 7a 20 61 20 6c  * to make sz a l
11220 69 74 74 6c 65 20 74 6f 6f 20 6c 61 72 67 65 2e  ittle too large.
11230 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61    The first.** a
11240 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70  rgument should p
11250 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63  oint to an alloc
11260 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73  ation of at leas
11270 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20  t sz*N bytes of 
11280 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69  memory..** ^SQLi
11290 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20  te will use the 
112a0 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20  memory provided 
112b0 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67  by the first arg
112c0 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79  ument to satisfy
112d0 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e   its.** memory n
112e0 65 65 64 73 20 66 6f 72 20 74 68 65 20 66 69 72  eeds for the fir
112f0 73 74 20 4e 20 70 61 67 65 73 20 74 68 61 74 20  st N pages that 
11300 69 74 20 61 64 64 73 20 74 6f 20 63 61 63 68 65  it adds to cache
11310 2e 20 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61  .  ^If additiona
11320 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20  l.** page cache 
11330 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64  memory is needed
11340 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20   beyond what is 
11350 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73  provided by this
11360 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a   option, then.**
11370 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20   SQLite goes to 
11380 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
11390 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69 74  )] for the addit
113a0 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70  ional storage sp
113b0 61 63 65 2e 0a 2a 2a 20 54 68 65 20 70 6f 69 6e  ace..** The poin
113c0 74 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74  ter in the first
113d0 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 0a 2a   argument must.*
113e0 2a 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20  * be aligned to 
113f0 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61  an 8-byte bounda
11400 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74  ry or subsequent
11410 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c   behavior of SQL
11420 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 75  ite.** will be u
11430 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a  ndefined.</dd>.*
11440 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
11450 4e 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e  NFIG_HEAP]] <dt>
11460 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
11470 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  AP</dt>.** <dd> 
11480 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65  ^This option spe
11490 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
114a0 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68  memory buffer th
114b0 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  at SQLite will u
114c0 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66  se.** for all of
114d0 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d   its dynamic mem
114e0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
114f0 65 65 64 73 20 62 65 79 6f 6e 64 20 74 68 6f 73  eeds beyond thos
11500 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f  e provided.** fo
11510 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  r by [SQLITE_CON
11520 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64  FIG_SCRATCH] and
11530 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
11540 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54  PAGECACHE]..** T
11550 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
11560 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62  rguments: An 8-b
11570 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e  yte aligned poin
11580 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72  ter to the memor
11590 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  y,.** the number
115a0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
115b0 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20   memory buffer, 
115c0 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20  and the minimum 
115d0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e  allocation size.
115e0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73  .** ^If the firs
115f0 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d  t pointer (the m
11600 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69  emory pointer) i
11610 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c  s NULL, then SQL
11620 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74  ite reverts.** t
11630 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 61  o using its defa
11640 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ult memory alloc
11650 61 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d  ator (the system
11660 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d   malloc() implem
11670 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e  entation),.** un
11680 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20  doing any prior 
11690 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53  invocation of [S
116a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
116b0 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a  LOC].  ^If the.*
116c0 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  * memory pointer
116d0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64   is not NULL and
116e0 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
116f0 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20  ENABLE_MEMSYS3] 
11700 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  or.** [SQLITE_EN
11710 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72  ABLE_MEMSYS5] ar
11720 65 20 64 65 66 69 6e 65 64 2c 20 74 68 65 6e 20  e defined, then 
11730 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20  the alternative 
11740 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
11750 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74  tor is engaged t
11760 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20  o handle all of 
11770 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61  SQLites memory a
11780 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
11790 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f  .** The first po
117a0 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72  inter (the memor
117b0 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20  y pointer) must 
117c0 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  be aligned to an
117d0 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64   8-byte.** bound
117e0 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e  ary or subsequen
117f0 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51  t behavior of SQ
11800 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64  Lite will be und
11810 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d  efined..** The m
11820 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f  inimum allocatio
11830 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70 65 64  n size is capped
11840 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f   at 2**12. Reaso
11850 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20  nable values.** 
11860 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20  for the minimum 
11870 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20  allocation size 
11880 61 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68  are 2**5 through
11890 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a   2**8.</dd>.**.*
118a0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
118b0 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51  G_MUTEX]] <dt>SQ
118c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
118d0 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  X</dt>.** <dd> ^
118e0 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
118f0 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
11900 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
11910 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
11920 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
11930 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
11940 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
11950 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e  re.  The argumen
11960 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61  t specifies.** a
11970 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c  lternative low-l
11980 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69  evel mutex routi
11990 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69  nes to be used i
119a0 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d  n place.** the m
119b0 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75  utex routines bu
119c0 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
119d0 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65  )^  ^SQLite make
119e0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  s a copy of the.
119f0 2a 2a 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  ** content of th
11a00 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
11a10 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
11a20 75 72 65 20 62 65 66 6f 72 65 20 74 68 65 20 63  ure before the c
11a30 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
11a40 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74  e3_config()] ret
11a50 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65  urns. ^If SQLite
11a60 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
11a70 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
11a80 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
11a90 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
11aa0 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
11ab0 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74  option then.** t
11ac0 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69  he entire mutexi
11ad0 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20  ng subsystem is 
11ae0 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
11af0 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65   build and hence
11b00 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
11b10 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
11b20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
11b30 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e  CONFIG_MUTEX con
11b40 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
11b50 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e  n will.** return
11b60 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e   [SQLITE_ERROR].
11b70 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
11b80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
11b90 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  UTEX]] <dt>SQLIT
11ba0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
11bb0 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  X</dt>.** <dd> ^
11bc0 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
11bd0 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
11be0 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
11bf0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
11c00 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
11c10 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
11c20 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
11c30 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c  re.  The.** [sql
11c40 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
11c50 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  ds].** structure
11c60 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
11c70 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65  the currently de
11c80 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74  fined mutex rout
11c90 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20  ines.)^.** This 
11ca0 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
11cb0 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74  ed to overload t
11cc0 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78  he default mutex
11cd0 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72   allocation.** r
11ce0 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77  outines with a w
11cf0 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 74  rapper used to t
11d00 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65  rack mutex usage
11d10 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65   for performance
11d20 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72  .** profiling or
11d30 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78   testing, for ex
11d40 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c  ample.   ^If SQL
11d50 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
11d60 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
11d70 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
11d80 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
11d90 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
11da0 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
11db0 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74  * the entire mut
11dc0 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20  exing subsystem 
11dd0 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
11de0 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65  the build and he
11df0 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  nce calls to.** 
11e00 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
11e10 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  )] with the SQLI
11e20 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
11e30 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  EX configuration
11e40 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20   option will.** 
11e50 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
11e60 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  RROR].</dd>.**.*
11e70 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
11e80 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64  G_LOOKASIDE]] <d
11e90 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
11ea0 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a  LOOKASIDE</dt>.*
11eb0 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70  * <dd> ^(This op
11ec0 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61  tion takes two a
11ed0 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65  rguments that de
11ee0 74 65 72 6d 69 6e 65 20 74 68 65 20 64 65 66 61  termine the defa
11ef0 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  ult.** memory al
11f00 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 74 68 65  location for the
11f10 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
11f20 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20 65  y allocator on e
11f30 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  ach.** [database
11f40 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54   connection].  T
11f50 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
11f60 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65  t is the.** size
11f70 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69   of each lookasi
11f80 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61  de buffer slot a
11f90 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73  nd the second is
11fa0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
11fb0 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65  * slots allocate
11fc0 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61  d to each databa
11fd0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e  se connection.)^
11fe0 20 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20    ^(This option 
11ff0 73 65 74 73 20 74 68 65 0a 2a 2a 20 3c 69 3e 64  sets the.** <i>d
12000 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61  efault</i> looka
12010 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b  side size. The [
12020 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
12030 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 65  LOOKASIDE].** ve
12040 72 62 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64  rb to [sqlite3_d
12050 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20  b_config()] can 
12060 62 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67  be used to chang
12070 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a  e the lookaside.
12080 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
12090 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63   on individual c
120a0 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f  onnections.)^ </
120b0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
120c0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
120d0 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  2]] <dt>SQLITE_C
120e0 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64  ONFIG_PCACHE2</d
120f0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
12100 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
12110 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
12120 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
12130 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71  ter to.** an [sq
12140 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
12150 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20  hods2] object.  
12160 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63  This object spec
12170 69 66 69 65 73 20 74 68 65 20 69 6e 74 65 72 66  ifies the interf
12180 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74  ace.** to a cust
12190 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  om page cache im
121a0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 20  plementation.)^ 
121b0 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61   ^SQLite makes a
121c0 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
121d0 6f 62 6a 65 63 74 20 61 6e 64 20 75 73 65 73 20  object and uses 
121e0 69 74 20 66 6f 72 20 70 61 67 65 20 63 61 63 68  it for page cach
121f0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
12200 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ions.</dd>.**.**
12210 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
12220 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64  _GETPCACHE2]] <d
12230 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
12240 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a  GETPCACHE2</dt>.
12250 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
12260 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
12270 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
12280 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
12290 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   to an.** [sqlit
122a0 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
122b0 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c  s2] object.  SQL
122c0 69 74 65 20 63 6f 70 69 65 73 20 6f 66 20 74 68  ite copies of th
122d0 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 70 61 67  e current.** pag
122e0 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
122f0 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74  tation into that
12300 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e   object.)^ </dd>
12310 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
12320 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74  CONFIG_LOG]] <dt
12330 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  >SQLITE_CONFIG_L
12340 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OG</dt>.** <dd> 
12350 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
12360 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61  IG_LOG option ta
12370 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  kes two argument
12380 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  s: a pointer to 
12390 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69  a.** function wi
123a0 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74  th a call signat
123b0 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76  ure of void(*)(v
123c0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  oid*,int,const c
123d0 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61  har*), .** and a
123e0 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64   pointer to void
123f0 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69  . ^If the functi
12400 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  on pointer is no
12410 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a  t NULL, it is.**
12420 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c   invoked by [sql
12430 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70  ite3_log()] to p
12440 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67  rocess each logg
12450 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20  ing event.  ^If 
12460 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  the.** function 
12470 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c  pointer is NULL,
12480 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f   the [sqlite3_lo
12490 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62  g()] interface b
124a0 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a  ecomes a no-op..
124b0 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69  ** ^The void poi
124c0 6e 74 65 72 20 74 68 61 74 20 69 73 20 74 68 65  nter that is the
124d0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
124e0 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49   to SQLITE_CONFI
124f0 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73  G_LOG is.** pass
12500 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68  ed through as th
12510 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
12520 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  r to the applica
12530 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67  tion-defined log
12540 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ger.** function 
12550 77 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 75  whenever that fu
12560 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65  nction is invoke
12570 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  d.  ^The second 
12580 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
12590 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74  the logger funct
125a0 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ion is a copy of
125b0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
125c0 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72  eter to the corr
125d0 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71  esponding.** [sq
125e0 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c  lite3_log()] cal
125f0 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65  l and is intende
12600 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c  d to be a [resul
12610 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a  t code] or an.**
12620 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
12630 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74  t code].  ^The t
12640 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 70  hird parameter p
12650 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67  assed to the log
12660 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65  ger is.** log me
12670 73 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d  ssage after form
12680 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69  atting via [sqli
12690 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e  te3_snprintf()].
126a0 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c  .** The SQLite l
126b0 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65  ogging interface
126c0 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e   is not reentran
126d0 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75  t; the logger fu
126e0 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69  nction.** suppli
126f0 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ed by the applic
12700 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69  ation must not i
12710 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65  nvoke any SQLite
12720 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49   interface..** I
12730 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  n a multi-thread
12740 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20  ed application, 
12750 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
12760 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a  defined logger.*
12770 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  * function must 
12780 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c  be threadsafe. <
12790 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
127a0 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d  ITE_CONFIG_URI]]
127b0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
127c0 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 20 54  IG_URI.** <dd> T
127d0 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
127e0 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
127f0 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 20  nt of type int. 
12800 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  If non-zero, the
12810 6e 0a 2a 2a 20 55 52 49 20 68 61 6e 64 6c 69 6e  n.** URI handlin
12820 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e  g is globally en
12830 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61  abled. If the pa
12840 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c  rameter is zero,
12850 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69   then URI handli
12860 6e 67 0a 2a 2a 20 69 73 20 67 6c 6f 62 61 6c 6c  ng.** is globall
12870 79 20 64 69 73 61 62 6c 65 64 2e 20 49 66 20 55  y disabled. If U
12880 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
12890 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2c  lobally enabled,
128a0 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a   all filenames.*
128b0 2a 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c  * passed to [sql
128c0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
128d0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
128e0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
128f0 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63  16()] or.** spec
12900 69 66 69 65 64 20 61 73 20 70 61 72 74 20 6f 66  ified as part of
12910 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e   [ATTACH] comman
12920 64 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  ds are interpret
12930 65 64 20 61 73 20 55 52 49 73 2c 20 72 65 67 61  ed as URIs, rega
12940 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65  rdless.** of whe
12950 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
12960 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
12970 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68  ] flag is set wh
12980 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  en the database.
12990 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  ** connection is
129a0 20 6f 70 65 6e 65 64 2e 20 49 66 20 69 74 20 69   opened. If it i
129b0 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62  s globally disab
129c0 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61  led, filenames a
129d0 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72  re.** only inter
129e0 70 72 65 74 65 64 20 61 73 20 55 52 49 73 20 69  preted as URIs i
129f0 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45  f the SQLITE_OPE
12a00 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 20 73 65  N_URI flag is se
12a10 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61  t when the.** da
12a20 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
12a30 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 42 79 20  n is opened. By 
12a40 64 65 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e  default, URI han
12a50 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
12a60 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54  y.** disabled. T
12a70 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65  he default value
12a80 20 6d 61 79 20 62 65 20 63 68 61 6e 67 65 64 20   may be changed 
12a90 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74  by compiling wit
12aa0 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
12ab0 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c  _USE_URI] symbol
12ac0 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20   defined..**.** 
12ad0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
12ae0 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54  PCACHE]] [[SQLIT
12af0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
12b00 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  HE]].** <dt>SQLI
12b10 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
12b20 20 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46   and SQLITE_CONF
12b30 49 47 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a 20  IG_GETPCACHE.** 
12b40 3c 64 64 3e 20 54 68 65 73 65 20 6f 70 74 69 6f  <dd> These optio
12b50 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65 74 65 20  ns are obsolete 
12b60 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  and should not b
12b70 65 20 75 73 65 64 20 62 79 20 6e 65 77 20 63 6f  e used by new co
12b80 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65 20  de..** They are 
12b90 72 65 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63  retained for bac
12ba0 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
12bb0 6c 69 74 79 20 62 75 74 20 61 72 65 20 6e 6f 77  lity but are now
12bc0 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 6c   no-ops..** </dl
12bd0 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
12be0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
12bf0 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e  ETHREAD  1  /* n
12c00 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
12c10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
12c20 49 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20  ITHREAD   2  /* 
12c30 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
12c40 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
12c50 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a  IALIZED    3  /*
12c60 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
12c70 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
12c80 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f  LLOC        4  /
12c90 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  * sqlite3_mem_me
12ca0 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
12cb0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
12cc0 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20  GETMALLOC     5 
12cd0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f   /* sqlite3_mem_
12ce0 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
12cf0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
12d00 47 5f 53 43 52 41 54 43 48 20 20 20 20 20 20 20  G_SCRATCH       
12d10 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  6  /* void*, int
12d20 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64   sz, int N */.#d
12d30 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
12d40 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 20 20  FIG_PAGECACHE   
12d50 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    7  /* void*, i
12d60 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a  nt sz, int N */.
12d70 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
12d80 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20 20  ONFIG_HEAP      
12d90 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c      8  /* void*,
12da0 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20   int nByte, int 
12db0 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  min */.#define S
12dc0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
12dd0 53 54 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a  STATUS     9  /*
12de0 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66   boolean */.#def
12df0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
12e00 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20 31  G_MUTEX        1
12e10 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  0  /* sqlite3_mu
12e20 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
12e30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
12e40 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20  ONFIG_GETMUTEX  
12e50 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65     11  /* sqlite
12e60 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a  3_mutex_methods*
12e70 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c   */./* previousl
12e80 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  y SQLITE_CONFIG_
12e90 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68  CHUNKALLOC 12 wh
12ea0 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65  ich is now unuse
12eb0 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53  d. */ .#define S
12ec0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
12ed0 4b 41 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a  KASIDE    13  /*
12ee0 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66   int int */.#def
12ef0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
12f00 47 5f 50 43 41 43 48 45 20 20 20 20 20 20 20 31  G_PCACHE       1
12f10 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23  4  /* no-op */.#
12f20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
12f30 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 20 20  NFIG_GETPCACHE  
12f40 20 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a    15  /* no-op *
12f50 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
12f60 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20  _CONFIG_LOG     
12f70 20 20 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e       16  /* xFun
12f80 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66  c, void* */.#def
12f90 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
12fa0 47 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 31  G_URI          1
12fb0 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65  7  /* int */.#de
12fc0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
12fd0 49 47 5f 50 43 41 43 48 45 32 20 20 20 20 20 20  IG_PCACHE2      
12fe0 31 38 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70  18  /* sqlite3_p
12ff0 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20  cache_methods2* 
13000 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
13010 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
13020 48 45 32 20 20 20 31 39 20 20 2f 2a 20 73 71 6c  HE2   19  /* sql
13030 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
13040 6f 64 73 32 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  ods2* */../*.** 
13050 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61  CAPI3REF: Databa
13060 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f  se Connection Co
13070 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69  nfiguration Opti
13080 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
13090 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68  constants are th
130a0 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65  e available inte
130b0 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ger configuratio
130c0 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a  n options that.*
130d0 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20  * can be passed 
130e0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  as the second ar
130f0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73  gument to the [s
13100 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
13110 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
13120 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75  *.** New configu
13130 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
13140 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
13150 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
13160 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69  f SQLite..** Exi
13170 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  sting configurat
13180 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68  ion options migh
13190 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65  t be discontinue
131a0 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  d.  Applications
131b0 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b  .** should check
131c0 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65   the return code
131d0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64   from [sqlite3_d
131e0 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d  b_config()] to m
131f0 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a  ake sure that.**
13200 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64   the call worked
13210 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  .  ^The [sqlite3
13220 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  _db_config()] in
13230 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74  terface will ret
13240 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72  urn a.** non-zer
13250 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  o [error code] i
13260 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64  f a discontinued
13270 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20   or unsupported 
13280 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
13290 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b  tion.** is invok
132a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  ed..**.** <dl>.*
132b0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
132c0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c  ONFIG_LOOKASIDE<
132d0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
132e0 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
132f0 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c  three additional
13300 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
13310 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a  determine the .*
13320 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  * [lookaside mem
13330 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63  ory allocator] c
13340 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72  onfiguration for
13350 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
13360 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e  onnection]..** ^
13370 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
13380 6e 74 20 28 74 68 65 20 74 68 69 72 64 20 70 61  nt (the third pa
13390 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
133a0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
133b0 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72   is a.** pointer
133c0 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75 66   to a memory buf
133d0 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c  fer to use for l
133e0 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e  ookaside memory.
133f0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
13400 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74 68  rgument after th
13410 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
13420 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72 62  G_LOOKASIDE verb
13430 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20  .** may be NULL 
13440 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 53 51  in which case SQ
13450 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61  Lite will alloca
13460 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73  te the.** lookas
13470 69 64 65 20 62 75 66 66 65 72 20 69 74 73 65 6c  ide buffer itsel
13480 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  f using [sqlite3
13490 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65  _malloc()]. ^The
134a0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
134b0 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20   is the.** size 
134c0 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64  of each lookasid
134d0 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20 20  e buffer slot.  
134e0 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d  ^The third argum
134f0 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ent is the numbe
13500 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20  r of.** slots.  
13510 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  The size of the 
13520 62 75 66 66 65 72 20 69 6e 20 74 68 65 20 66 69  buffer in the fi
13530 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73  rst argument mus
13540 74 20 62 65 20 67 72 65 61 74 65 72 20 74 68 61  t be greater tha
13550 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f  n.** or equal to
13560 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20   the product of 
13570 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74  the second and t
13580 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 20  hird arguments. 
13590 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d   The buffer.** m
135a0 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74  ust be aligned t
135b0 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e  o an 8-byte boun
135c0 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20 73  dary.  ^If the s
135d0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
135e0 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f  o.** SQLITE_DBCO
135f0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69  NFIG_LOOKASIDE i
13600 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65  s not a multiple
13610 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e 74   of 8, it is int
13620 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64  ernally.** round
13630 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e  ed down to the n
13640 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c 74  ext smaller mult
13650 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54 68  iple of 8.  ^(Th
13660 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  e lookaside memo
13670 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  ry.** configurat
13680 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61 62 61  ion for a databa
13690 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61  se connection ca
136a0 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67 65  n only be change
136b0 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20 63  d when that.** c
136c0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74  onnection is not
136d0 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e 67   currently using
136e0 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
136f0 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72 20 77  y, or in other w
13700 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68 65  ords.** when the
13710 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75 65 22   "current value"
13720 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
13730 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74  [sqlite3_db_stat
13740 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43 4f  us](D,[SQLITE_CO
13750 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c  NFIG_LOOKASIDE],
13760 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a  ...) is zero..**
13770 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   Any attempt to 
13780 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61  change the looka
13790 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 66  side memory conf
137a0 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e 20 6c  iguration when l
137b0 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f  ookaside.** memo
137c0 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c 65 61  ry is in use lea
137d0 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67 75 72  ves the configur
137e0 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64 20  ation unchanged 
137f0 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20  and returns .** 
13800 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29 5e  [SQLITE_BUSY].)^
13810 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
13820 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
13830 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e  ENABLE_FKEY</dt>
13840 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
13850 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ption is used to
13860 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62   enable or disab
13870 6c 65 20 74 68 65 20 65 6e 66 6f 72 63 65 6d 65  le the enforceme
13880 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67  nt of.** [foreig
13890 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74  n key constraint
138a0 73 5d 2e 20 20 54 68 65 72 65 20 73 68 6f 75 6c  s].  There shoul
138b0 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f  d be two additio
138c0 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a  nal arguments..*
138d0 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
138e0 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67  ment is an integ
138f0 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f  er which is 0 to
13900 20 64 69 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f   disable FK enfo
13910 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69  rcement,.** posi
13920 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 46  tive to enable F
13930 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72  K enforcement or
13940 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61   negative to lea
13950 76 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  ve FK enforcemen
13960 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20  t.** unchanged. 
13970 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
13980 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74  meter is a point
13990 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
139a0 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69   into which.** i
139b0 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31  s written 0 or 1
139c0 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65   to indicate whe
139d0 74 68 65 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d  ther FK enforcem
139e0 65 6e 74 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e  ent is off or on
139f0 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  .** following th
13a00 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65  is call.  The se
13a10 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d  cond parameter m
13a20 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  ay be a NULL poi
13a30 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63  nter, in.** whic
13a40 68 20 63 61 73 65 20 74 68 65 20 46 4b 20 65 6e  h case the FK en
13a50 66 6f 72 63 65 6d 65 6e 74 20 73 65 74 74 69 6e  forcement settin
13a60 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65  g is not reporte
13a70 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a  d back. </dd>.**
13a80 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
13a90 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54  BCONFIG_ENABLE_T
13aa0 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c  RIGGER</dt>.** <
13ab0 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
13ac0 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62   is used to enab
13ad0 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 5b 43  le or disable [C
13ae0 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20  REATE TRIGGER | 
13af0 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68  triggers]..** Th
13b00 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77  ere should be tw
13b10 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  o additional arg
13b20 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66  uments..** The f
13b30 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
13b40 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
13b50 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  h is 0 to disabl
13b60 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70  e triggers,.** p
13b70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c  ositive to enabl
13b80 65 20 74 72 69 67 67 65 72 73 20 6f 72 20 6e 65  e triggers or ne
13b90 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20  gative to leave 
13ba0 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68  the setting unch
13bb0 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65  anged..** The se
13bc0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
13bd0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
13be0 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77  n integer into w
13bf0 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74  hich.** is writt
13c00 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64  en 0 or 1 to ind
13c10 69 63 61 74 65 20 77 68 65 74 68 65 72 20 74 72  icate whether tr
13c20 69 67 67 65 72 73 20 61 72 65 20 64 69 73 61 62  iggers are disab
13c30 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a  led or enabled.*
13c40 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73  * following this
13c50 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f   call.  The seco
13c60 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  nd parameter may
13c70 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   be a NULL point
13c80 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20  er, in.** which 
13c90 63 61 73 65 20 74 68 65 20 74 72 69 67 67 65 72  case the trigger
13ca0 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20   setting is not 
13cb0 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c  reported back. <
13cc0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e  /dd>.**.** </dl>
13cd0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
13ce0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
13cf0 41 53 49 44 45 20 20 20 20 20 20 20 31 30 30 31  ASIDE       1001
13d00 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69    /* void* int i
13d10 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nt */.#define SQ
13d20 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
13d30 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 31 30  ABLE_FKEY     10
13d40 30 32 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20  02  /* int int* 
13d50 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
13d60 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
13d70 45 5f 54 52 49 47 47 45 52 20 20 31 30 30 33 20  E_TRIGGER  1003 
13d80 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a   /* int int* */.
13d90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
13da0 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61  : Enable Or Disa
13db0 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73  ble Extended Res
13dc0 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  ult Codes.**.** 
13dd0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74  ^The sqlite3_ext
13de0 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
13df0 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61  es() routine ena
13e00 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73  bles or disables
13e10 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65   the.** [extende
13e20 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20  d result codes] 
13e30 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74  feature of SQLit
13e40 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64  e. ^The extended
13e50 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73   result.** codes
13e60 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79   are disabled by
13e70 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73   default for his
13e80 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62  torical compatib
13e90 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ility..*/.int sq
13ea0 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
13eb0 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69  esult_codes(sqli
13ec0 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29  te3*, int onoff)
13ed0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
13ee0 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52  F: Last Insert R
13ef0 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68  owid.**.** ^Each
13f00 20 65 6e 74 72 79 20 69 6e 20 61 6e 20 53 51 4c   entry in an SQL
13f10 69 74 65 20 74 61 62 6c 65 20 68 61 73 20 61 20  ite table has a 
13f20 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 69  unique 64-bit si
13f30 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  gned.** integer 
13f40 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b  key called the [
13f50 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d  ROWID | "rowid"]
13f60 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20  . ^The rowid is 
13f70 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65  always available
13f80 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c  .** as an undecl
13f90 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65  ared column name
13fa0 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72  d ROWID, OID, or
13fb0 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67   _ROWID_ as long
13fc0 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d   as those.** nam
13fd0 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20  es are not also 
13fe0 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 74  used by explicit
13ff0 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75  ly declared colu
14000 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20  mns. ^If.** the 
14010 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75  table has a colu
14020 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45  mn of type [INTE
14030 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d  GER PRIMARY KEY]
14040 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d   then that colum
14050 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20  n.** is another 
14060 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f  alias for the ro
14070 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  wid..**.** ^This
14080 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
14090 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20   the [rowid] of 
140a0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a  the most recent.
140b0 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  ** successful [I
140c0 4e 53 45 52 54 5d 20 69 6e 74 6f 20 74 68 65 20  NSERT] into the 
140d0 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20 74 68  database from th
140e0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
140f0 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68  ection].** in th
14100 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
14110 2e 20 20 5e 41 73 20 6f 66 20 53 51 4c 69 74 65  .  ^As of SQLite
14120 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20   version 3.7.7, 
14130 74 68 69 73 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  this routines.**
14140 20 72 65 63 6f 72 64 73 20 74 68 65 20 6c 61 73   records the las
14150 74 20 69 6e 73 65 72 74 20 72 6f 77 69 64 20 6f  t insert rowid o
14160 66 20 62 6f 74 68 20 6f 72 64 69 6e 61 72 79 20  f both ordinary 
14170 74 61 62 6c 65 73 20 61 6e 64 20 5b 76 69 72 74  tables and [virt
14180 75 61 6c 20 74 61 62 6c 65 73 5d 2e 0a 2a 2a 20  ual tables]..** 
14190 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75  ^If no successfu
141a0 6c 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a 20 68  l [INSERT]s.** h
141b0 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65  ave ever occurre
141c0 64 20 6f 6e 20 74 68 61 74 20 64 61 74 61 62 61  d on that databa
141d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a  se connection, z
141e0 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ero is returned.
141f0 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b  .**.** ^(If an [
14200 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77  INSERT] occurs w
14210 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20  ithin a trigger 
14220 6f 72 20 77 69 74 68 69 6e 20 61 20 5b 76 69 72  or within a [vir
14230 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d  tual table].** m
14240 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 69 73  ethod, then this
14250 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 65   routine will re
14260 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d  turn the [rowid]
14270 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64   of the inserted
14280 0a 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20  .** row as long 
14290 61 73 20 74 68 65 20 74 72 69 67 67 65 72 20 6f  as the trigger o
142a0 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  r virtual table 
142b0 6d 65 74 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e  method is runnin
142c0 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74  g..** But once t
142d0 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  he trigger or vi
142e0 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68  rtual table meth
142f0 6f 64 20 65 6e 64 73 2c 20 74 68 65 20 76 61 6c  od ends, the val
14300 75 65 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20  ue returned .** 
14310 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  by this routine 
14320 72 65 76 65 72 74 73 20 74 6f 20 77 68 61 74 20  reverts to what 
14330 69 74 20 77 61 73 20 62 65 66 6f 72 65 20 74 68  it was before th
14340 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72  e trigger or vir
14350 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65  tual.** table me
14360 74 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a  thod began.)^.**
14370 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d  .** ^An [INSERT]
14380 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20   that fails due 
14390 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20  to a constraint 
143a0 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74  violation is not
143b0 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c   a.** successful
143c0 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f   [INSERT] and do
143d0 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
143e0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
143f0 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74   by this.** rout
14400 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45  ine.  ^Thus INSE
14410 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45  RT OR FAIL, INSE
14420 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e  RT OR IGNORE, IN
14430 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b  SERT OR ROLLBACK
14440 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20  ,.** and INSERT 
14450 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f  OR ABORT make no
14460 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20   changes to the 
14470 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
14480 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  this.** routine 
14490 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72  when their inser
144a0 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57  tion fails.  ^(W
144b0 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45  hen INSERT OR RE
144c0 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74  PLACE.** encount
144d0 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74  ers a constraint
144e0 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64   violation, it d
144f0 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54  oes not fail.  T
14500 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e  he.** INSERT con
14510 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65  tinues to comple
14520 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74  tion after delet
14530 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61  ing rows that ca
14540 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73  used.** the cons
14550 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73  traint problem s
14560 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c  o INSERT OR REPL
14570 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ACE will always 
14580 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65  change.** the re
14590 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
145a0 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a  is interface.)^.
145b0 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70  **.** ^For the p
145c0 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20  urposes of this 
145d0 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53  routine, an [INS
145e0 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72  ERT] is consider
145f0 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63  ed to.** be succ
14600 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69  essful even if i
14610 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c  t is subsequentl
14620 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a  y rolled back..*
14630 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
14640 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c 65  on is accessible
14650 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   to SQL statemen
14660 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c  ts via the.** [l
14670 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
14680 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
14690 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70  ..**.** If a sep
146a0 61 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72  arate thread per
146b0 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53  forms a new [INS
146c0 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65  ERT] on the same
146d0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
146e0 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68  nection while th
146f0 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  e [sqlite3_last_
14700 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a  insert_rowid()].
14710 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  ** function is r
14720 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20  unning and thus 
14730 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74  changes the last
14740 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c   insert [rowid],
14750 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c  .** then the val
14760 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  ue returned by [
14770 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
14780 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a  ert_rowid()] is.
14790 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  ** unpredictable
147a0 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65   and might not e
147b0 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20  qual either the 
147c0 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a  old or the new.*
147d0 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72  * last insert [r
147e0 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65  owid]..*/.sqlite
147f0 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
14800 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
14810 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  d(sqlite3*);../*
14820 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
14830 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f  unt The Number O
14840 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a  f Rows Modified.
14850 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
14860 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
14870 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62   number of datab
14880 61 73 65 20 72 6f 77 73 20 74 68 61 74 20 77 65  ase rows that we
14890 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72  re changed.** or
148a0 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c   inserted or del
148b0 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74  eted by the most
148c0 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65   recently comple
148d0 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
148e0 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74  t.** on the [dat
148f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
14900 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  ] specified by t
14910 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
14920 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68  er..** ^(Only ch
14930 61 6e 67 65 73 20 74 68 61 74 20 61 72 65 20 64  anges that are d
14940 69 72 65 63 74 6c 79 20 73 70 65 63 69 66 69 65  irectly specifie
14950 64 20 62 79 20 74 68 65 20 5b 49 4e 53 45 52 54  d by the [INSERT
14960 5d 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20  ], [UPDATE],.** 
14970 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74  or [DELETE] stat
14980 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65  ement are counte
14990 64 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63 68  d.  Auxiliary ch
149a0 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 0a  anges caused by.
149b0 2a 2a 20 74 72 69 67 67 65 72 73 20 6f 72 20 5b  ** triggers or [
149c0 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69  foreign key acti
149d0 6f 6e 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75  ons] are not cou
149e0 6e 74 65 64 2e 29 5e 20 55 73 65 20 74 68 65 0a  nted.)^ Use the.
149f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  ** [sqlite3_tota
14a00 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e  l_changes()] fun
14a10 63 74 69 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68  ction to find th
14a20 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f  e total number o
14a30 66 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63  f changes.** inc
14a40 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63  luding changes c
14a50 61 75 73 65 64 20 62 79 20 74 72 69 67 67 65 72  aused by trigger
14a60 73 20 61 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65  s and foreign ke
14a70 79 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  y actions..**.**
14a80 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76   ^Changes to a v
14a90 69 65 77 20 74 68 61 74 20 61 72 65 20 73 69 6d  iew that are sim
14aa0 75 6c 61 74 65 64 20 62 79 20 61 6e 20 5b 49 4e  ulated by an [IN
14ab0 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
14ac0 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75  ].** are not cou
14ad0 6e 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c  nted.  Only real
14ae0 20 74 61 62 6c 65 20 63 68 61 6e 67 65 73 20 61   table changes a
14af0 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a  re counted..**.*
14b00 2a 20 5e 28 41 20 22 72 6f 77 20 63 68 61 6e 67  * ^(A "row chang
14b10 65 22 20 69 73 20 61 20 63 68 61 6e 67 65 20 74  e" is a change t
14b20 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f  o a single row o
14b30 66 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65  f a single table
14b40 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e  .** caused by an
14b50 20 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c   INSERT, DELETE,
14b60 20 6f 72 20 55 50 44 41 54 45 20 73 74 61 74 65   or UPDATE state
14b70 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74  ment.  Rows that
14b80 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20  .** are changed 
14b90 61 73 20 73 69 64 65 20 65 66 66 65 63 74 73 20  as side effects 
14ba0 6f 66 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e  of [REPLACE] con
14bb0 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69  straint resoluti
14bc0 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c  on,.** rollback,
14bd0 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e   ABORT processin
14be0 67 2c 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c  g, [DROP TABLE],
14bf0 20 6f 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72   or by any other
14c00 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64  .** mechanisms d
14c10 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64  o not count as d
14c20 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65  irect row change
14c30 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72  s.)^.**.** A "tr
14c40 69 67 67 65 72 20 63 6f 6e 74 65 78 74 22 20 69  igger context" i
14c50 73 20 61 20 73 63 6f 70 65 20 6f 66 20 65 78 65  s a scope of exe
14c60 63 75 74 69 6f 6e 20 74 68 61 74 20 62 65 67 69  cution that begi
14c70 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77  ns and.** ends w
14c80 69 74 68 20 74 68 65 20 73 63 72 69 70 74 20 6f  ith the script o
14c90 66 20 61 20 5b 43 52 45 41 54 45 20 54 52 49 47  f a [CREATE TRIG
14ca0 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d 2e 20  GER | trigger]. 
14cb0 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c 20 73 74 61  .** Most SQL sta
14cc0 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65  tements are.** e
14cd0 76 61 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65  valuated outside
14ce0 20 6f 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e   of any trigger.
14cf0 20 20 54 68 69 73 20 69 73 20 74 68 65 20 22 74    This is the "t
14d00 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69  op level".** tri
14d10 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49  gger context.  I
14d20 66 20 61 20 74 72 69 67 67 65 72 20 66 69 72 65  f a trigger fire
14d30 73 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c  s from the top l
14d40 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74  evel, a.** new t
14d50 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69  rigger context i
14d60 73 20 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68  s entered for th
14d70 65 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68  e duration of th
14d80 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65  at one.** trigge
14d90 72 2e 20 20 53 75 62 74 72 69 67 67 65 72 73 20  r.  Subtriggers 
14da0 63 72 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78  create subcontex
14db0 74 73 20 66 6f 72 20 74 68 65 69 72 20 64 75 72  ts for their dur
14dc0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61  ation..**.** ^Ca
14dd0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65  lling [sqlite3_e
14de0 78 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  xec()] or [sqlit
14df0 65 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72  e3_step()] recur
14e00 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e  sively does.** n
14e10 6f 74 20 63 72 65 61 74 65 20 61 20 6e 65 77 20  ot create a new 
14e20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e  trigger context.
14e30 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
14e40 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
14e50 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65  e number of dire
14e60 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69  ct row changes i
14e70 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65  n the.** most re
14e80 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44  cent INSERT, UPD
14e90 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73  ATE, or DELETE s
14ea0 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
14eb0 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67  the same.** trig
14ec0 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a  ger context..**.
14ed0 2a 2a 20 5e 54 68 75 73 2c 20 77 68 65 6e 20 63  ** ^Thus, when c
14ee0 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74  alled from the t
14ef0 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66  op level, this f
14f00 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
14f10 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
14f20 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20   changes in the 
14f30 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45  most recent INSE
14f40 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
14f50 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c  ELETE.** that al
14f60 73 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20 74  so occurred at t
14f70 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e  he top level.  ^
14f80 28 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79  (Within the body
14f90 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c 0a 2a   of a trigger,.*
14fa0 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68  * the sqlite3_ch
14fb0 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61 63  anges() interfac
14fc0 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  e can be called 
14fd0 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62  to find the numb
14fe0 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73  er of.** changes
14ff0 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63   in the most rec
15000 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20  ently completed 
15010 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
15020 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61  or DELETE.** sta
15030 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68  tement within th
15040 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61  e body of the sa
15050 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48  me trigger..** H
15060 6f 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62  owever, the numb
15070 65 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73  er returned does
15080 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61   not include cha
15090 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62  nges.** caused b
150a0 79 20 73 75 62 74 72 69 67 67 65 72 73 20 73 69  y subtriggers si
150b0 6e 63 65 20 74 68 6f 73 65 20 68 61 76 65 20 74  nce those have t
150c0 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74  heir own context
150d0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  .)^.**.** See al
150e0 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  so the [sqlite3_
150f0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
15100 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a   interface, the.
15110 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65  ** [count_change
15120 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74  s pragma], and t
15130 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51  he [changes() SQ
15140 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a  L function]..**.
15150 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65  ** If a separate
15160 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68   thread makes ch
15170 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d  anges on the sam
15180 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
15190 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b  ction.** while [
151a0 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
151b0 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  )] is running th
151c0 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  en the value ret
151d0 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72  urned.** is unpr
151e0 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f  edictable and no
151f0 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f  t meaningful..*/
15200 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61  .int sqlite3_cha
15210 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a  nges(sqlite3*);.
15220 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
15230 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66   Total Number Of
15240 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a   Rows Modified.*
15250 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
15260 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
15270 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68  number of row ch
15280 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
15290 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50  [INSERT],.** [UP
152a0 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45  DATE] or [DELETE
152b0 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e  ] statements sin
152c0 63 65 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  ce the [database
152d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73   connection] was
152e0 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68   opened..** ^(Th
152f0 65 20 63 6f 75 6e 74 20 72 65 74 75 72 6e 65 64  e count returned
15300 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61   by sqlite3_tota
15310 6c 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 63 6c  l_changes() incl
15320 75 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73  udes all changes
15330 0a 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52  .** from all [CR
15340 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74  EATE TRIGGER | t
15350 72 69 67 67 65 72 5d 20 63 6f 6e 74 65 78 74 73  rigger] contexts
15360 20 61 6e 64 20 63 68 61 6e 67 65 73 20 6d 61 64   and changes mad
15370 65 20 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e  e by.** [foreign
15380 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48   key actions]. H
15390 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63  owever,.** the c
153a0 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e  ount does not in
153b0 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75 73  clude changes us
153c0 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
153d0 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72  [REPLACE] constr
153e0 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c  aints,.** do rol
153f0 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20  lbacks or ABORT 
15400 70 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b  processing, or [
15410 44 52 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f 63  DROP TABLE] proc
15420 65 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20  essing.  The.** 
15430 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69  count does not i
15440 6e 63 6c 75 64 65 20 72 6f 77 73 20 6f 66 20 76  nclude rows of v
15450 69 65 77 73 20 74 68 61 74 20 66 69 72 65 20 61  iews that fire a
15460 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72  n [INSTEAD OF tr
15470 69 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67  igger],.** thoug
15480 68 20 69 66 20 74 68 65 20 49 4e 53 54 45 41 44  h if the INSTEAD
15490 20 4f 46 20 74 72 69 67 67 65 72 20 6d 61 6b 65   OF trigger make
154a0 73 20 63 68 61 6e 67 65 73 20 6f 66 20 69 74 73  s changes of its
154b0 20 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e   own, those chan
154c0 67 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e  ges .** are coun
154d0 74 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 73  ted.)^.** ^The s
154e0 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
154f0 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20  nges() function 
15500 63 6f 75 6e 74 73 20 74 68 65 20 63 68 61 6e 67  counts the chang
15510 65 73 20 61 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a  es as soon as.**
15520 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74   the statement t
15530 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69  hat makes them i
15540 73 20 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65  s completed (whe
15550 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  n the statement 
15560 68 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 61 73  handle.** is pas
15570 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  sed to [sqlite3_
15580 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
15590 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
155a0 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )..**.** See als
155b0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
155c0 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66  hanges()] interf
155d0 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75  ace, the.** [cou
155e0 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d  nt_changes pragm
155f0 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74  a], and the [tot
15600 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c  al_changes() SQL
15610 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a   function]..**.*
15620 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
15630 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
15640 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
15650 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
15660 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73  tion.** while [s
15670 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
15680 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69  nges()] is runni
15690 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ng then the valu
156a0 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73  e.** returned is
156b0 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
156c0 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75  nd not meaningfu
156d0 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
156e0 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
156f0 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
15700 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65  * CAPI3REF: Inte
15710 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e  rrupt A Long-Run
15720 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a  ning Query.**.**
15730 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
15740 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69  causes any pendi
15750 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  ng database oper
15760 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61  ation to abort a
15770 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20  nd.** return at 
15780 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70  its earliest opp
15790 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72  ortunity. This r
157a0 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63 61  outine is typica
157b0 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e  lly.** called in
157c0 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75   response to a u
157d0 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20  ser action such 
157e0 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e  as pressing "Can
157f0 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d  cel".** or Ctrl-
15800 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65 72  C where the user
15810 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75   wants a long qu
15820 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f  ery operation to
15830 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61   halt.** immedia
15840 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20  tely..**.** ^It 
15850 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20  is safe to call 
15860 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f  this routine fro
15870 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65  m a thread diffe
15880 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a  rent from the.**
15890 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20   thread that is 
158a0 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e  currently runnin
158b0 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  g the database o
158c0 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69  peration.  But i
158d0 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65  t.** is not safe
158e0 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
158f0 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61  utine with a [da
15900 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
15910 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c  n] that.** is cl
15920 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c  osed or might cl
15930 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74  ose before sqlit
15940 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72  e3_interrupt() r
15950 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49  eturns..**.** ^I
15960 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69  f an SQL operati
15970 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c  on is very nearl
15980 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68  y finished at th
15990 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73  e time when.** s
159a0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
159b0 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68  () is called, th
159c0 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20  en it might not 
159d0 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e  have an opportun
159e0 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74  ity.** to be int
159f0 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67  errupted and mig
15a00 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63  ht continue to c
15a10 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  ompletion..**.**
15a20 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69   ^An SQL operati
15a30 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 72  on that is inter
15a40 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75  rupted will retu
15a50 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  rn [SQLITE_INTER
15a60 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68  RUPT]..** ^If th
15a70 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53 51  e interrupted SQ
15a80 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61  L operation is a
15a90 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  n INSERT, UPDATE
15aa0 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74  , or DELETE.** t
15ab0 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e  hat is inside an
15ac0 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
15ad0 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ction, then the 
15ae0 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 69  entire transacti
15af0 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f  on.** will be ro
15b00 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61  lled back automa
15b10 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  tically..**.** ^
15b20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  The sqlite3_inte
15b30 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73  rrupt(D) call is
15b40 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c   in effect until
15b50 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72   all currently r
15b60 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74  unning.** SQL st
15b70 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74  atements on [dat
15b80 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
15b90 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e  ] D complete.  ^
15ba0 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74  Any new SQL stat
15bb0 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
15bc0 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
15bd0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
15be0 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e  errupt() call an
15bf0 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a  d before the .**
15c00 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65   running stateme
15c10 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f  nts reaches zero
15c20 20 61 72 65 20 69 6e 74 65 72 72 75 70 74 65 64   are interrupted
15c30 20 61 73 20 69 66 20 74 68 65 79 20 68 61 64 20   as if they had 
15c40 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20  been.** running 
15c50 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c  prior to the sql
15c60 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
15c70 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c   call.  ^New SQL
15c80 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
15c90 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
15ca0 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e  after the runnin
15cb0 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e  g statement coun
15cc0 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61  t reaches zero a
15cd0 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74  re.** not effect
15ce0 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65  ed by the sqlite
15cf0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a  3_interrupt()..*
15d00 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  * ^A call to sql
15d10 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44  ite3_interrupt(D
15d20 29 20 74 68 61 74 20 6f 63 63 75 72 73 20 77 68  ) that occurs wh
15d30 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20  en there are no 
15d40 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73  running.** SQL s
15d50 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e  tatements is a n
15d60 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20  o-op and has no 
15d70 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74  effect on SQL st
15d80 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
15d90 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
15da0 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  er the sqlite3_i
15db0 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20  nterrupt() call 
15dc0 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49  returns..**.** I
15dd0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  f the database c
15de0 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73  onnection closes
15df0 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f   while [sqlite3_
15e00 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20  interrupt()].** 
15e10 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
15e20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20  bad things will 
15e30 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a  likely happen..*
15e40 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69  /.void sqlite3_i
15e50 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 33  nterrupt(sqlite3
15e60 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
15e70 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49  REF: Determine I
15e80 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  f An SQL Stateme
15e90 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a  nt Is Complete.*
15ea0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
15eb0 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c 20 64  nes are useful d
15ec0 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69  uring command-li
15ed0 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65  ne input to dete
15ee0 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20  rmine if the.** 
15ef0 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65  currently entere
15f00 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20  d text seems to 
15f10 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20  form a complete 
15f20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72  SQL statement or
15f30 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61  .** if additiona
15f40 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65  l input is neede
15f50 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67  d before sending
15f60 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a   the text into.*
15f70 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72  * SQLite for par
15f80 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f  sing.  ^These ro
15f90 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20  utines return 1 
15fa0 69 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  if the input str
15fb0 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74  ing.** appears t
15fc0 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20  o be a complete 
15fd0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  SQL statement.  
15fe0 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  ^A statement is 
15ff0 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20  judged to be.** 
16000 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65  complete if it e
16010 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d 69 63  nds with a semic
16020 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69  olon token and i
16030 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f  s not a prefix o
16040 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d  f a.** well-form
16050 65 64 20 43 52 45 41 54 45 20 54 52 49 47 47 45  ed CREATE TRIGGE
16060 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53  R statement.  ^S
16070 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61  emicolons that a
16080 72 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 68  re embedded with
16090 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74  in.** string lit
160a0 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20  erals or quoted 
160b0 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73  identifier names
160c0 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65   or comments are
160d0 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64   not.** independ
160e0 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79  ent tokens (they
160f0 20 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 65   are part of the
16100 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20   token in which 
16110 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65  they are.** embe
16120 64 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 64  dded) and thus d
16130 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61  o not count as a
16140 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69   statement termi
16150 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70  nator.  ^Whitesp
16160 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65  ace.** and comme
16170 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20  nts that follow 
16180 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f  the final semico
16190 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e  lon are ignored.
161a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
161b0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20  utines return 0 
161c0 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  if the statement
161d0 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20   is incomplete. 
161e0 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79   ^If a.** memory
161f0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
16200 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e  s, then SQLITE_N
16210 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64  OMEM is returned
16220 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  ..**.** ^These r
16230 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70  outines do not p
16240 61 72 73 65 20 74 68 65 20 53 51 4c 20 73 74 61  arse the SQL sta
16250 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20  tements thus.** 
16260 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20  will not detect 
16270 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e  syntactically in
16280 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a  correct SQL..**.
16290 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68  ** ^(If SQLite h
162a0 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74  as not been init
162b0 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73  ialized using [s
162c0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
162d0 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74  e()] prior .** t
162e0 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74  o invoking sqlit
162f0 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20  e3_complete16() 
16300 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69  then sqlite3_ini
16310 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76  tialize() is inv
16320 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  oked.** automati
16330 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33  cally by sqlite3
16340 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20  _complete16().  
16350 49 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69  If that initiali
16360 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a  zation fails,.**
16370 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e   then the return
16380 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
16390 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
163a0 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72   will be non-zer
163b0 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20  o.** regardless 
163c0 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
163d0 74 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20  t the input SQL 
163e0 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a  is complete.)^.*
163f0 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74  *.** The input t
16400 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  o [sqlite3_compl
16410 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61  ete()] must be a
16420 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
16430 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67  .** UTF-8 string
16440 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75  ..**.** The inpu
16450 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
16460 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74  mplete16()] must
16470 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   be a zero-termi
16480 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20  nated.** UTF-16 
16490 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65  string in native
164a0 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a   byte order..*/.
164b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
164c0 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20  lete(const char 
164d0 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  *sql);.int sqlit
164e0 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f  e3_complete16(co
164f0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a  nst void *sql);.
16500 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
16510 20 52 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c   Register A Call
16520 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53  back To Handle S
16530 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72  QLITE_BUSY Error
16540 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  s.**.** ^This ro
16550 75 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c  utine sets a cal
16560 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74  lback function t
16570 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76  hat might be inv
16580 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a  oked whenever.**
16590 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d   an attempt is m
165a0 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61  ade to open a da
165b0 74 61 62 61 73 65 20 74 61 62 6c 65 20 74 68 61  tabase table tha
165c0 74 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64  t another thread
165d0 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68  .** or process h
165e0 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a  as locked..**.**
165f0 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61   ^If the busy ca
16600 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20  llback is NULL, 
16610 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  then [SQLITE_BUS
16620 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  Y] or [SQLITE_IO
16630 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20  ERR_BLOCKED].** 
16640 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65  is returned imme
16650 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63  diately upon enc
16660 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f  ountering the lo
16670 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73  ck.  ^If the bus
16680 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73  y callback.** is
16690 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20   not NULL, then 
166a0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67  the callback mig
166b0 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  ht be invoked wi
166c0 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  th two arguments
166d0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
166e0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
166f0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
16700 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
16710 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77   void* pointer w
16720 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74  hich.** is the t
16730 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  hird argument to
16740 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
16750 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73  ndler().  ^The s
16760 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
16770 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61  o.** the busy ha
16780 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  ndler callback i
16790 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
167a0 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62  times that the b
167b0 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a  usy handler has.
167c0 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20  ** been invoked 
167d0 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67  for this locking
167e0 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65   event.  ^If the
167f0 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63  .** busy callbac
16800 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65  k returns 0, the
16810 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20  n no additional 
16820 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64  attempts are mad
16830 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74  e to.** access t
16840 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  he database and 
16850 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72  [SQLITE_BUSY] or
16860 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
16870 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72  LOCKED] is retur
16880 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ned..** ^If the 
16890 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
168a0 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
168b0 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a  another attempt.
168c0 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70  ** is made to op
168d0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
168e0 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
168f0 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74  the cycle repeat
16900 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65  s..**.** The pre
16910 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20  sence of a busy 
16920 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74  handler does not
16930 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20   guarantee that 
16940 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b  it will be invok
16950 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65  ed.** when there
16960 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74   is lock content
16970 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20  ion. ^If SQLite 
16980 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20  determines that 
16990 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73  invoking the bus
169a0 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75  y.** handler cou
169b0 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64  ld result in a d
169c0 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c  eadlock, it will
169d0 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65   go ahead and re
169e0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  turn [SQLITE_BUS
169f0 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45  Y].** or [SQLITE
16a00 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20  _IOERR_BLOCKED] 
16a10 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b  instead of invok
16a20 69 6e 67 20 74 68 65 20 62 75 73 79 20 68 61 6e  ing the busy han
16a30 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65  dler..** Conside
16a40 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65  r a scenario whe
16a50 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69  re one process i
16a60 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64  s holding a read
16a70 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74   lock that.** it
16a80 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72   is trying to pr
16a90 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72  omote to a reser
16aa0 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20  ved lock and.** 
16ab0 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  a second process
16ac0 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65   is holding a re
16ad0 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74  served lock that
16ae0 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a   it is trying.**
16af0 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61   to promote to a
16b00 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b  n exclusive lock
16b10 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f  .  The first pro
16b20 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63  cess cannot proc
16b30 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69  eed.** because i
16b40 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20  t is blocked by 
16b50 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74  the second and t
16b60 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73  he second proces
16b70 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63  s cannot.** proc
16b80 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20 69  eed because it i
16b90 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65  s blocked by the
16ba0 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68   first.  If both
16bb0 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e   processes.** in
16bc0 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 61  voke the busy ha
16bd0 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20  ndlers, neither 
16be0 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72  will make any pr
16bf0 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f  ogress.  Therefo
16c00 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65  re,.** SQLite re
16c10 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55  turns [SQLITE_BU
16c20 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73  SY] for the firs
16c30 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e  t process, hopin
16c40 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77  g that this.** w
16c50 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66  ill induce the f
16c60 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20  irst process to 
16c70 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 64  release its read
16c80 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a   lock and allow.
16c90 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72  ** the second pr
16ca0 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64  ocess to proceed
16cb0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66  ..**.** ^The def
16cc0 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61  ault busy callba
16cd0 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ck is NULL..**.*
16ce0 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 42  * ^The [SQLITE_B
16cf0 55 53 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f  USY] error is co
16d00 6e 76 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49  nverted to [SQLI
16d10 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
16d20 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65  ].** when SQLite
16d30 20 69 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c   is in the middl
16d40 65 20 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61  e of a large tra
16d50 6e 73 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61  nsaction where a
16d60 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65  ll the.** change
16d70 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69  s will not fit i
16d80 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72  nto the in-memor
16d90 79 20 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65  y cache.  SQLite
16da0 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79   will.** already
16db0 20 68 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44   hold a RESERVED
16dc0 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74   lock on the dat
16dd0 61 62 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20  abase file, but 
16de0 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70  it needs.** to p
16df0 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b  romote this lock
16e00 20 74 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f   to EXCLUSIVE so
16e10 20 74 68 61 74 20 69 74 20 63 61 6e 20 73 70 69   that it can spi
16e20 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65  ll cache.** page
16e30 73 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62  s into the datab
16e40 61 73 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74  ase file without
16e50 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72   harm to concurr
16e60 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20  ent.** readers. 
16e70 20 5e 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c   ^If it is unabl
16e80 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65  e to promote the
16e90 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20   lock, then the 
16ea0 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63  in-memory.** cac
16eb0 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20  he will be left 
16ec0 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65  in an inconsiste
16ed0 6e 74 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20  nt state and so 
16ee0 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64  the error.** cod
16ef0 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72  e is promoted fr
16f00 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c  om the relativel
16f10 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45  y benign [SQLITE
16f20 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65  _BUSY] to.** the
16f30 20 6d 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51   more severe [SQ
16f40 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
16f50 45 44 5d 2e 20 20 5e 54 68 69 73 20 65 72 72 6f  ED].  ^This erro
16f60 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e  r code promotion
16f70 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75  .** forces an au
16f80 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b  tomatic rollback
16f90 20 6f 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e   of the changes.
16fa0 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20    See the.** <a 
16fb0 68 72 65 66 3d 22 2f 63 76 73 74 72 61 63 2f 77  href="/cvstrac/w
16fc0 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e  iki?p=Corruption
16fd0 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72  FollowingBusyErr
16fe0 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69  or">.** Corrupti
16ff0 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45  onFollowingBusyE
17000 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61  rror</a> wiki pa
17010 67 65 20 66 6f 72 20 61 20 64 69 73 63 75 73 73  ge for a discuss
17020 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68  ion of why.** th
17030 69 73 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e  is is important.
17040 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63  .**.** ^(There c
17050 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e  an only be a sin
17060 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  gle busy handler
17070 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63   defined for eac
17080 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  h.** [database c
17090 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74  onnection].  Set
170a0 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20  ting a new busy 
170b0 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61  handler clears a
170c0 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  ny.** previously
170d0 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20   set handler.)^ 
170e0 20 5e 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c   ^Note that call
170f0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  ing [sqlite3_bus
17100 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20  y_timeout()].** 
17110 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72  will also set or
17120 20 63 6c 65 61 72 20 74 68 65 20 62 75 73 79 20   clear the busy 
17130 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  handler..**.** T
17140 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
17150 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65   should not take
17160 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69   any actions whi
17170 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a  ch modify the.**
17180 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
17190 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
171a0 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  d the busy handl
171b0 65 72 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63  er.  Any such ac
171c0 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20  tions.** result 
171d0 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68  in undefined beh
171e0 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20  avior..** .** A 
171f0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73  busy handler mus
17200 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20  t not close the 
17210 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
17220 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61  ion.** or [prepa
17230 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
17240 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
17250 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f  busy handler..*/
17260 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73  .int sqlite3_bus
17270 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65  y_handler(sqlite
17280 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a  3*, int(*)(void*
17290 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  ,int), void*);..
172a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
172b0 53 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f  Set A Busy Timeo
172c0 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  ut.**.** ^This r
172d0 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73  outine sets a [s
172e0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
172f0 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c  ler | busy handl
17300 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a  er] that sleeps.
17310 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69  ** for a specifi
17320 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d  ed amount of tim
17330 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69  e when a table i
17340 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20  s locked.  ^The 
17350 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20  handler.** will 
17360 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74  sleep multiple t
17370 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65  imes until at le
17380 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65  ast "ms" millise
17390 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e  conds of sleepin
173a0 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75  g.** have accumu
173b0 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61  lated.  ^After a
173c0 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c  t least "ms" mil
173d0 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
173e0 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61  eping,.** the ha
173f0 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20  ndler returns 0 
17400 77 68 69 63 68 20 63 61 75 73 65 73 20 5b 73 71  which causes [sq
17410 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f  lite3_step()] to
17420 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49   return.** [SQLI
17430 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c  TE_BUSY] or [SQL
17440 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
17450 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  D]..**.** ^Calli
17460 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ng this routine 
17470 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74  with an argument
17480 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71   less than or eq
17490 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74  ual to zero.** t
174a0 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73  urns off all bus
174b0 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a  y handlers..**.*
174c0 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e  * ^(There can on
174d0 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62  ly be a single b
174e0 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20  usy handler for 
174f0 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
17500 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
17510 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69  tion] any any gi
17520 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20  ven moment.  If 
17530 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e  another busy han
17540 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69  dler.** was defi
17550 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c  ned  (using [sql
17560 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
17570 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63  r()]) prior to c
17580 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72  alling.** this r
17590 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68  outine, that oth
175a0 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  er busy handler 
175b0 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f  is cleared.)^.*/
175c0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73  .int sqlite3_bus
175d0 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65  y_timeout(sqlite
175e0 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a  3*, int ms);../*
175f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
17600 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e  nvenience Routin
17610 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51  es For Running Q
17620 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69  ueries.**.** Thi
17630 73 20 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e  s is a legacy in
17640 74 65 72 66 61 63 65 20 74 68 61 74 20 69 73 20  terface that is 
17650 70 72 65 73 65 72 76 65 64 20 66 6f 72 20 62 61  preserved for ba
17660 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
17670 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66  ility..** Use of
17680 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
17690 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64  is not recommend
176a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69  ed..**.** Defini
176b0 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c  tion: A <b>resul
176c0 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d  t table</b> is m
176d0 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63  emory data struc
176e0 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20  ture created by 
176f0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
17700 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74  get_table()] int
17710 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c  erface.  A resul
17720 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20  t table records 
17730 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20  the.** complete 
17740 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72  query results fr
17750 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71  om one or more q
17760 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ueries..**.** Th
17770 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75  e table conceptu
17780 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65  ally has a numbe
17790 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f  r of rows and co
177a0 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74  lumns.  But.** t
177b0 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65  hese numbers are
177c0 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65   not part of the
177d0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74   result table it
177e0 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20  self.  These.** 
177f0 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61  numbers are obta
17800 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e  ined separately.
17810 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e    Let N be the n
17820 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a  umber of rows.**
17830 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75   and M be the nu
17840 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e  mber of columns.
17850 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  .**.** A result 
17860 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61  table is an arra
17870 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
17880 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
17890 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a   UTF-8 strings..
178a0 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b  ** There are (N+
178b0 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e  1)*M elements in
178c0 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65   the array.  The
178d0 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72   first M pointer
178e0 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65  s point.** to ze
178f0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
17900 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74  rings that  cont
17910 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66  ain the names of
17920 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a   the columns..**
17930 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65   The remaining e
17940 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74  ntries all point
17950 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74   to query result
17960 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20  s.  NULL values 
17970 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c  result.** in NUL
17980 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c  L pointers.  All
17990 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72   other values ar
179a0 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38  e in their UTF-8
179b0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
179c0 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65  .** string repre
179d0 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74  sentation as ret
179e0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
179f0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
17a00 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ..**.** A result
17a10 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e   table might con
17a20 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d  sist of one or m
17a30 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ore memory alloc
17a40 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73  ations..** It is
17a50 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73   not safe to pas
17a60 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65  s a result table
17a70 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71   directly to [sq
17a80 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a  lite3_free()]..*
17a90 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
17aa0 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c   should be deall
17ab0 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71  ocated using [sq
17ac0 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
17ad0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20  ()]..**.** ^(As 
17ae0 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68  an example of th
17af0 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66  e result table f
17b00 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61  ormat, suppose a
17b10 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a   query result.**
17b20 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a   is as follows:.
17b30 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
17b40 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
17b50 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20    Name        | 
17b60 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d  Age.**        --
17b70 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
17b80 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20  -----.**        
17b90 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33  Alice       | 43
17ba0 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20  .**        Bob  
17bb0 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20         | 28.**  
17bc0 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20        Cindy     
17bd0 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e    | 21.** </pre>
17be0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
17bf0 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 77  .** There are tw
17c00 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20  o column (M==2) 
17c10 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 28  and three rows (
17c20 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65  N==3).  Thus the
17c30 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65  .** result table
17c40 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20   has 8 entries. 
17c50 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 73   Suppose the res
17c60 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f  ult table is sto
17c70 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72  red.** in an arr
17c80 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c  ay names azResul
17c90 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c  t.  Then azResul
17ca0 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e  t holds this con
17cb0 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  tent:.**.** <blo
17cc0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
17cd0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
17ce0 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22  &#91;0] = "Name"
17cf0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
17d00 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41  sult&#91;1] = "A
17d10 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ge";.**        a
17d20 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d  zResult&#91;2] =
17d30 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20   "Alice";.**    
17d40 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
17d50 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20  ;3] = "43";.**  
17d60 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
17d70 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a  91;4] = "Bob";.*
17d80 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
17d90 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b  t&#91;5] = "28";
17da0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
17db0 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69  ult&#91;6] = "Ci
17dc0 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ndy";.**        
17dd0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20  azResult&#91;7] 
17de0 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65  = "21";.** </pre
17df0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e  ></blockquote>)^
17e00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
17e10 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
17e20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74  function evaluat
17e30 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a  es one or more.*
17e40 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61  * semicolon-sepa
17e50 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  rated SQL statem
17e60 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f  ents in the zero
17e70 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
17e80 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69  8.** string of i
17e90 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  ts 2nd parameter
17ea0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72   and returns a r
17eb0 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74  esult table to t
17ec0 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69  he.** pointer gi
17ed0 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70  ven in its 3rd p
17ee0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
17ef0 41 66 74 65 72 20 74 68 65 20 61 70 70 6c 69 63  After the applic
17f00 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68  ation has finish
17f10 65 64 20 77 69 74 68 20 74 68 65 20 72 65 73 75  ed with the resu
17f20 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  lt from sqlite3_
17f30 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20  get_table(),.** 
17f40 69 74 20 6d 75 73 74 20 70 61 73 73 20 74 68 65  it must pass the
17f50 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f   result table po
17f60 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  inter to sqlite3
17f70 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e  _free_table() in
17f80 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c   order to.** rel
17f90 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  ease the memory 
17fa0 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65  that was malloce
17fb0 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74  d.  Because of t
17fc0 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73  he way the.** [s
17fd0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
17fe0 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20   happens within 
17ff0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
18000 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67  e(), the calling
18010 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  .** function mus
18020 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c  t not try to cal
18030 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  l [sqlite3_free(
18040 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e  )] directly.  On
18050 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  ly.** [sqlite3_f
18060 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20  ree_table()] is 
18070 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20  able to release 
18080 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65  the memory prope
18090 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a  rly and safely..
180a0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
180b0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e  3_get_table() in
180c0 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65  terface is imple
180d0 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70  mented as a wrap
180e0 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73  per around.** [s
180f0 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20  qlite3_exec()]. 
18100 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74   The sqlite3_get
18110 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65  _table() routine
18120 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61   does not have a
18130 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20  ccess.** to any 
18140 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74  internal data st
18150 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69  ructures of SQLi
18160 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c  te.  It uses onl
18170 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20  y the public.** 
18180 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65  interface define
18190 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f  d here.  As a co
181a0 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72  nsequence, error
181b0 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20  s that occur in 
181c0 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c  the.** wrapper l
181d0 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20  ayer outside of 
181e0 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71  the internal [sq
181f0 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61  lite3_exec()] ca
18200 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65  ll are not.** re
18210 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65  flected in subse
18220 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b  quent calls to [
18230 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
18240 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
18250 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a  3_errmsg()]..*/.
18260 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  int sqlite3_get_
18270 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33  table(.  sqlite3
18280 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f   *db,          /
18290 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  * An open databa
182a0 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  se */.  const ch
182b0 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a  ar *zSql,     /*
182c0 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75   SQL to be evalu
182d0 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a  ated */.  char *
182e0 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20  **pazResult,    
182f0 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68  /* Results of th
18300 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74  e query */.  int
18310 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20   *pnRow,        
18320 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
18330 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74  result rows writ
18340 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e  ten here */.  in
18350 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20  t *pnColumn,    
18360 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
18370 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20   result columns 
18380 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
18390 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73    char **pzErrms
183a0 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72  g       /* Error
183b0 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72   msg written her
183c0 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c  e */.);.void sql
183d0 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
183e0 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a  char **result);.
183f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
18400 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e   Formatted Strin
18410 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74  g Printing Funct
18420 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
18430 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f   routines are wo
18440 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65  rk-alikes of the
18450 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69   "printf()" fami
18460 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a  ly of functions.
18470 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e  ** from the stan
18480 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a  dard C library..
18490 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
184a0 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64  e3_mprintf() and
184b0 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74   sqlite3_vmprint
184c0 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69  f() routines wri
184d0 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75  te their.** resu
184e0 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  lts into memory 
184f0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
18500 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
18510 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73  ..** The strings
18520 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
18530 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20  se two routines 
18540 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c  should be.** rel
18550 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65  eased by [sqlite
18560 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74  3_free()].  ^Bot
18570 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  h routines retur
18580 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e  n a.** NULL poin
18590 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f  ter if [sqlite3_
185a0 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61  malloc()] is una
185b0 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
185c0 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79  enough.** memory
185d0 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73   to hold the res
185e0 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a  ulting string..*
185f0 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74  *.** ^(The sqlit
18600 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f  e3_snprintf() ro
18610 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72  utine is similar
18620 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22   to "snprintf()"
18630 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61   from.** the sta
18640 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
18650 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20    The result is 
18660 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65  written into the
18670 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c  .** buffer suppl
18680 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ied as the secon
18690 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73  d parameter whos
186a0 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20  e size is given 
186b0 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  by.** the first 
186c0 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20  parameter. Note 
186d0 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f  that the order o
186e0 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74  f the.** first t
186f0 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73  wo parameters is
18700 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73   reversed from s
18710 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68  nprintf().)^  Th
18720 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74  is is an.** hist
18730 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20  orical accident 
18740 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66  that cannot be f
18750 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65  ixed without bre
18760 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72  aking.** backwar
18770 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
18780 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74  .  ^(Note also t
18790 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  hat sqlite3_snpr
187a0 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e  intf().** return
187b0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69  s a pointer to i
187c0 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61  ts buffer instea
187d0 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20  d of the number 
187e0 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  of.** characters
187f0 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65   actually writte
18800 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65  n into the buffe
18810 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74  r.)^  We admit t
18820 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  hat.** the numbe
18830 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20  r of characters 
18840 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65  written would be
18850 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72   a more useful r
18860 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62  eturn.** value b
18870 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61  ut we cannot cha
18880 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  nge the implemen
18890 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65  tation of sqlite
188a0 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
188b0 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61  now without brea
188c0 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69  king compatibili
188d0 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f  ty..**.** ^As lo
188e0 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72  ng as the buffer
188f0 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72   size is greater
18900 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69   than zero, sqli
18910 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
18920 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  * guarantees tha
18930 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20  t the buffer is 
18940 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d  always zero-term
18950 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69  inated.  ^The fi
18960 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  rst.** parameter
18970 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61   "n" is the tota
18980 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75  l size of the bu
18990 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20  ffer, including 
189a0 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65  space for.** the
189b0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
189c0 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73  .  So the longes
189d0 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61  t string that ca
189e0 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a  n be completely.
189f0 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20  ** written will 
18a00 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72  be n-1 character
18a10 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
18a20 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28  lite3_vsnprintf(
18a30 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76  ) routine is a v
18a40 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f  arargs version o
18a50 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  f sqlite3_snprin
18a60 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tf()..**.** Thes
18a70 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69  e routines all i
18a80 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64  mplement some ad
18a90 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74  ditional formatt
18aa0 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74  ing.** options t
18ab0 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66  hat are useful f
18ac0 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20  or constructing 
18ad0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
18ae0 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73  ** All of the us
18af0 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72  ual printf() for
18b00 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20  matting options 
18b10 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74  apply.  In addit
18b20 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73  ion, there.** is
18b30 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c   are "%q", "%Q",
18b40 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e   and "%z" option
18b50 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25  s..**.** ^(The %
18b60 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  q option works l
18b70 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69  ike %s in that i
18b80 74 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20  t substitutes a 
18b90 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  nul-terminated.*
18ba0 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68  * string from th
18bb0 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e  e argument list.
18bc0 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f    But %q also do
18bd0 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27  ubles every '\''
18be0 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25   character..** %
18bf0 71 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f  q is designed fo
18c00 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73  r use inside a s
18c10 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e  tring literal.)^
18c20 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61    By doubling ea
18c30 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61  ch '\''.** chara
18c40 63 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20  cter it escapes 
18c50 74 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61  that character a
18c60 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20  nd allows it to 
18c70 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f  be inserted into
18c80 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a  .** the string..
18c90 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c  **.** For exampl
18ca0 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 74  e, assume the st
18cb0 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54  ring variable zT
18cc0 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78  ext contains tex
18cd0 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  t as follows:.**
18ce0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
18cf0 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
18d00 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20  zText = "It's a 
18d10 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20  happy day!";.** 
18d20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
18d30 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61  te>.**.** One ca
18d40 6e 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20  n use this text 
18d50 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  in an SQL statem
18d60 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  ent as follows:.
18d70 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
18d80 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
18d90 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33   *zSQL = sqlite3
18da0 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54  _mprintf("INSERT
18db0 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55   INTO table VALU
18dc0 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74  ES('%q')", zText
18dd0 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65  );.**  sqlite3_e
18de0 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c  xec(db, zSQL, 0,
18df0 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69   0, 0);.**  sqli
18e00 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a  te3_free(zSQL);.
18e10 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
18e20 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63  quote>.**.** Bec
18e30 61 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d  ause the %q form
18e40 61 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65  at string is use
18e50 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72  d, the '\'' char
18e60 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a  acter in zText.*
18e70 2a 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64  * is escaped and
18e80 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74   the SQL generat
18e90 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73  ed is as follows
18ea0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
18eb0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e  ote><pre>.**  IN
18ec0 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31  SERT INTO table1
18ed0 20 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61   VALUES('It''s a
18ee0 20 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a   happy day!').**
18ef0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
18f00 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ote>.**.** This 
18f10 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64  is correct.  Had
18f20 20 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74   we used %s inst
18f30 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67  ead of %q, the g
18f40 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20  enerated SQL.** 
18f50 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65  would have looke
18f60 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a  d like this:.**.
18f70 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
18f80 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20  pre>.**  INSERT 
18f90 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55  INTO table1 VALU
18fa0 45 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79  ES('It's a happy
18fb0 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72   day!');.** </pr
18fc0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
18fd0 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e  **.** This secon
18fe0 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20  d example is an 
18ff0 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72  SQL syntax error
19000 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20  .  As a general 
19010 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a  rule you should.
19020 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 71  ** always use %q
19030 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77   instead of %s w
19040 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65  hen inserting te
19050 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67  xt into a string
19060 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20   literal..**.** 
19070 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20  ^(The %Q option 
19080 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78  works like %q ex
19090 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64  cept it also add
190a0 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20  s single quotes 
190b0 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75  around.** the ou
190c0 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74  tside of the tot
190d0 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69  al string.  Addi
190e0 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65  tionally, if the
190f0 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68   parameter in th
19100 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69  e.** argument li
19110 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  st is a NULL poi
19120 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74  nter, %Q substit
19130 75 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e  utes the text "N
19140 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a  ULL" (without.**
19150 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e   single quotes).
19160 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d  )^  So, for exam
19170 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73  ple, one could s
19180 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ay:.**.** <block
19190 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
191a0 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c  char *zSQL = sql
191b0 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e  ite3_mprintf("IN
191c0 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20  SERT INTO table 
191d0 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65  VALUES(%Q)", zTe
191e0 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33  xt);.**  sqlite3
191f0 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20  _exec(db, zSQL, 
19200 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71  0, 0, 0);.**  sq
19210 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29  lite3_free(zSQL)
19220 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
19230 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
19240 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69  he code above wi
19250 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72  ll render a corr
19260 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ect SQL statemen
19270 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a  t in the zSQL.**
19280 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69   variable even i
19290 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69  f the zText vari
192a0 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70  able is a NULL p
192b0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ointer..**.** ^(
192c0 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74  The "%z" formatt
192d0 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73  ing option works
192e0 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20 77   like "%s" but w
192f0 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74  ith the.** addit
19300 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74  ion that after t
19310 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65  he string has be
19320 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69  en read and copi
19330 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72  ed into.** the r
19340 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f  esult, [sqlite3_
19350 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65  free()] is calle
19360 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73  d on the input s
19370 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72  tring.)^.*/.char
19380 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74   *sqlite3_mprint
19390 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e  f(const char*,..
193a0 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  .);.char *sqlite
193b0 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74  3_vmprintf(const
193c0 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29   char*, va_list)
193d0 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  ;.char *sqlite3_
193e0 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61  snprintf(int,cha
193f0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  r*,const char*, 
19400 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69  ...);.char *sqli
19410 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e  te3_vsnprintf(in
19420 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t,char*,const ch
19430 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a  ar*, va_list);..
19440 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
19450 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f  Memory Allocatio
19460 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a  n Subsystem.**.*
19470 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * The SQLite cor
19480 65 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72  e uses these thr
19490 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20  ee routines for 
194a0 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a  all of its own.*
194b0 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72  * internal memor
194c0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
194d0 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68  ds. "Core" in th
194e0 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65  e previous sente
194f0 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  nce.** does not 
19500 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e  include operatin
19510 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69  g-system specifi
19520 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  c VFS implementa
19530 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69  tion.  The.** Wi
19540 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e  ndows VFS uses n
19550 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61  ative malloc() a
19560 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f  nd free() for so
19570 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a  me operations..*
19580 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
19590 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69  3_malloc() routi
195a0 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ne returns a poi
195b0 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a  nter to a block.
195c0 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20  ** of memory at 
195d0 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e  least N bytes in
195e0 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e   length, where N
195f0 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65   is the paramete
19600 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  r..** ^If sqlite
19610 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e  3_malloc() is un
19620 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73  able to obtain s
19630 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a  ufficient free.*
19640 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74  * memory, it ret
19650 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
19660 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61  ter.  ^If the pa
19670 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20  rameter N to.** 
19680 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
19690 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61   is zero or nega
196a0 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65  tive then sqlite
196b0 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  3_malloc() retur
196c0 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69  ns.** a NULL poi
196d0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  nter..**.** ^Cal
196e0 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65  ling sqlite3_fre
196f0 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  e() with a point
19700 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  er previously re
19710 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c  turned.** by sql
19720 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72  ite3_malloc() or
19730 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
19740 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74  () releases that
19750 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68   memory so.** th
19760 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72  at it might be r
19770 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c  eused.  ^The sql
19780 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74  ite3_free() rout
19790 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f  ine is.** a no-o
197a0 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77  p if is called w
197b0 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
197c0 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e  er.  Passing a N
197d0 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  ULL pointer.** t
197e0 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  o sqlite3_free()
197f0 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41   is harmless.  A
19800 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64  fter being freed
19810 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75  , memory.** shou
19820 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65  ld neither be re
19830 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20  ad nor written. 
19840 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72   Even reading pr
19850 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a  eviously freed.*
19860 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72  * memory might r
19870 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65  esult in a segme
19880 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72  ntation fault or
19890 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72   other severe er
198a0 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63  ror..** Memory c
198b0 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67  orruption, a seg
198c0 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c  mentation fault,
198d0 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65   or other severe
198e0 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20   error.** might 
198f0 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65  result if sqlite
19900 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c  3_free() is call
19910 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55  ed with a non-NU
19920 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a  LL pointer that.
19930 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69  ** was not obtai
19940 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ned from sqlite3
19950 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
19960 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a  ite3_realloc()..
19970 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69  **.** ^(The sqli
19980 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e  te3_realloc() in
19990 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
199a0 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20   to resize a.** 
199b0 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c  prior memory all
199c0 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74  ocation to be at
199d0 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20   least N bytes, 
199e0 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a  where N is the.*
199f0 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
19a00 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20  er.  The memory 
19a10 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65  allocation to be
19a20 20 72 65 73 69 7a 65 64 20 69 73 20 74 68 65 20   resized is the 
19a30 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74  first.** paramet
19a40 65 72 2e 29 5e 20 5e 20 49 66 20 74 68 65 20 66  er.)^ ^ If the f
19a50 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
19a60 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
19a70 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c  c().** is a NULL
19a80 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74   pointer then it
19a90 73 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64  s behavior is id
19aa0 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69  entical to calli
19ab0 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  ng.** sqlite3_ma
19ac0 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65 20 4e 20  lloc(N) where N 
19ad0 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  is the second pa
19ae0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
19af0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
19b00 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20   ^If the second 
19b10 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
19b20 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69  ite3_realloc() i
19b30 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67  s zero or.** neg
19b40 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62  ative then the b
19b50 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74  ehavior is exact
19b60 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63  ly the same as c
19b70 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  alling.** sqlite
19b80 33 5f 66 72 65 65 28 50 29 20 77 68 65 72 65 20  3_free(P) where 
19b90 50 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70  P is the first p
19ba0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
19bb0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a  te3_realloc()..*
19bc0 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  * ^sqlite3_reall
19bd0 6f 63 28 29 20 72 65 74 75 72 6e 73 20 61 20 70  oc() returns a p
19be0 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f  ointer to a memo
19bf0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
19c00 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62   of at least N b
19c10 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20  ytes in size or 
19c20 4e 55 4c 4c 20 69 66 20 73 75 66 66 69 63 69 65  NULL if sufficie
19c30 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61  nt memory is una
19c40 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66  vailable..** ^If
19c50 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f   M is the size o
19c60 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  f the prior allo
19c70 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e  cation, then min
19c80 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f  (N,M) bytes.** o
19c90 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  f the prior allo
19ca0 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65  cation are copie
19cb0 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e  d into the begin
19cc0 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72  ning of buffer r
19cd0 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71  eturned.** by sq
19ce0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
19cf0 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c  and the prior al
19d00 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  location is free
19d10 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  d..** ^If sqlite
19d20 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75  3_realloc() retu
19d30 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74  rns NULL, then t
19d40 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
19d50 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72  ion.** is not fr
19d60 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eed..**.** ^The 
19d70 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20  memory returned 
19d80 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  by sqlite3_mallo
19d90 63 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  c() and sqlite3_
19da0 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20  realloc().** is 
19db0 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74  always aligned t
19dc0 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20  o at least an 8 
19dd0 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f  byte boundary, o
19de0 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65  r to a.** 4 byte
19df0 20 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65   boundary if the
19e00 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f   [SQLITE_4_BYTE_
19e10 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20  ALIGNED_MALLOC] 
19e20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20  compile-time.** 
19e30 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a  option is used..
19e40 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20  **.** In SQLite 
19e50 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e  version 3.5.0 an
19e60 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20  d 3.5.1, it was 
19e70 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69  possible to defi
19e80 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45  ne.** the SQLITE
19e90 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c  _OMIT_MEMORY_ALL
19ea0 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f  OCATION which wo
19eb0 75 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75  uld cause the bu
19ec0 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d  ilt-in.** implem
19ed0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73  entation of thes
19ee0 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65  e routines to be
19ef0 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20   omitted.  That 
19f00 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73  capability.** is
19f10 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69   no longer provi
19f20 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74  ded.  Only built
19f30 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  -in memory alloc
19f40 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65  ators can be use
19f50 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74  d..**.** Prior t
19f60 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  o SQLite version
19f70 20 33 2e 37 2e 31 30 2c 20 74 68 65 20 57 69 6e   3.7.10, the Win
19f80 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63  dows OS interfac
19f90 65 20 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a  e layer called.*
19fa0 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c  * the system mal
19fb0 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
19fc0 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63   directly when c
19fd0 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c  onverting.** fil
19fe0 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74  enames between t
19ff0 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  he UTF-8 encodin
1a000 67 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65  g used by SQLite
1a010 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72  .** and whatever
1a020 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69   filename encodi
1a030 6e 67 20 69 73 20 75 73 65 64 20 62 79 20 74 68  ng is used by th
1a040 65 20 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e  e particular Win
1a050 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61  dows.** installa
1a060 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c  tion.  Memory al
1a070 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20  location errors 
1a080 77 65 72 65 20 64 65 74 65 63 74 65 64 2c 20 62  were detected, b
1a090 75 74 0a 2a 2a 20 74 68 65 79 20 77 65 72 65 20  ut.** they were 
1a0a0 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73  reported back as
1a0b0 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   [SQLITE_CANTOPE
1a0c0 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  N] or.** [SQLITE
1a0d0 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74  _IOERR] rather t
1a0e0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  han [SQLITE_NOME
1a0f0 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f  M]..**.** The po
1a100 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20  inter arguments 
1a110 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  to [sqlite3_free
1a120 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
1a130 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d  _realloc()].** m
1a140 75 73 74 20 62 65 20 65 69 74 68 65 72 20 4e 55  ust be either NU
1a150 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74  LL or else point
1a160 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ers obtained fro
1a170 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76  m a prior.** inv
1a180 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69  ocation of [sqli
1a190 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72  te3_malloc()] or
1a1a0 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
1a1b0 63 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a  c()] that have.*
1a1c0 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72  * not yet been r
1a1d0 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  eleased..**.** T
1a1e0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
1a1f0 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20  ust not read or 
1a200 77 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f  write any part o
1a210 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20  f.** a block of 
1a220 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20  memory after it 
1a230 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65  has been release
1a240 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  d using.** [sqli
1a250 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b  te3_free()] or [
1a260 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1a270 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  )]..*/.void *sql
1a280 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29  ite3_malloc(int)
1a290 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  ;.void *sqlite3_
1a2a0 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69  realloc(void*, i
1a2b0 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
1a2c0 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a  3_free(void*);..
1a2d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1a2e0 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72  Memory Allocator
1a2f0 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a   Statistics.**.*
1a300 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65  * SQLite provide
1a310 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65  s these two inte
1a320 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72  rfaces for repor
1a330 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74  ting on the stat
1a340 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  us.** of the [sq
1a350 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c  lite3_malloc()],
1a360 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1a370 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
1a380 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f  realloc()].** ro
1a390 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f  utines, which fo
1a3a0 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20  rm the built-in 
1a3b0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1a3c0 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a  n subsystem..**.
1a3d0 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
1a3e0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
1a3f0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
1a400 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
1a410 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79  tes.** of memory
1a420 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74   currently outst
1a430 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64  anding (malloced
1a440 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e   but not freed).
1a450 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
1a460 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1a470 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65  er()] routine re
1a480 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75  turns the maximu
1a490 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73  m.** value of [s
1a4a0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
1a4b0 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20  ed()] since the 
1a4c0 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a  high-water mark.
1a4d0 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73 65  ** was last rese
1a4e0 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20  t.  ^The values 
1a4f0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
1a500 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
1a510 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  ()] and.** [sqli
1a520 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1a530 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20  ater()] include 
1a540 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20  any overhead.** 
1a550 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20  added by SQLite 
1a560 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74  in its implement
1a570 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
1a580 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20  3_malloc()],.** 
1a590 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64  but not overhead
1a5a0 20 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e   added by the an
1a5b0 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73  y underlying sys
1a5c0 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72  tem library.** r
1a5d0 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71  outines that [sq
1a5e0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
1a5f0 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20  may call..**.** 
1a600 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68  ^The memory high
1a610 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72  -water mark is r
1a620 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72  eset to the curr
1a630 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20  ent value of.** 
1a640 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1a650 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f  used()] if and o
1a660 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d  nly if the param
1a670 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  eter to.** [sqli
1a680 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1a690 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e  ater()] is true.
1a6a0 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74    ^The value ret
1a6b0 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c  urned.** by [sql
1a6c0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1a6d0 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65  water(1)] is the
1a6e0 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
1a6f0 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65  .** prior to the
1a700 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74   reset..*/.sqlit
1a710 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
1a720 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69  _memory_used(voi
1a730 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  d);.sqlite3_int6
1a740 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  4 sqlite3_memory
1a750 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72  _highwater(int r
1a760 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a  esetFlag);../*.*
1a770 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 75  * CAPI3REF: Pseu
1a780 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72  do-Random Number
1a790 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a   Generator.**.**
1a7a0 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73   SQLite contains
1a7b0 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20   a high-quality 
1a7c0 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75  pseudo-random nu
1a7d0 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28  mber generator (
1a7e0 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a  PRNG) used to.**
1a7f0 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b   select random [
1a800 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20  ROWID | ROWIDs] 
1a810 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e  when inserting n
1a820 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20  ew records into 
1a830 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20  a table that.** 
1a840 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65  already uses the
1a850 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c   largest possibl
1a860 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20  e [ROWID].  The 
1a870 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65  PRNG is also use
1a880 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69  d for.** the bui
1a890 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61  ld-in random() a
1a8a0 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20  nd randomblob() 
1a8b0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  SQL functions.  
1a8c0 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61  This interface a
1a8d0 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61  llows.** applica
1a8e0 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20  tions to access 
1a8f0 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f  the same PRNG fo
1a900 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73  r other purposes
1a910 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20  ..**.** ^A call 
1a920 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  to this routine 
1a930 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f  stores N bytes o
1a940 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  f randomness int
1a950 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a  o buffer P..**.*
1a960 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d  * ^The first tim
1a970 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  e this routine i
1a980 73 20 69 6e 76 6f 6b 65 64 20 28 65 69 74 68 65  s invoked (eithe
1a990 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 20  r internally or 
1a9a0 62 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  by.** the applic
1a9b0 61 74 69 6f 6e 29 20 74 68 65 20 50 52 4e 47 20  ation) the PRNG 
1a9c0 69 73 20 73 65 65 64 65 64 20 75 73 69 6e 67 20  is seeded using 
1a9d0 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69  randomness obtai
1a9e0 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ned.** from the 
1a9f0 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68  xRandomness meth
1aa00 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c  od of the defaul
1aa10 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
1aa20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 4f 6e 20 61  object..** ^On a
1aa30 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e  ll subsequent in
1aa40 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65 20 70  vocations, the p
1aa50 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73  seudo-randomness
1aa60 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a   is generated.**
1aa70 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20   internally and 
1aa80 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65  without recourse
1aa90 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
1aaa0 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73  _vfs] xRandomnes
1aab0 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a  s.** method..*/.
1aac0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e  void sqlite3_ran
1aad0 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76  domness(int N, v
1aae0 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid *P);../*.** 
1aaf0 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c  CAPI3REF: Compil
1ab00 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61  e-Time Authoriza
1ab10 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  tion Callbacks.*
1ab20 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
1ab30 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 6e 20  ne registers an 
1ab40 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1ab50 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 69  ack with a parti
1ab60 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61  cular.** [databa
1ab70 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20  se connection], 
1ab80 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20  supplied in the 
1ab90 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a  first argument..
1aba0 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a  ** ^The authoriz
1abb0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
1abc0 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74  nvoked as SQL st
1abd0 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69  atements are bei
1abe0 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62  ng compiled.** b
1abf0 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  y [sqlite3_prepa
1ac00 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  re()] or its var
1ac10 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70  iants [sqlite3_p
1ac20 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a  repare_v2()],.**
1ac30 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1ac40 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  e16()] and [sqli
1ac50 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
1ac60 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75  ()].  ^At variou
1ac70 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69  s.** points duri
1ac80 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69  ng the compilati
1ac90 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c  on process, as l
1aca0 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 72  ogic is being cr
1acb0 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66  eated.** to perf
1acc0 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69  orm various acti
1acd0 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69  ons, the authori
1ace0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1acf0 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65  invoked to.** se
1ad00 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f  e if those actio
1ad10 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20  ns are allowed. 
1ad20 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72   ^The authorizer
1ad30 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64   callback should
1ad40 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
1ad50 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20  TE_OK] to allow 
1ad60 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c  the action, [SQL
1ad70 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64  ITE_IGNORE] to d
1ad80 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73  isallow the.** s
1ad90 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62  pecific action b
1ada0 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c  ut allow the SQL
1adb0 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f   statement to co
1adc0 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20  ntinue to be.** 
1add0 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51  compiled, or [SQ
1ade0 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61  LITE_DENY] to ca
1adf0 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 53  use the entire S
1ae00 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  QL statement to 
1ae10 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77  be.** rejected w
1ae20 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e  ith an error.  ^
1ae30 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  If the authorize
1ae40 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  r callback retur
1ae50 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20  ns.** any value 
1ae60 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
1ae70 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c  TE_IGNORE], [SQL
1ae80 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c  ITE_OK], or [SQL
1ae90 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65  ITE_DENY].** the
1aea0 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70  n the [sqlite3_p
1aeb0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
1aec0 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
1aed0 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a  that triggered.*
1aee0 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * the authorizer
1aef0 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20   will fail with 
1af00 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
1af10 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
1af20 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1af30 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74  s [SQLITE_OK], t
1af40 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70  hat means the op
1af50 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65  eration.** reque
1af60 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68  sted is ok.  ^Wh
1af70 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
1af80 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
1af90 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73  DENY], the.** [s
1afa0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1afb0 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65  2()] or equivale
1afc0 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  nt call that tri
1afd0 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75  ggered the.** au
1afe0 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61  thorizer will fa
1aff0 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  il with an error
1b000 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e   message explain
1b010 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65  ing that.** acce
1b020 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a  ss is denied. .*
1b030 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
1b040 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1b050 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1b060 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f  back is a copy o
1b070 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70  f the third.** p
1b080 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
1b090 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1b0a0 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61  orizer() interfa
1b0b0 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  ce. ^The second 
1b0c0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20  parameter.** to 
1b0d0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
1b0e0 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49  an integer [SQLI
1b0f0 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e  TE_COPY | action
1b100 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63   code] that spec
1b110 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72  ifies.** the par
1b120 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74  ticular action t
1b130 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e  o be authorized.
1b140 20 5e 54 68 65 20 74 68 69 72 64 20 74 68 72 6f   ^The third thro
1b150 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65  ugh sixth parame
1b160 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63  ters.** to the c
1b170 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f  allback are zero
1b180 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
1b190 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ngs that contain
1b1a0 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64   additional.** d
1b1b0 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65  etails about the
1b1c0 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75   action to be au
1b1d0 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20  thorized..**.** 
1b1e0 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63  ^If the action c
1b1f0 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52  ode is [SQLITE_R
1b200 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20  EAD].** and the 
1b210 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1b220 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
1b230 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72   then the.** [pr
1b240 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1b250 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63  ] statement is c
1b260 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73 75  onstructed to su
1b270 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55  bstitute.** a NU
1b280 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63  LL value in plac
1b290 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63  e of the table c
1b2a0 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64  olumn that would
1b2b0 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65   have.** been re
1b2c0 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b  ad if [SQLITE_OK
1b2d0 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 72  ] had been retur
1b2e0 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ned.  The [SQLIT
1b2f0 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74  E_IGNORE].** ret
1b300 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  urn can be used 
1b310 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75  to deny an untru
1b320 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73 73  sted user access
1b330 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a   to individual.*
1b340 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74  * columns of a t
1b350 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  able..** ^If the
1b360 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20   action code is 
1b370 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20  [SQLITE_DELETE] 
1b380 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  and the callback
1b390 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c   returns.** [SQL
1b3a0 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e  ITE_IGNORE] then
1b3b0 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70   the [DELETE] op
1b3c0 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73  eration proceeds
1b3d0 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75   but the.** [tru
1b3e0 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69  ncate optimizati
1b3f0 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20  on] is disabled 
1b400 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65  and all rows are
1b410 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64   deleted individ
1b420 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20  ually..**.** An 
1b430 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73  authorizer is us
1b440 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33  ed when [sqlite3
1b450 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61  _prepare | prepa
1b460 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61  ring].** SQL sta
1b470 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20  tements from an 
1b480 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65  untrusted source
1b490 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74  , to ensure that
1b4a0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
1b4b0 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72  nts.** do not tr
1b4c0 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 61  y to access data
1b4d0 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c   they are not al
1b4e0 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72  lowed to see, or
1b4f0 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f   that they do no
1b500 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63  t.** try to exec
1b510 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74  ute malicious st
1b520 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61  atements that da
1b530 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61 73  mage the databas
1b540 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70  e.  For.** examp
1b550 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  le, an applicati
1b560 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75  on may allow a u
1b570 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62  ser to enter arb
1b580 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75  itrary.** SQL qu
1b590 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61  eries for evalua
1b5a0 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61  tion by a databa
1b5b0 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 70  se.  But the app
1b5c0 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a  lication does.**
1b5d0 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73   not want the us
1b5e0 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f  er to be able to
1b5f0 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 20   make arbitrary 
1b600 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a  changes to the.*
1b610 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20  * database.  An 
1b620 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64  authorizer could
1b630 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20   then be put in 
1b640 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a  place while the.
1b650 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20  ** user-entered 
1b660 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71  SQL is being [sq
1b670 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20  lite3_prepare | 
1b680 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a  prepared] that.*
1b690 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72  * disallows ever
1b6a0 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53  ything except [S
1b6b0 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
1b6c0 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61  s..**.** Applica
1b6d0 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20  tions that need 
1b6e0 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66  to process SQL f
1b6f0 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f  rom untrusted so
1b700 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61  urces.** might a
1b710 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77  lso consider low
1b720 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c  ering resource l
1b730 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c  imits using [sql
1b740 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a  ite3_limit()].**
1b750 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61   and limiting da
1b760 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e  tabase size usin
1b770 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f  g the [max_page_
1b780 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a  count] [PRAGMA].
1b790 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74  ** in addition t
1b7a0 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f  o using an autho
1b7b0 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f  rizer..**.** ^(O
1b7c0 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74  nly a single aut
1b7d0 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69  horizer can be i
1b7e0 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74  n place on a dat
1b7f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1b800 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20  .** at a time.  
1b810 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c  Each call to sql
1b820 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1b830 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74 68  zer overrides th
1b840 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61  e.** previous ca
1b850 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20  ll.)^  ^Disable 
1b860 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62  the authorizer b
1b870 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e  y installing a N
1b880 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ULL callback..**
1b890 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   The authorizer 
1b8a0 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  is disabled by d
1b8b0 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  efault..**.** Th
1b8c0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1b8d0 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64  lback must not d
1b8e0 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20  o anything that 
1b8f0 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74  will modify.** t
1b900 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1b910 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
1b920 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ked the authoriz
1b930 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  er callback..** 
1b940 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
1b950 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1b960 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
1b970 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
1b980 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
1b990 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
1b9a0 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
1b9b0 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
1b9c0 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
1b9d0 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69  *.** ^When [sqli
1b9e0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1b9f0 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72 65  ] is used to pre
1ba00 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74  pare a statement
1ba10 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65  , the.** stateme
1ba20 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70  nt might be re-p
1ba30 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b  repared during [
1ba40 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1ba50 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68  due to a .** sch
1ba60 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e  ema change.  Hen
1ba70 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74  ce, the applicat
1ba80 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72  ion should ensur
1ba90 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f  e that the.** co
1baa0 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72  rrect authorizer
1bab0 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e   callback remain
1bac0 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e  s in place durin
1bad0 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  g the [sqlite3_s
1bae0 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e  tep()]..**.** ^N
1baf0 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74  ote that the aut
1bb00 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1bb10 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79   is invoked only
1bb20 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69   during.** [sqli
1bb30 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
1bb40 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20  r its variants. 
1bb50 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69   Authorization i
1bb60 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d  s not.** perform
1bb70 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d  ed during statem
1bb80 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69  ent evaluation i
1bb90 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  n [sqlite3_step(
1bba0 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73  )], unless.** as
1bbb0 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20 70   stated in the p
1bbc0 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70  revious paragrap
1bbd0 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  h, sqlite3_step(
1bbe0 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c  ) invokes.** sql
1bbf0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1bc00 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20 61  ) to reprepare a
1bc10 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72   statement after
1bc20 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65   a schema change
1bc30 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1bc40 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
1bc50 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69  .  sqlite3*,.  i
1bc60 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64  nt (*xAuth)(void
1bc70 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72  *,int,const char
1bc80 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  *,const char*,co
1bc90 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
1bca0 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a  char*),.  void *
1bcb0 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a  pUserData.);../*
1bcc0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75  .** CAPI3REF: Au
1bcd0 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20  thorizer Return 
1bce0 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Codes.**.** The 
1bcf0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
1bd00 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
1bd10 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  izer callback fu
1bd20 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20  nction] must.** 
1bd30 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53  return either [S
1bd40 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65  QLITE_OK] or one
1bd50 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f   of these two co
1bd60 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72  nstants in order
1bd70 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51  .** to signal SQ
1bd80 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 20  Lite whether or 
1bd90 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69  not the action i
1bda0 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65  s permitted.  Se
1bdb0 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  e the.** [sqlite
1bdc0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1bdd0 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f   | authorizer do
1bde0 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72  cumentation] for
1bdf0 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
1be00 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
1be10 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49  * Note that SQLI
1be20 54 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73  TE_IGNORE is als
1be30 6f 20 75 73 65 64 20 61 73 20 61 20 5b 53 51 4c  o used as a [SQL
1be40 49 54 45 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20 72  ITE_ROLLBACK | r
1be50 65 74 75 72 6e 20 63 6f 64 65 5d 0a 2a 2a 20 66  eturn code].** f
1be60 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33  rom the [sqlite3
1be70 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63  _vtab_on_conflic
1be80 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  t()] interface..
1be90 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1bea0 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20  E_DENY   1   /* 
1beb0 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74  Abort the SQL st
1bec0 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20  atement with an 
1bed0 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65  error */.#define
1bee0 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32   SQLITE_IGNORE 2
1bef0 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f     /* Don't allo
1bf00 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f  w access, but do
1bf10 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20  n't generate an 
1bf20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  error */../*.** 
1bf30 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72  CAPI3REF: Author
1bf40 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65  izer Action Code
1bf50 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  s.**.** The [sql
1bf60 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1bf70 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65  zer()] interface
1bf80 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
1bf90 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a  lback function.*
1bfa0 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65  * that is invoke
1bfb0 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63  d to authorize c
1bfc0 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65  ertain SQL state
1bfd0 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54  ment actions.  T
1bfe0 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
1bff0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61  ameter to the ca
1c000 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74  llback is an int
1c010 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73  eger code that s
1c020 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74  pecifies.** what
1c030 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67   action is being
1c040 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68   authorized.  Th
1c050 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65  ese are the inte
1c060 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73  ger action codes
1c070 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74   that.** the aut
1c080 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1c090 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a   may be passed..
1c0a0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69  **.** These acti
1c0b0 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73  on code values s
1c0c0 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64  ignify what kind
1c0d0 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73   of operation is
1c0e0 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72   to be.** author
1c0f0 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61  ized.  The 3rd a
1c100 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  nd 4th parameter
1c110 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  s to the authori
1c120 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61  zation.** callba
1c130 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c  ck function will
1c140 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f   be parameters o
1c150 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67  r NULL depending
1c160 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65   on which of the
1c170 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75  se.** codes is u
1c180 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
1c190 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28  d parameter.  ^(
1c1a0 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  The 5th paramete
1c1b0 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68  r to the.** auth
1c1c0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1c1d0 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
1c1e0 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61  he database ("ma
1c1f0 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20  in", "temp",.** 
1c200 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61  etc.) if applica
1c210 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68  ble.)^  ^The 6th
1c220 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1c230 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1c240 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20  lback.** is the 
1c250 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65  name of the inne
1c260 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f  r-most trigger o
1c270 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72  r view that is r
1c280 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a  esponsible for.*
1c290 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74  * the access att
1c2a0 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20  empt or NULL if 
1c2b0 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65  this access atte
1c2c0 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20  mpt is directly 
1c2d0 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65  from.** top-leve
1c2e0 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f  l SQL code..*/./
1c2f0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1c300 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1c310 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20  *********** 3rd 
1c320 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68  ************ 4th
1c330 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64   ***********/.#d
1c340 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1c350 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20  ATE_INDEX       
1c360 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20     1   /* Index 
1c370 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
1c380 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1c390 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1c3a0 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  TE_TABLE        
1c3b0 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    2   /* Table N
1c3c0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1c3d0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1c3e0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1c3f0 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20  E_TEMP_INDEX    
1c400 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61   3   /* Index Na
1c410 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
1c420 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1c430 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1c440 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20  _TEMP_TABLE     
1c450 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  4   /* Table Nam
1c460 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1c470 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1c480 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1c490 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35  TEMP_TRIGGER   5
1c4a0 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
1c4b0 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
1c4c0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1c4d0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1c4e0 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20  EMP_VIEW      6 
1c4f0 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
1c500 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1c510 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1c520 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52  SQLITE_CREATE_TR
1c530 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20  IGGER        7  
1c540 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
1c550 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1c560 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1c570 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45  QLITE_CREATE_VIE
1c580 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20  W           8   
1c590 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
1c5a0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1c5b0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1c5c0 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20  LITE_DELETE     
1c5d0 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f             9   /
1c5e0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1c5f0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1c600 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1c610 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20  ITE_DROP_INDEX  
1c620 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a           10   /*
1c630 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
1c640 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1c650 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1c660 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20  TE_DROP_TABLE   
1c670 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20          11   /* 
1c680 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1c690 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1c6a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1c6b0 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45  E_DROP_TEMP_INDE
1c6c0 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49  X      12   /* I
1c6d0 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
1c6e0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1c6f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1c700 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45  _DROP_TEMP_TABLE
1c710 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61        13   /* Ta
1c720 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
1c730 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1c740 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1c750 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45  DROP_TEMP_TRIGGE
1c760 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69  R    14   /* Tri
1c770 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
1c780 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1c790 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1c7a0 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20  ROP_TEMP_VIEW   
1c7b0 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77      15   /* View
1c7c0 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
1c7d0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1c7e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1c7f0 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  OP_TRIGGER      
1c800 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67     16   /* Trigg
1c810 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
1c820 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1c830 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1c840 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20  P_VIEW          
1c850 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e    17   /* View N
1c860 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
1c870 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1c880 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45  fine SQLITE_INSE
1c890 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  RT              
1c8a0 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   18   /* Table N
1c8b0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1c8c0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1c8d0 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d  ine SQLITE_PRAGM
1c8e0 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  A               
1c8f0 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e  19   /* Pragma N
1c900 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20  ame     1st arg 
1c910 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69  or NULL */.#defi
1c920 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20  ne SQLITE_READ  
1c930 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
1c940 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  0   /* Table Nam
1c950 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61  e      Column Na
1c960 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
1c970 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20  e SQLITE_SELECT 
1c980 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31                21
1c990 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
1c9a0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1c9b0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1c9c0 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54   SQLITE_TRANSACT
1c9d0 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20  ION          22 
1c9e0 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20    /* Operation  
1c9f0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1ca00 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1ca10 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20  SQLITE_UPDATE   
1ca20 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20              23  
1ca30 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1ca40 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
1ca50 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1ca60 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20  QLITE_ATTACH    
1ca70 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20             24   
1ca80 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20  /* Filename     
1ca90 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1caa0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1cab0 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20  LITE_DETACH     
1cac0 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f            25   /
1cad0 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20  * Database Name 
1cae0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1caf0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1cb00 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20  ITE_ALTER_TABLE 
1cb10 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a           26   /*
1cb20 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20   Database Name  
1cb30 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1cb40 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1cb50 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20  TE_REINDEX      
1cb60 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20          27   /* 
1cb70 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
1cb80 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1cb90 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1cba0 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20  E_ANALYZE       
1cbb0 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54         28   /* T
1cbc0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1cbd0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1cbe0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1cbf0 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20  _CREATE_VTABLE  
1cc00 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61        29   /* Ta
1cc10 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f  ble Name      Mo
1cc20 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f  dule Name     */
1cc30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1cc40 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20  DROP_VTABLE     
1cc50 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62       30   /* Tab
1cc60 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64  le Name      Mod
1cc70 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  ule Name     */.
1cc80 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
1cc90 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20  UNCTION         
1cca0 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c      31   /* NULL
1ccb0 20 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63              Func
1ccc0 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23  tion Name   */.#
1ccd0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41  define SQLITE_SA
1cce0 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20  VEPOINT         
1ccf0 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61     32   /* Opera
1cd00 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70  tion       Savep
1cd10 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64  oint Name  */.#d
1cd20 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50  efine SQLITE_COP
1cd30 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  Y               
1cd40 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e     0   /* No lon
1cd50 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a  ger used */../*.
1cd60 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61  ** CAPI3REF: Tra
1cd70 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69  cing And Profili
1cd80 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a  ng Functions.**.
1cd90 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1cda0 73 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62  s register callb
1cdb0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68  ack functions th
1cdc0 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 66  at can be used f
1cdd0 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e  or.** tracing an
1cde0 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20  d profiling the 
1cdf0 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c  execution of SQL
1ce00 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
1ce10 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b  ** ^The callback
1ce20 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74   function regist
1ce30 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ered by sqlite3_
1ce40 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b  trace() is invok
1ce50 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73  ed at.** various
1ce60 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53   times when an S
1ce70 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  QL statement is 
1ce80 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71  being run by [sq
1ce90 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
1cea0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74  * ^The sqlite3_t
1ceb0 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20  race() callback 
1cec0 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  is invoked with 
1ced0 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e  a UTF-8 renderin
1cee0 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20  g of the.** SQL 
1cef0 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61  statement text a
1cf00 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
1cf10 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 65  first begins exe
1cf20 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64  cuting..** ^(Add
1cf30 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f  itional sqlite3_
1cf40 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b  trace() callback
1cf50 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a  s might occur.**
1cf60 20 61 73 20 65 61 63 68 20 74 72 69 67 67 65 72   as each trigger
1cf70 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73  ed subprogram is
1cf80 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63   entered.  The c
1cf90 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69  allbacks for tri
1cfa0 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e  ggers.** contain
1cfb0 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d   a UTF-8 SQL com
1cfc0 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69  ment that identi
1cfd0 66 69 65 73 20 74 68 65 20 74 72 69 67 67 65 72  fies the trigger
1cfe0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63  .)^.**.** ^The c
1cff0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1d000 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73   registered by s
1d010 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
1d020 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61   is invoked.** a
1d030 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65  s each SQL state
1d040 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20  ment finishes.  
1d050 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c  ^The profile cal
1d060 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a  lback contains.*
1d070 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73  * the original s
1d080 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e  tatement text an
1d090 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66  d an estimate of
1d0a0 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65   wall-clock time
1d0b0 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20  .** of how long 
1d0c0 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74  that statement t
1d0d0 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68  ook to run.  ^Th
1d0e0 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
1d0f0 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e  ck.** time is in
1d100 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65   units of nanose
1d110 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 74  conds, however t
1d120 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65  he current imple
1d130 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20  mentation.** is 
1d140 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 20  only capable of 
1d150 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f  millisecond reso
1d160 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 69  lution so the si
1d170 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63  x least signific
1d180 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e  ant.** digits in
1d190 20 74 68 65 20 74 69 6d 65 20 61 72 65 20 6d 65   the time are me
1d1a0 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 75  aningless.  Futu
1d1b0 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
1d1c0 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70  QLite.** might p
1d1d0 72 6f 76 69 64 65 20 67 72 65 61 74 65 72 20 72  rovide greater r
1d1e0 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65  esolution on the
1d1f0 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61   profiler callba
1d200 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69  ck.  The.** sqli
1d210 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 66 75  te3_profile() fu
1d220 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64  nction is consid
1d230 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61  ered experimenta
1d240 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a  l and is.** subj
1d250 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
1d260 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
1d270 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 76   of SQLite..*/.v
1d280 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61  oid *sqlite3_tra
1d290 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69  ce(sqlite3*, voi
1d2a0 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a  d(*xTrace)(void*
1d2b0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76  ,const char*), v
1d2c0 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 45 58  oid*);.SQLITE_EX
1d2d0 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20  PERIMENTAL void 
1d2e0 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65  *sqlite3_profile
1d2f0 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f  (sqlite3*,.   vo
1d300 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f  id(*xProfile)(vo
1d310 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  id*,const char*,
1d320 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c  sqlite3_uint64),
1d330 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
1d340 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20  CAPI3REF: Query 
1d350 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63  Progress Callbac
1d360 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ks.**.** ^The sq
1d370 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
1d380 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20  andler(D,N,X,P) 
1d390 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
1d3a0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a   the callback.**
1d3b0 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62   function X to b
1d3c0 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64  e invoked period
1d3d0 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f  ically during lo
1d3e0 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73  ng running calls
1d3f0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
1d400 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65  exec()], [sqlite
1d410 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73  3_step()] and [s
1d420 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1d430 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62  ()] for.** datab
1d440 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44  ase connection D
1d450 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73  .  An example us
1d460 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e  e for this.** in
1d470 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65  terface is to ke
1d480 65 70 20 61 20 47 55 49 20 75 70 64 61 74 65 64  ep a GUI updated
1d490 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20   during a large 
1d4a0 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  query..**.** ^Th
1d4b0 65 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73  e parameter P is
1d4c0 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20   passed through 
1d4d0 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61  as the only para
1d4e0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a  meter to the .**
1d4f0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1d500 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61  on X.  ^The para
1d510 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65 20 6e  meter N is the n
1d520 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69  umber of .** [vi
1d530 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e  rtual machine in
1d540 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74  structions] that
1d550 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 62   are evaluated b
1d560 65 74 77 65 65 6e 20 73 75 63 63 65 73 73 69 76  etween successiv
1d570 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73  e.** invocations
1d580 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   of the callback
1d590 20 58 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20   X..**.** ^Only 
1d5a0 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73  a single progres
1d5b0 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65  s handler may be
1d5c0 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20   defined at one 
1d5d0 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74  time per.** [dat
1d5e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1d5f0 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77  ]; setting a new
1d600 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
1d610 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a  r cancels the.**
1d620 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74   old one.  ^Sett
1d630 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58 20  ing parameter X 
1d640 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73  to NULL disables
1d650 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   the progress ha
1d660 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70  ndler..** ^The p
1d670 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
1d680 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64  is also disabled
1d690 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f   by setting N to
1d6a0 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a   a value less.**
1d6b0 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e   than 1..**.** ^
1d6c0 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  If the progress 
1d6d0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1d6e0 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f   non-zero, the o
1d6f0 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69  peration is.** i
1d700 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 69  nterrupted.  Thi
1d710 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65  s feature can be
1d720 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
1d730 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22  nt a.** "Cancel"
1d740 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49   button on a GUI
1d750 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67   progress dialog
1d760 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20   box..**.** The 
1d770 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
1d780 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e   callback must n
1d790 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74  ot do anything t
1d7a0 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a  hat will modify.
1d7b0 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
1d7c0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
1d7d0 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67  invoked the prog
1d7e0 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  ress handler..**
1d7f0 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
1d800 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1d810 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
1d820 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
1d830 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
1d840 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
1d850 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
1d860 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
1d870 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
1d880 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  **.*/.void sqlit
1d890 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
1d8a0 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  ler(sqlite3*, in
1d8b0 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29  t, int(*)(void*)
1d8c0 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
1d8d0 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69   CAPI3REF: Openi
1d8e0 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62 61 73  ng A New Databas
1d8f0 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a  e Connection.**.
1d900 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
1d910 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74  es open an SQLit
1d920 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
1d930 61 73 20 73 70 65 63 69 66 69 65 64 20 62 79 20  as specified by 
1d940 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  the .** filename
1d950 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20   argument. ^The 
1d960 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
1d970 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  t is interpreted
1d980 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a   as UTF-8 for.**
1d990 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
1d9a0 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
1d9b0 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 46  _v2() and as UTF
1d9c0 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76  -16 in the nativ
1d9d0 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20  e byte.** order 
1d9e0 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
1d9f0 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62  16(). ^(A [datab
1da00 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1da10 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c  handle is usuall
1da20 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e  y.** returned in
1da30 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20   *ppDb, even if 
1da40 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e  an error occurs.
1da50 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70    The only excep
1da60 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20  tion is that.** 
1da70 69 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61  if SQLite is una
1da80 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
1da90 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
1daa0 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
1dab0 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77  ect,.** a NULL w
1dac0 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69  ill be written i
1dad0 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61  nto *ppDb instea
1dae0 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74  d of a pointer t
1daf0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a  o the [sqlite3].
1db00 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49  ** object.)^ ^(I
1db10 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  f the database i
1db20 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72  s opened (and/or
1db30 20 63 72 65 61 74 65 64 29 20 73 75 63 63 65 73   created) succes
1db40 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20  sfully, then.** 
1db50 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72  [SQLITE_OK] is r
1db60 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77  eturned.  Otherw
1db70 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ise an [error co
1db80 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
1db90 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69  )^ ^The.** [sqli
1dba0 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72  te3_errmsg()] or
1dbb0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1dbc0 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63  16()] routines c
1dbd0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62  an be used to ob
1dbe0 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69  tain.** an Engli
1dbf0 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63  sh language desc
1dc00 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65  ription of the e
1dc10 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  rror following a
1dc20 20 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a   failure of any.
1dc30 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ** of the sqlite
1dc40 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65  3_open() routine
1dc50 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65  s..**.** ^The de
1dc60 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66  fault encoding f
1dc70 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20  or the database 
1dc80 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 69 66  will be UTF-8 if
1dc90 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
1dca0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
1dcb0 65 6e 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65  en_v2() is calle
1dcc0 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20  d and.** UTF-16 
1dcd0 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
1dce0 74 65 20 6f 72 64 65 72 20 69 66 20 73 71 6c 69  te order if sqli
1dcf0 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 69 73 20  te3_open16() is 
1dd00 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74  used..**.** Whet
1dd10 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72  her or not an er
1dd20 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20  ror occurs when 
1dd30 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65  it is opened, re
1dd40 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63  sources.** assoc
1dd50 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b  iated with the [
1dd60 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1dd70 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75  ion] handle shou
1dd80 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64 20 62  ld be released b
1dd90 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20  y.** passing it 
1dda0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  to [sqlite3_clos
1ddb0 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20  e()] when it is 
1ddc0 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72  no longer requir
1ddd0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
1dde0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
1ddf0 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20  interface works 
1de00 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65  like sqlite3_ope
1de10 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68  n().** except th
1de20 61 74 20 69 74 20 61 63 63 65 70 74 73 20 74 77  at it accepts tw
1de30 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72  o additional par
1de40 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64 69  ameters for addi
1de50 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a  tional control.*
1de60 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64  * over the new d
1de70 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1de80 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73  on.  ^(The flags
1de90 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
1dea0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1deb0 28 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20  () can take one 
1dec0 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77  of.** the follow
1ded0 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65 73  ing three values
1dee0 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d  , optionally com
1def0 62 69 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a  bined with the .
1df00 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
1df10 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54  NOMUTEX], [SQLIT
1df20 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
1df30 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ], [SQLITE_OPEN_
1df40 53 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a  SHAREDCACHE],.**
1df50 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52   [SQLITE_OPEN_PR
1df60 49 56 41 54 45 43 41 43 48 45 5d 2c 20 61 6e 64  IVATECACHE], and
1df70 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  /or [SQLITE_OPEN
1df80 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a  _URI] flags:)^.*
1df90 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c  *.** <dl>.** ^(<
1dfa0 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
1dfb0 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a  READONLY]</dt>.*
1dfc0 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
1dfd0 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20  se is opened in 
1dfe0 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20  read-only mode. 
1dff0 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
1e000 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72   does not.** alr
1e010 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65  eady exist, an e
1e020 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
1e030 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
1e040 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45  (<dt>[SQLITE_OPE
1e050 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74  N_READWRITE]</dt
1e060 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
1e070 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
1e080 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
1e090 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69  writing if possi
1e0a0 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a  ble, or reading.
1e0b0 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66  ** only if the f
1e0c0 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f  ile is write pro
1e0d0 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70  tected by the op
1e0e0 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20  erating system. 
1e0f0 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61   In either.** ca
1e100 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
1e110 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 69  must already exi
1e120 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e  st, otherwise an
1e130 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
1e140 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  ed.</dd>)^.**.**
1e150 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f   ^(<dt>[SQLITE_O
1e160 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c  PEN_READWRITE] |
1e170 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
1e180 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  EATE]</dt>.** <d
1e190 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
1e1a0 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
1e1b0 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67  ding and writing
1e1c0 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74 65 64  , and is created
1e1d0 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e   if.** it does n
1e1e0 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  ot already exist
1e1f0 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 62 65  . This is the be
1e200 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 61  havior that is a
1e210 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a  lways used for.*
1e220 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
1e230 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
1e240 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  n16().</dd>)^.**
1e250 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20   </dl>.**.** If 
1e260 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
1e270 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
1e280 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e  n_v2() is not on
1e290 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62  e of the.** comb
1e2a0 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61  inations shown a
1e2b0 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20  bove optionally 
1e2c0 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 6f 74  combined with ot
1e2d0 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  her.** [SQLITE_O
1e2e0 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53  PEN_READONLY | S
1e2f0 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74  QLITE_OPEN_* bit
1e300 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62  s].** then the b
1e310 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
1e320 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ined..**.** ^If 
1e330 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
1e340 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69  _NOMUTEX] flag i
1e350 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20  s set, then the 
1e360 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1e370 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20  ion.** opens in 
1e380 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  the multi-thread
1e390 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
1e3a0 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  ] as long as the
1e3b0 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a   single-thread.*
1e3c0 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62  * mode has not b
1e3d0 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69  een set at compi
1e3e0 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74  le-time or start
1e3f0 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a  -time.  ^If the.
1e400 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
1e410 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20  FULLMUTEX] flag 
1e420 69 73 20 73 65 74 20 74 68 65 6e 20 74 68 65 20  is set then the 
1e430 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1e440 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20  ion opens.** in 
1e450 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b  the serialized [
1e460 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
1e470 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68  unless single-th
1e480 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76  read was.** prev
1e490 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20  iously selected 
1e4a0 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
1e4b0 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a  or start-time..*
1e4c0 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  * ^The [SQLITE_O
1e4d0 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d  PEN_SHAREDCACHE]
1e4e0 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65   flag causes the
1e4f0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1e500 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c  tion to be.** el
1e510 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73  igible to use [s
1e520 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65  hared cache mode
1e530 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ], regardless of
1e540 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
1e550 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20  shared.** cache 
1e560 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67  is enabled using
1e570 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65   [sqlite3_enable
1e580 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d  _shared_cache()]
1e590 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49  .  ^The.** [SQLI
1e5a0 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
1e5b0 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65  ACHE] flag cause
1e5c0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
1e5d0 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74  onnection to not
1e5e0 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65 20  .** participate 
1e5f0 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68 65  in [shared cache
1e600 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69   mode] even if i
1e610 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  t is enabled..**
1e620 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20  .** ^The fourth 
1e630 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
1e640 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
1e650 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
1e660 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66  e.** [sqlite3_vf
1e670 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64  s] object that d
1e680 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61  efines the opera
1e690 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65  ting system inte
1e6a0 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68  rface that.** th
1e6b0 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  e new database c
1e6c0 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64  onnection should
1e6d0 20 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66   use.  ^If the f
1e6e0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
1e6f0 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69  is.** a NULL poi
1e700 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65  nter then the de
1e710 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
1e720 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73  fs] object is us
1e730 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
1e740 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a  e filename is ":
1e750 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61  memory:", then a
1e760 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72   private, tempor
1e770 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61  ary in-memory da
1e780 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65  tabase.** is cre
1e790 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e  ated for the con
1e7a0 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20  nection.  ^This 
1e7b0 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
1e7c0 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77  se will vanish w
1e7d0 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  hen.** the datab
1e7e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
1e7f0 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72  s closed.  Futur
1e800 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
1e810 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61  Lite might.** ma
1e820 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 69  ke use of additi
1e830 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c  onal special fil
1e840 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67 69  enames that begi
1e850 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22 20 63  n with the ":" c
1e860 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20  haracter..** It 
1e870 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
1e880 68 61 74 20 77 68 65 6e 20 61 20 64 61 74 61 62  hat when a datab
1e890 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74  ase filename act
1e8a0 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e  ually does begin
1e8b0 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63   with.** a ":" c
1e8c0 68 61 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f  haracter you sho
1e8d0 75 6c 64 20 70 72 65 66 69 78 20 74 68 65 20 66  uld prefix the f
1e8e0 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70  ilename with a p
1e8f0 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a  athname such as.
1e900 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64  ** "./" to avoid
1e910 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a   ambiguity..**.*
1e920 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61  * ^If the filena
1e930 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73  me is an empty s
1e940 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72  tring, then a pr
1e950 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79  ivate, temporary
1e960 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61  .** on-disk data
1e970 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65  base will be cre
1e980 61 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69  ated.  ^This pri
1e990 76 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69  vate database wi
1e9a0 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74  ll be.** automat
1e9b0 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61  ically deleted a
1e9c0 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61  s soon as the da
1e9d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1e9e0 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  n is closed..**.
1e9f0 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ** [[URI filenam
1ea00 65 73 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70  es in sqlite3_op
1ea10 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46  en()]] <h3>URI F
1ea20 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a  ilenames</h3>.**
1ea30 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66 69 6c  .** ^If [URI fil
1ea40 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72 65 74  ename] interpret
1ea50 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ation is enabled
1ea60 2c 20 61 6e 64 20 74 68 65 20 66 69 6c 65 6e 61  , and the filena
1ea70 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62  me argument.** b
1ea80 65 67 69 6e 73 20 77 69 74 68 20 22 66 69 6c 65  egins with "file
1ea90 3a 22 2c 20 74 68 65 6e 20 74 68 65 20 66 69 6c  :", then the fil
1eaa0 65 6e 61 6d 65 20 69 73 20 69 6e 74 65 72 70 72  ename is interpr
1eab0 65 74 65 64 20 61 73 20 61 20 55 52 49 2e 20 5e  eted as a URI. ^
1eac0 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20  URI.** filename 
1ead0 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69  interpretation i
1eae0 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65  s enabled if the
1eaf0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52   [SQLITE_OPEN_UR
1eb00 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65  I] flag is.** se
1eb10 74 20 69 6e 20 74 68 65 20 66 6f 75 72 74 68 20  t in the fourth 
1eb20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
1eb30 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f  te3_open_v2(), o
1eb40 72 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 62  r if it has.** b
1eb50 65 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62  een enabled glob
1eb60 61 6c 6c 79 20 75 73 69 6e 67 20 74 68 65 20 5b  ally using the [
1eb70 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
1eb80 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68 20 74  I] option with t
1eb90 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  he.** [sqlite3_c
1eba0 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f 64 20  onfig()] method 
1ebb0 6f 72 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54  or by the [SQLIT
1ebc0 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69  E_USE_URI] compi
1ebd0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a  le-time option..
1ebe0 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69 74 65 20  ** As of SQLite 
1ebf0 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 55  version 3.7.7, U
1ec00 52 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65  RI filename inte
1ec10 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 74 75  rpretation is tu
1ec20 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64  rned off.** by d
1ec30 65 66 61 75 6c 74 2c 20 62 75 74 20 66 75 74 75  efault, but futu
1ec40 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
1ec50 51 4c 69 74 65 20 6d 69 67 68 74 20 65 6e 61 62  QLite might enab
1ec60 6c 65 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a  le URI filename.
1ec70 2a 2a 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  ** interpretatio
1ec80 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20 53  n by default.  S
1ec90 65 65 20 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ee "[URI filenam
1eca0 65 73 5d 22 20 66 6f 72 20 61 64 64 69 74 69 6f  es]" for additio
1ecb0 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  nal.** informati
1ecc0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69  on..**.** URI fi
1ecd0 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61 72 73  lenames are pars
1ece0 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20  ed according to 
1ecf0 52 46 43 20 33 39 38 36 2e 20 5e 49 66 20 74 68  RFC 3986. ^If th
1ed00 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73 20 61  e URI contains a
1ed10 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c 20  n.** authority, 
1ed20 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62 65 20  then it must be 
1ed30 65 69 74 68 65 72 20 61 6e 20 65 6d 70 74 79 20  either an empty 
1ed40 73 74 72 69 6e 67 20 6f 72 20 74 68 65 20 73 74  string or the st
1ed50 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68  ring .** "localh
1ed60 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 20 61 75  ost". ^If the au
1ed70 74 68 6f 72 69 74 79 20 69 73 20 6e 6f 74 20 61  thority is not a
1ed80 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f  n empty string o
1ed90 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61  r "localhost", a
1eda0 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20 72  n .** error is r
1edb0 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20 63  eturned to the c
1edc0 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72 61 67  aller. ^The frag
1edd0 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  ment component o
1ede0 66 20 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20  f a URI, if .** 
1edf0 70 72 65 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f  present, is igno
1ee00 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  red..**.** ^SQLi
1ee10 74 65 20 75 73 65 73 20 74 68 65 20 70 61 74 68  te uses the path
1ee20 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68   component of th
1ee30 65 20 55 52 49 20 61 73 20 74 68 65 20 6e 61 6d  e URI as the nam
1ee40 65 20 6f 66 20 74 68 65 20 64 69 73 6b 20 66 69  e of the disk fi
1ee50 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74  le.** which cont
1ee60 61 69 6e 73 20 74 68 65 20 64 61 74 61 62 61 73  ains the databas
1ee70 65 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20  e. ^If the path 
1ee80 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 27 2f  begins with a '/
1ee90 27 20 63 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a  ' character, .**
1eea0 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 74 65   then it is inte
1eeb0 72 70 72 65 74 65 64 20 61 73 20 61 6e 20 61 62  rpreted as an ab
1eec0 73 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e 49 66  solute path. ^If
1eed0 20 74 68 65 20 70 61 74 68 20 64 6f 65 73 20 6e   the path does n
1eee0 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74  ot begin .** wit
1eef0 68 20 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67  h a '/' (meaning
1ef00 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72   that the author
1ef10 69 74 79 20 73 65 63 74 69 6f 6e 20 69 73 20 6f  ity section is o
1ef20 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20  mitted from the 
1ef30 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65  URI).** then the
1ef40 20 70 61 74 68 20 69 73 20 69 6e 74 65 72 70 72   path is interpr
1ef50 65 74 65 64 20 61 73 20 61 20 72 65 6c 61 74 69  eted as a relati
1ef60 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 4f 6e  ve path. .** ^On
1ef70 20 77 69 6e 64 6f 77 73 2c 20 74 68 65 20 66 69   windows, the fi
1ef80 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  rst component of
1ef90 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74   an absolute pat
1efa0 68 20 0a 2a 2a 20 69 73 20 61 20 64 72 69 76 65  h .** is a drive
1efb0 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 20 28   specification (
1efc0 65 2e 67 2e 20 22 43 3a 22 29 2e 0a 2a 2a 0a 2a  e.g. "C:")..**.*
1efd0 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20 71 75 65  * [[core URI que
1efe0 72 79 20 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a  ry parameters]].
1eff0 2a 2a 20 54 68 65 20 71 75 65 72 79 20 63 6f 6d  ** The query com
1f000 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20  ponent of a URI 
1f010 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70 61 72 61  may contain para
1f020 6d 65 74 65 72 73 20 74 68 61 74 20 61 72 65 20  meters that are 
1f030 69 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a 20 65  interpreted.** e
1f040 69 74 68 65 72 20 62 79 20 53 51 4c 69 74 65 20  ither by SQLite 
1f050 69 74 73 65 6c 66 2c 20 6f 72 20 62 79 20 61 20  itself, or by a 
1f060 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d 20 56 46  [VFS | custom VF
1f070 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
1f080 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  ]..** SQLite int
1f090 65 72 70 72 65 74 73 20 74 68 65 20 66 6f 6c 6c  erprets the foll
1f0a0 6f 77 69 6e 67 20 74 68 72 65 65 20 71 75 65 72  owing three quer
1f0b0 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a  y parameters:.**
1f0c0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  .** <ul>.**   <l
1f0d0 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e  i> <b>vfs</b>: ^
1f0e0 54 68 65 20 22 76 66 73 22 20 70 61 72 61 6d 65  The "vfs" parame
1f0f0 74 65 72 20 6d 61 79 20 62 65 20 75 73 65 64 20  ter may be used 
1f100 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 6e  to specify the n
1f110 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20  ame of.**     a 
1f120 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20  VFS object that 
1f130 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65  provides the ope
1f140 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e  rating system in
1f150 74 65 72 66 61 63 65 20 74 68 61 74 20 73 68 6f  terface that sho
1f160 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73  uld.**     be us
1f170 65 64 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  ed to access the
1f180 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f   database file o
1f190 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73  n disk. ^If this
1f1a0 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74   option is set t
1f1b0 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74  o.**     an empt
1f1c0 79 20 73 74 72 69 6e 67 20 74 68 65 20 64 65 66  y string the def
1f1d0 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20  ault VFS object 
1f1e0 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66  is used. ^Specif
1f1f0 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a  ying an unknown.
1f200 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20 61 6e  **     VFS is an
1f210 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69   error. ^If sqli
1f220 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
1f230 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 76 66   used and the vf
1f240 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20  s option is.**  
1f250 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e     present, then
1f260 20 74 68 65 20 56 46 53 20 73 70 65 63 69 66 69   the VFS specifi
1f270 65 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e  ed by the option
1f280 20 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63   takes precedenc
1f290 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68  e over.**     th
1f2a0 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61  e value passed a
1f2b0 73 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  s the fourth par
1f2c0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1f2d0 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  3_open_v2()..**.
1f2e0 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64  **   <li> <b>mod
1f2f0 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64  e</b>: ^(The mod
1f300 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
1f310 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72  be set to either
1f320 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20   "ro", "rw",.** 
1f330 20 20 20 20 22 72 77 63 22 2c 20 6f 72 20 22 6d      "rwc", or "m
1f340 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70 74 69  emory". Attempti
1f350 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20  ng to set it to 
1f360 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20  any other value 
1f370 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72 72  is.**     an err
1f380 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49  or)^. .**     ^I
1f390 66 20 22 72 6f 22 20 69 73 20 73 70 65 63 69 66  f "ro" is specif
1f3a0 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61  ied, then the da
1f3b0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
1f3c0 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a   for read-only .
1f3d0 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a  **     access, j
1f3e0 75 73 74 20 61 73 20 69 66 20 74 68 65 20 5b 53  ust as if the [S
1f3f0 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
1f400 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65  NLY] flag had be
1f410 65 6e 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a  en set in the .*
1f420 2a 20 20 20 20 20 74 68 69 72 64 20 61 72 67 75  *     third argu
1f430 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
1f440 70 72 65 70 61 72 65 5f 76 32 28 29 2e 20 5e 49  prepare_v2(). ^I
1f450 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f  f the mode optio
1f460 6e 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20  n is set to .** 
1f470 20 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74      "rw", then t
1f480 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
1f490 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77  pened for read-w
1f4a0 72 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72  rite (but not cr
1f4b0 65 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63  eate) .**     ac
1f4c0 63 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49  cess, as if SQLI
1f4d0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
1f4e0 45 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54  E (but not SQLIT
1f4f0 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68  E_OPEN_CREATE) h
1f500 61 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20  ad .**     been 
1f510 73 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63  set. ^Value "rwc
1f520 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20  " is equivalent 
1f530 74 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20  to setting both 
1f540 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f  .**     SQLITE_O
1f550 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e  PEN_READWRITE an
1f560 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  d SQLITE_OPEN_CR
1f570 45 41 54 45 2e 20 20 5e 49 66 20 74 68 65 20 6d  EATE.  ^If the m
1f580 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a  ode option is.**
1f590 20 20 20 20 20 73 65 74 20 74 6f 20 22 6d 65 6d       set to "mem
1f5a0 6f 72 79 22 20 74 68 65 6e 20 61 20 70 75 72 65  ory" then a pure
1f5b0 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61   [in-memory data
1f5c0 62 61 73 65 5d 20 74 68 61 74 20 6e 65 76 65 72  base] that never
1f5d0 20 72 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72   reads.**     or
1f5e0 20 77 72 69 74 65 73 20 66 72 6f 6d 20 64 69 73   writes from dis
1f5f0 6b 20 69 73 20 75 73 65 64 2e 20 5e 49 74 20 69  k is used. ^It i
1f600 73 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70  s an error to sp
1f610 65 63 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f  ecify a value fo
1f620 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f 64  r.**     the mod
1f630 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74  e parameter that
1f640 20 69 73 20 6c 65 73 73 20 72 65 73 74 72 69 63   is less restric
1f650 74 69 76 65 20 74 68 61 6e 20 74 68 61 74 20 73  tive than that s
1f660 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20  pecified by.**  
1f670 20 20 20 74 68 65 20 66 6c 61 67 73 20 70 61 73     the flags pas
1f680 73 65 64 20 69 6e 20 74 68 65 20 74 68 69 72 64  sed in the third
1f690 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
1f6a0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
1f6b0 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62  .**.**   <li> <b
1f6c0 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65  >cache</b>: ^The
1f6d0 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72   cache parameter
1f6e0 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65   may be set to e
1f6f0 69 74 68 65 72 20 22 73 68 61 72 65 64 22 20 6f  ither "shared" o
1f700 72 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61 74  r.**     "privat
1f710 65 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 20  e". ^Setting it 
1f720 74 6f 20 22 73 68 61 72 65 64 22 20 69 73 20 65  to "shared" is e
1f730 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74  quivalent to set
1f740 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20  ting the.**     
1f750 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
1f760 45 44 43 41 43 48 45 20 62 69 74 20 69 6e 20 74  EDCACHE bit in t
1f770 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
1f780 74 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20  t passed to.**  
1f790 20 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f     sqlite3_open_
1f7a0 76 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 74  v2(). ^Setting t
1f7b0 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74  he cache paramet
1f7c0 65 72 20 74 6f 20 22 70 72 69 76 61 74 65 22 20  er to "private" 
1f7d0 69 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 76  is .**     equiv
1f7e0 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67  alent to setting
1f7f0 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e   the SQLITE_OPEN
1f800 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 62 69  _PRIVATECACHE bi
1f810 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 71  t..**     ^If sq
1f820 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
1f830 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20  is used and the 
1f840 22 63 61 63 68 65 22 20 70 61 72 61 6d 65 74 65  "cache" paramete
1f850 72 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e 0a  r is present in.
1f860 2a 2a 20 20 20 20 20 61 20 55 52 49 20 66 69 6c  **     a URI fil
1f870 65 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 65  ename, its value
1f880 20 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20 62   overrides any b
1f890 65 68 61 76 69 6f 75 72 20 72 65 71 75 65 73 74  ehaviour request
1f8a0 65 64 20 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a  ed by setting.**
1f8b0 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e       SQLITE_OPEN
1f8c0 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 6f 72  _PRIVATECACHE or
1f8d0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41   SQLITE_OPEN_SHA
1f8e0 52 45 44 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a  REDCACHE flag..*
1f8f0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53  * </ul>.**.** ^S
1f900 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b  pecifying an unk
1f910 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69  nown parameter i
1f920 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70  n the query comp
1f930 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69  onent of a URI i
1f940 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f  s not an.** erro
1f950 72 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  r.  Future versi
1f960 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ons of SQLite mi
1f970 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61  ght understand a
1f980 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a  dditional query.
1f990 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ** parameters.  
1f9a0 53 65 65 20 22 5b 71 75 65 72 79 20 70 61 72 61  See "[query para
1f9b0 6d 65 74 65 72 73 20 77 69 74 68 20 73 70 65 63  meters with spec
1f9c0 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53  ial meaning to S
1f9d0 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61  QLite]" for.** a
1f9e0 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
1f9f0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55  ation..**.** [[U
1fa00 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d  RI filename exam
1fa10 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66  ples]] <h3>URI f
1fa20 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73  ilename examples
1fa30 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62  </h3>.**.** <tab
1fa40 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c  le border="1" al
1fa50 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70  ign=center cellp
1fa60 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72  adding=5>.** <tr
1fa70 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61  ><th> URI filena
1fa80 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73  mes <th> Results
1fa90 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
1faa0 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a  e:data.db <td> .
1fab0 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
1fac0 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e   the file "data.
1fad0 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65  db" in the curre
1fae0 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a  nt directory..**
1faf0 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
1fb00 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
1fb10 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20  b<br>.**        
1fb20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66    file:///home/f
1fb30 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e  red/data.db <br>
1fb40 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69   .**          fi
1fb50 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68  le://localhost/h
1fb60 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
1fb70 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20   <br> <td> .**  
1fb80 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65          Open the
1fb90 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 22   database file "
1fba0 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
1fbb0 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  db"..** <tr><td>
1fbc0 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72   file://darkstar
1fbd0 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
1fbe0 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  db <td> .**     
1fbf0 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22       An error. "
1fc00 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74  darkstar" is not
1fc10 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75   a recognized au
1fc20 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e  thority..** <tr>
1fc30 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65  <td style="white
1fc40 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20  -space:nowrap"> 
1fc50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c  .**          fil
1fc60 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74  e:///C:/Document
1fc70 73 25 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e  s%20and%20Settin
1fc80 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f  gs/fred/Desktop/
1fc90 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c  data.db.**     <
1fca0 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79  td> Windows only
1fcb0 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20  : Open the file 
1fcc0 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65  "data.db" on fre
1fcd0 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64  d's desktop on d
1fce0 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  rive.**         
1fcf0 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74   C:. Note that t
1fd00 68 65 20 25 32 30 20 65 73 63 61 70 69 6e 67 20  he %20 escaping 
1fd10 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20  in this example 
1fd20 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  is not strictly 
1fd30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63  .**          nec
1fd40 65 73 73 61 72 79 20 2d 20 73 70 61 63 65 20 63  essary - space c
1fd50 68 61 72 61 63 74 65 72 73 20 63 61 6e 20 62 65  haracters can be
1fd60 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a   used literally.
1fd70 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 55  **          in U
1fd80 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a  RI filenames..**
1fd90 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64   <tr><td> file:d
1fda0 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63  ata.db?mode=ro&c
1fdb0 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64  ache=private <td
1fdc0 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  > .**          O
1fdd0 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64  pen file "data.d
1fde0 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  b" in the curren
1fdf0 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20  t directory for 
1fe00 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73  read-only access
1fe10 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65  ..**          Re
1fe20 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
1fe30 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65  her or not share
1fe40 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20  d-cache mode is 
1fe50 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20  enabled by.**   
1fe60 20 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20         default, 
1fe70 75 73 65 20 61 20 70 72 69 76 61 74 65 20 63 61  use a private ca
1fe80 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  che..** <tr><td>
1fe90 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64   file:/home/fred
1fea0 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69  /data.db?vfs=uni
1feb0 78 2d 6e 6f 6c 6f 63 6b 20 3c 74 64 3e 0a 2a 2a  x-nolock <td>.**
1fec0 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66            Open f
1fed0 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f  ile "/home/fred/
1fee0 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74 68  data.db". Use th
1fef0 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 22 75  e special VFS "u
1ff00 6e 69 78 2d 6e 6f 6c 6f 63 6b 22 2e 0a 2a 2a 20  nix-nolock"..** 
1ff10 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61  <tr><td> file:da
1ff20 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f  ta.db?mode=reado
1ff30 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  nly <td> .**    
1ff40 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20        An error. 
1ff50 22 72 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f  "readonly" is no
1ff60 74 20 61 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e  t a valid option
1ff70 20 66 6f 72 20 74 68 65 20 22 6d 6f 64 65 22 20   for the "mode" 
1ff80 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f  parameter..** </
1ff90 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52  table>.**.** ^UR
1ffa0 49 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73  I hexadecimal es
1ffb0 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 28  cape sequences (
1ffc0 25 48 48 29 20 61 72 65 20 73 75 70 70 6f 72 74  %HH) are support
1ffd0 65 64 20 77 69 74 68 69 6e 20 74 68 65 20 70 61  ed within the pa
1ffe0 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20  th and.** query 
1fff0 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20  components of a 
20000 55 52 49 2e 20 41 20 68 65 78 61 64 65 63 69 6d  URI. A hexadecim
20010 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e  al escape sequen
20020 63 65 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 61  ce consists of a
20030 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73 69 67 6e  .** percent sign
20040 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65   - "%" - followe
20050 64 20 62 79 20 65 78 61 63 74 6c 79 20 74 77 6f  d by exactly two
20060 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64 69 67   hexadecimal dig
20070 69 74 73 20 0a 2a 2a 20 73 70 65 63 69 66 79 69  its .** specifyi
20080 6e 67 20 61 6e 20 6f 63 74 65 74 20 76 61 6c 75  ng an octet valu
20090 65 2e 20 5e 42 65 66 6f 72 65 20 74 68 65 20 70  e. ^Before the p
200a0 61 74 68 20 6f 72 20 71 75 65 72 79 20 63 6f 6d  ath or query com
200b0 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20  ponents of a.** 
200c0 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 61 72 65  URI filename are
200d0 20 69 6e 74 65 72 70 72 65 74 65 64 2c 20 74 68   interpreted, th
200e0 65 79 20 61 72 65 20 65 6e 63 6f 64 65 64 20 75  ey are encoded u
200f0 73 69 6e 67 20 55 54 46 2d 38 20 61 6e 64 20 61  sing UTF-8 and a
20100 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d  ll .** hexadecim
20110 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e  al escape sequen
20120 63 65 73 20 72 65 70 6c 61 63 65 64 20 62 79 20  ces replaced by 
20130 61 20 73 69 6e 67 6c 65 20 62 79 74 65 20 63 6f  a single byte co
20140 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20  ntaining the.** 
20150 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63  corresponding oc
20160 74 65 74 2e 20 49 66 20 74 68 69 73 20 70 72 6f  tet. If this pro
20170 63 65 73 73 20 67 65 6e 65 72 61 74 65 73 20 61  cess generates a
20180 6e 20 69 6e 76 61 6c 69 64 20 55 54 46 2d 38 20  n invalid UTF-8 
20190 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65  encoding,.** the
201a0 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
201b0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62  efined..**.** <b
201c0 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73  >Note to Windows
201d0 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65   users:</b>  The
201e0 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66   encoding used f
201f0 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  or the filename 
20200 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73  argument.** of s
20210 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
20220 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  d sqlite3_open_v
20230 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d  2() must be UTF-
20240 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a  8, not whatever.
20250 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63  ** codepage is c
20260 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
20270 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e  .  Filenames con
20280 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74  taining internat
20290 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74  ional.** charact
202a0 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ers must be conv
202b0 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70  erted to UTF-8 p
202c0 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20  rior to passing 
202d0 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c  them into.** sql
202e0 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
202f0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
20300 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
20310 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63  _open(.  const c
20320 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  har *filename,  
20330 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
20340 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f  ename (UTF-8) */
20350 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
20360 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b          /* OU
20370 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
20380 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  dle */.);.int sq
20390 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20  lite3_open16(.  
203a0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65  const void *file
203b0 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
203c0 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
203d0 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74  F-16) */.  sqlit
203e0 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20  e3 **ppDb       
203f0 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
20400 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29  e db handle */.)
20410 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  ;.int sqlite3_op
20420 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63  en_v2(.  const c
20430 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  har *filename,  
20440 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
20450 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f  ename (UTF-8) */
20460 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
20470 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b,         /* OU
20480 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
20490 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61  dle */.  int fla
204a0 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  gs,             
204b0 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63   /* Flags */.  c
204c0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20  onst char *zVfs 
204d0 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
204e0 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20  f VFS module to 
204f0 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  use */.);../*.**
20500 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
20510 6e 20 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49  n Values For URI
20520 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a   Parameters.**.*
20530 2a 20 54 68 65 73 65 20 61 72 65 20 75 74 69 6c  * These are util
20540 69 74 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73  ity routines, us
20550 65 66 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c  eful to VFS impl
20560 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61  ementations, tha
20570 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65  t check.** to se
20580 65 20 69 66 20 61 20 64 61 74 61 62 61 73 65 20  e if a database 
20590 66 69 6c 65 20 77 61 73 20 61 20 55 52 49 20 74  file was a URI t
205a0 68 61 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20  hat contained a 
205b0 73 70 65 63 69 66 69 63 20 71 75 65 72 79 20 0a  specific query .
205c0 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e  ** parameter, an
205d0 64 20 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20  d if so obtains 
205e0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61  the value of tha
205f0 74 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  t query paramete
20600 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73  r..**.** If F is
20610 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
20620 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70  lename pointer p
20630 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78  assed into the x
20640 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66  Open() method of
20650 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65   .** a VFS imple
20660 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74  mentation when t
20670 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
20680 65 72 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61  er to xOpen() ha
20690 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72  s one or .** mor
206a0 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  e of the [SQLITE
206b0 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53  _OPEN_URI] or [S
206c0 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
206d0 44 42 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64  DB] bits set and
206e0 0a 2a 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d  .** P is the nam
206f0 65 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 70  e of the query p
20700 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a  arameter, then.*
20710 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61  * sqlite3_uri_pa
20720 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74  rameter(F,P) ret
20730 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f  urns the value o
20740 66 20 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d  f the P.** param
20750 65 74 65 72 20 69 66 20 69 74 20 65 78 69 73 74  eter if it exist
20760 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s or a NULL poin
20770 74 65 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f  ter if P does no
20780 74 20 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a  t appear as a .*
20790 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  * query paramete
207a0 72 20 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73  r on F.  If P is
207b0 20 61 20 71 75 65 72 79 20 70 61 72 61 6d 65 74   a query paramet
207c0 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e  er of F.** has n
207d0 6f 20 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65  o explicit value
207e0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75  , then sqlite3_u
207f0 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50  ri_parameter(F,P
20800 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70  ) returns.** a p
20810 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70  ointer to an emp
20820 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ty string..**.**
20830 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69   The sqlite3_uri
20840 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
20850 72 6f 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20  routine assumes 
20860 74 68 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c  that P is a bool
20870 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ean.** parameter
20880 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75   and returns tru
20890 65 20 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28  e (1) or false (
208a0 30 29 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20  0) according to 
208b0 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  the value.** of 
208c0 50 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  P.  The sqlite3_
208d0 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
208e0 42 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  B) routine retur
208f0 6e 73 20 74 72 75 65 20 28 31 29 20 69 66 20 74  ns true (1) if t
20900 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71  he.** value of q
20910 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50  uery parameter P
20920 20 69 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22   is one of "yes"
20930 2c 20 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e  , "true", or "on
20940 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65  " in any.** case
20950 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65   or if the value
20960 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e   begins with a n
20970 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20  on-zero number. 
20980 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33   The .** sqlite3
20990 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
209a0 2c 42 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ,B) routines ret
209b0 75 72 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69  urns false (0) i
209c0 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a  f the value of.*
209d0 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  * query paramete
209e0 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e  r P is one of "n
209f0 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20  o", "false", or 
20a00 22 6f 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73  "off" in any cas
20a10 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76  e or.** if the v
20a20 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68  alue begins with
20a30 20 61 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e   a numeric zero.
20a40 20 20 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20    If P is not a 
20a50 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74  query.** paramet
20a60 65 72 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68  er on F or if th
20a70 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20  e value of P is 
20a80 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61  does not match a
20a90 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f  ny of the.** abo
20aa0 76 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ve, then sqlite3
20ab0 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
20ac0 2c 42 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d  ,B) returns (B!=
20ad0 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  0)..**.** The sq
20ae0 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28  lite3_uri_int64(
20af0 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63  F,P,D) routine c
20b00 6f 6e 76 65 72 74 73 20 74 68 65 20 76 61 6c 75  onverts the valu
20b10 65 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a  e of P into a.**
20b20 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
20b30 6e 74 65 67 65 72 20 61 6e 64 20 72 65 74 75 72  nteger and retur
20b40 6e 73 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c  ns that integer,
20b50 20 6f 72 20 44 20 69 66 20 50 20 64 6f 65 73 20   or D if P does 
20b60 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49  not.** exist.  I
20b70 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50  f the value of P
20b80 20 69 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74   is something ot
20b90 68 65 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65  her than an inte
20ba0 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72  ger, then.** zer
20bb0 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  o is returned..*
20bc0 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20  * .** If F is a 
20bd0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68  NULL pointer, th
20be0 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70  en sqlite3_uri_p
20bf0 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65  arameter(F,P) re
20c00 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a  turns NULL and.*
20c10 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  * sqlite3_uri_bo
20c20 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74  olean(F,P,B) ret
20c30 75 72 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73  urns B.  If F is
20c40 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e   not a NULL poin
20c50 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f  ter and.** is no
20c60 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  t a database fil
20c70 65 20 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74  e pathname point
20c80 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 70  er that SQLite p
20c90 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78  assed into the x
20ca0 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68  Open.** VFS meth
20cb0 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  od, then the beh
20cc0 61 76 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f  avior of this ro
20cd0 75 74 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e  utine is undefin
20ce0 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a  ed and probably.
20cf0 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a  ** undesirable..
20d00 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
20d10 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d  qlite3_uri_param
20d20 65 74 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20  eter(const char 
20d30 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73  *zFilename, cons
20d40 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b  t char *zParam);
20d50 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 75 72 69  .int sqlite3_uri
20d60 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63  _boolean(const c
20d70 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73  har *zFile, cons
20d80 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20  t char *zParam, 
20d90 69 6e 74 20 62 44 65 66 61 75 6c 74 29 3b 0a 73  int bDefault);.s
20da0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
20db0 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 63  ite3_uri_int64(c
20dc0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73  onst char*, cons
20dd0 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33  t char*, sqlite3
20de0 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  _int64);.../*.**
20df0 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72   CAPI3REF: Error
20e00 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61   Codes And Messa
20e10 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ges.**.** ^The s
20e20 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
20e30 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
20e40 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b  ns the numeric [
20e50 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a  result code] or.
20e60 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
20e70 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68  ult code] for th
20e80 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61  e most recent fa
20e90 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41  iled sqlite3_* A
20ea0 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63  PI call.** assoc
20eb0 69 61 74 65 64 20 77 69 74 68 20 61 20 5b 64 61  iated with a [da
20ec0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
20ed0 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f 72 20 41  n]. If a prior A
20ee0 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a  PI call failed.*
20ef0 2a 20 62 75 74 20 74 68 65 20 6d 6f 73 74 20 72  * but the most r
20f00 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 73  ecent API call s
20f10 75 63 63 65 65 64 65 64 2c 20 74 68 65 20 72 65  ucceeded, the re
20f20 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a  turn value from.
20f30 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  ** sqlite3_errco
20f40 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65  de() is undefine
20f50 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  d.  ^The sqlite3
20f60 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64  _extended_errcod
20f70 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  e().** interface
20f80 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 78 63   is the same exc
20f90 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 77 61  ept that it alwa
20fa0 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a  ys returns the .
20fb0 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
20fc0 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77  ult code] even w
20fd0 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73  hen extended res
20fe0 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a  ult codes are.**
20ff0 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a   disabled..**.**
21000 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72   ^The sqlite3_er
21010 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74  rmsg() and sqlit
21020 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65  e3_errmsg16() re
21030 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e  turn English-lan
21040 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68  guage.** text th
21050 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65  at describes the
21060 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65   error, as eithe
21070 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  r UTF-8 or UTF-1
21080 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  6 respectively..
21090 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68  ** ^(Memory to h
210a0 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65  old the error me
210b0 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
210c0 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c  managed internal
210d0 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  ly..** The appli
210e0 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20  cation does not 
210f0 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62  need to worry ab
21100 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65 20  out freeing the 
21110 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76  result..** Howev
21120 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74  er, the error st
21130 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76  ring might be ov
21140 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61  erwritten or dea
21150 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73  llocated by.** s
21160 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
21170 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  to other SQLite 
21180 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69  interface functi
21190 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 57 68 65  ons.)^.**.** Whe
211a0 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64  n the serialized
211b0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
211c0 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20  ] is in use, it 
211d0 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20  might be the.** 
211e0 63 61 73 65 20 74 68 61 74 20 61 20 73 65 63 6f  case that a seco
211f0 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  nd error occurs 
21200 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 74 68  on a separate th
21210 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a  read in between.
21220 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74  ** the time of t
21230 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 20 61  he first error a
21240 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74  nd the call to t
21250 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e  hese interfaces.
21260 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61  .** When that ha
21270 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e  ppens, the secon
21280 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20  d error will be 
21290 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74  reported since t
212a0 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  hese.** interfac
212b0 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74  es always report
212c0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
212d0 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f   result.  To avo
212e0 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68  id.** this, each
212f0 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61   thread can obta
21300 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73 65  in exclusive use
21310 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
21320 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a  e connection] D.
21330 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b  ** by invoking [
21340 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e  sqlite3_mutex_en
21350 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62  ter]([sqlite3_db
21360 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f  _mutex](D)) befo
21370 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20  re beginning.** 
21380 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76  to use D and inv
21390 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  oking [sqlite3_m
213a0 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c  utex_leave]([sql
213b0 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44  ite3_db_mutex](D
213c0 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20  )) after.** all 
213d0 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74  calls to the int
213e0 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 20 68  erfaces listed h
213f0 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65  ere are complete
21400 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69  d..**.** If an i
21410 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77  nterface fails w
21420 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  ith SQLITE_MISUS
21430 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68  E, that means th
21440 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77  e interface.** w
21450 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72  as invoked incor
21460 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 61 70  rectly by the ap
21470 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74  plication.  In t
21480 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a  hat case, the.**
21490 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20   error code and 
214a0 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d  message may or m
214b0 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a  ay not be set..*
214c0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72  /.int sqlite3_er
214d0 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64  rcode(sqlite3 *d
214e0 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  b);.int sqlite3_
214f0 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
21500 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63  (sqlite3 *db);.c
21510 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
21520 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65  e3_errmsg(sqlite
21530 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  3*);.const void 
21540 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  *sqlite3_errmsg1
21550 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  6(sqlite3*);../*
21560 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51  .** CAPI3REF: SQ
21570 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  L Statement Obje
21580 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ct.** KEYWORDS: 
21590 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  {prepared statem
215a0 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73  ent} {prepared s
215b0 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a  tatements}.**.**
215c0 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
215d0 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72  this object repr
215e0 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20  esents a single 
215f0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  SQL statement..*
21600 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73  * This object is
21610 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e   variously known
21620 20 61 73 20 61 20 22 70 72 65 70 61 72 65 64 20   as a "prepared 
21630 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a  statement" or a.
21640 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c  ** "compiled SQL
21650 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73   statement" or s
21660 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61 74  imply as a "stat
21670 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68  ement"..**.** Th
21680 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74  e life of a stat
21690 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65  ement object goe
216a0 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65  s something like
216b0 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   this:.**.** <ol
216c0 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65  >.** <li> Create
216d0 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e   the object usin
216e0 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
216f0 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65  re_v2()] or a re
21700 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75  lated.**      fu
21710 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20  nction..** <li> 
21720 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b  Bind values to [
21730 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 5d  host parameters]
21740 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
21750 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20  e3_bind_*().**  
21760 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a      interfaces..
21770 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20  ** <li> Run the 
21780 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  SQL by calling [
21790 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
217a0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
217b0 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74  s..** <li> Reset
217c0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75   the statement u
217d0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  sing [sqlite3_re
217e0 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62  set()] then go b
217f0 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73  ack.**      to s
21800 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20  tep 2.  Do this 
21810 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d  zero or more tim
21820 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74  es..** <li> Dest
21830 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75  roy the object u
21840 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
21850 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f  nalize()]..** </
21860 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20  ol>.**.** Refer 
21870 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  to documentation
21880 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d   on individual m
21890 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72  ethods above for
218a0 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
218b0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74  nformation..*/.t
218c0 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
218d0 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74  lite3_stmt sqlit
218e0 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20  e3_stmt;../*.** 
218f0 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69  CAPI3REF: Run-ti
21900 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20  me Limits.**.** 
21910 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  ^(This interface
21920 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65   allows the size
21930 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73   of various cons
21940 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d  tructs to be lim
21950 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e  ited.** on a con
21960 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65  nection by conne
21970 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68  ction basis.  Th
21980 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
21990 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74  r is the.** [dat
219a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
219b0 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73  ] whose limit is
219c0 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75   to be set or qu
219d0 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73  eried.  The.** s
219e0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
219f0 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c  is one of the [l
21a00 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d  imit categories]
21a10 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a   that define a.*
21a20 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74  * class of const
21a30 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65  ructs to be size
21a40 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74   limited.  The t
21a50 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69  hird parameter i
21a60 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d  s the.** new lim
21a70 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73  it for that cons
21a80 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  truct.)^.**.** ^
21a90 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74  If the new limit
21aa0 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e   is a negative n
21ab0 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74  umber, the limit
21ac0 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a   is unchanged..*
21ad0 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d  * ^(For each lim
21ae0 69 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49  it category SQLI
21af0 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45  TE_LIMIT_<i>NAME
21b00 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61 20  </i> there is a 
21b10 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61  .** [limits | ha
21b20 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a  rd upper bound].
21b30 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c  ** set at compil
21b40 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70 72  e-time by a C pr
21b50 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
21b60 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69   called.** [limi
21b70 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f  ts | SQLITE_MAX_
21b80 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a  <i>NAME</i>]..**
21b90 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20   (The "_LIMIT_" 
21ba0 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63  in the name is c
21bb0 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f  hanged to "_MAX_
21bc0 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70  ".))^.** ^Attemp
21bd0 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61  ts to increase a
21be0 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73   limit above its
21bf0 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
21c00 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c  d are.** silentl
21c10 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74  y truncated to t
21c20 68 65 20 68 61 72 64 20 75 70 70 65 72 20 62 6f  he hard upper bo
21c30 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61  und..**.** ^Rega
21c40 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
21c50 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d  r or not the lim
21c60 69 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20  it was changed, 
21c70 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  the .** [sqlite3
21c80 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66  _limit()] interf
21c90 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
21ca0 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74  prior value of t
21cb0 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65  he limit..** ^He
21cc0 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65  nce, to find the
21cd0 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f   current value o
21ce0 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75  f a limit withou
21cf0 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a  t changing it,.*
21d00 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20  * simply invoke 
21d10 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 77  this interface w
21d20 69 74 68 20 74 68 65 20 74 68 69 72 64 20 70 61  ith the third pa
21d30 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d  rameter set to -
21d40 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d  1..**.** Run-tim
21d50 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74  e limits are int
21d60 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
21d70 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   applications th
21d80 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74  at manage.** bot
21d90 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65  h their own inte
21da0 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e  rnal database an
21db0 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73  d also databases
21dc0 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f   that are contro
21dd0 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75  lled.** by untru
21de0 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f  sted external so
21df0 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70  urces.  An examp
21e00 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  le application m
21e10 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62  ight be a.** web
21e20 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61   browser that ha
21e30 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61  s its own databa
21e40 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20  ses for storing 
21e50 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73  history and.** s
21e60 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65  eparate database
21e70 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20  s controlled by 
21e80 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69  JavaScript appli
21e90 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64  cations download
21ea0 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e  ed.** off the In
21eb0 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74  ternet.  The int
21ec0 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20  ernal databases 
21ed0 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65  can be given the
21ee0 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75  .** large, defau
21ef0 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61  lt limits.  Data
21f00 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79  bases managed by
21f10 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65   external source
21f20 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65  s can.** be give
21f30 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c  n much smaller l
21f40 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74  imits designed t
21f50 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69  o prevent a deni
21f60 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a  al of service.**
21f70 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f   attack.  Develo
21f80 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20  pers might also 
21f90 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20  want to use the 
21fa0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
21fb0 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e  horizer()].** in
21fc0 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68  terface to furth
21fd0 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75  er control untru
21fe0 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73  sted SQL.  The s
21ff0 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ize of the datab
22000 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62  ase.** created b
22010 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73  y an untrusted s
22020 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e  cript can be con
22030 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65  tained using the
22040 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f  .** [max_page_co
22050 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a  unt] [PRAGMA]..*
22060 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d  *.** New run-tim
22070 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69  e limit categori
22080 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  es may be added 
22090 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
220a0 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  es..*/.int sqlit
220b0 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33  e3_limit(sqlite3
220c0 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e  *, int id, int n
220d0 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ewVal);../*.** C
220e0 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
220f0 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69  e Limit Categori
22100 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
22110 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d  {limit category}
22120 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72   {*limit categor
22130 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ies}.**.** These
22140 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e   constants defin
22150 65 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72  e various perfor
22160 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20  mance limits.** 
22170 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65  that can be lowe
22180 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20  red at run-time 
22190 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c  using [sqlite3_l
221a0 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  imit()]..** The 
221b0 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20  synopsis of the 
221c0 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20  meanings of the 
221d0 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69  various limits i
221e0 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a  s shown below..*
221f0 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  * Additional inf
22200 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69  ormation is avai
22210 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73  lable at [limits
22220 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c   | Limits in SQL
22230 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  ite]..**.** <dl>
22240 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
22250 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64  IT_LENGTH]] ^(<d
22260 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  t>SQLITE_LIMIT_L
22270 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
22280 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69  d>The maximum si
22290 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67  ze of any string
222a0 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c   or BLOB or tabl
222b0 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e  e row, in bytes.
222c0 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  <dd>)^.**.** [[S
222d0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
222e0 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  LENGTH]] ^(<dt>S
222f0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
22300 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
22310 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c  dd>The maximum l
22320 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20  ength of an SQL 
22330 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79  statement, in by
22340 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  tes.</dd>)^.**.*
22350 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
22360 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e  _COLUMN]] ^(<dt>
22370 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
22380 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  UMN</dt>.** <dd>
22390 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
223a0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
223b0 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74   a table definit
223c0 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a  ion or in the.**
223d0 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61   result set of a
223e0 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65   [SELECT] or the
223f0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
22400 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e  of columns in an
22410 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20   index.** or in 
22420 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47  an ORDER BY or G
22430 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c  ROUP BY clause.<
22440 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
22450 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
22460 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  _DEPTH]] ^(<dt>S
22470 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
22480 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  _DEPTH</dt>.** <
22490 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64  dd>The maximum d
224a0 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73  epth of the pars
224b0 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78  e tree on any ex
224c0 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e  pression.</dd>)^
224d0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
224e0 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53  LIMIT_COMPOUND_S
224f0 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51  ELECT]] ^(<dt>SQ
22500 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
22510 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a  UND_SELECT</dt>.
22520 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
22530 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72  um number of ter
22540 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64  ms in a compound
22550 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
22560 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  t.</dd>)^.**.** 
22570 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  [[SQLITE_LIMIT_V
22580 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53  DBE_OP]] ^(<dt>S
22590 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
225a0 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  _OP</dt>.** <dd>
225b0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
225c0 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f  er of instructio
225d0 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20  ns in a virtual 
225e0 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a  machine program.
225f0 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  ** used to imple
22600 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74  ment an SQL stat
22610 65 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d  ement.  This lim
22620 69 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e  it is not curren
22630 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c  tly.** enforced,
22640 20 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67   though that mig
22650 68 74 20 62 65 20 61 64 64 65 64 20 69 6e 20 73  ht be added in s
22660 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61  ome future relea
22670 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e  se of.** SQLite.
22680 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
22690 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
226a0 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64  CTION_ARG]] ^(<d
226b0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  t>SQLITE_LIMIT_F
226c0 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e  UNCTION_ARG</dt>
226d0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
226e0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  mum number of ar
226f0 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e  guments on a fun
22700 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ction.</dd>)^.**
22710 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
22720 49 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28  IT_ATTACHED]] ^(
22730 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
22740 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a  _ATTACHED</dt>.*
22750 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
22760 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54  m number of [ATT
22770 41 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64  ACH | attached d
22780 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64  atabases].)^</dd
22790 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
227a0 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
227b0 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20  ERN_LENGTH]].** 
227c0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
227d0 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
227e0 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
227f0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c  dd>The maximum l
22800 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74  ength of the pat
22810 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f  tern argument to
22820 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a   the [LIKE] or.*
22830 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f  * [GLOB] operato
22840 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  rs.</dd>)^.**.**
22850 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
22860 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d  VARIABLE_NUMBER]
22870 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  ].** ^(<dt>SQLIT
22880 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
22890 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20  _NUMBER</dt>.** 
228a0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
228b0 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20  index number of 
228c0 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  any [parameter] 
228d0 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  in an SQL statem
228e0 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ent.)^.**.** [[S
228f0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
22900 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64  GER_DEPTH]] ^(<d
22910 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54  t>SQLITE_LIMIT_T
22920 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74  RIGGER_DEPTH</dt
22930 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
22940 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65  imum depth of re
22950 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67  cursion for trig
22960 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20  gers.</dd>)^.** 
22970 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
22980 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45   SQLITE_LIMIT_LE
22990 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
229a0 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e          0.#defin
229b0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  e SQLITE_LIMIT_S
229c0 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  QL_LENGTH       
229d0 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
229e0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
229f0 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20  COLUMN          
22a00 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66            2.#def
22a10 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
22a20 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20  _EXPR_DEPTH     
22a30 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65             3.#de
22a40 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
22a50 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
22a60 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64  T           4.#d
22a70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
22a80 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20  IT_VDBE_OP      
22a90 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23               5.#
22aa0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
22ab0 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
22ac0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a                6.
22ad0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
22ae0 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20  IMIT_ATTACHED   
22af0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37                 7
22b00 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22b10 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
22b20 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  RN_LENGTH       
22b30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
22b40 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
22b50 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20  NUMBER          
22b60 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   9.#define SQLIT
22b70 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f  E_LIMIT_TRIGGER_
22b80 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20  DEPTH           
22b90 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   10../*.** CAPI3
22ba0 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41  REF: Compiling A
22bb0 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a  n SQL Statement.
22bc0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51  ** KEYWORDS: {SQ
22bd0 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70  L statement comp
22be0 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65  iler}.**.** To e
22bf0 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75  xecute an SQL qu
22c00 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72  ery, it must fir
22c10 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69  st be compiled i
22c20 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a  nto a byte-code.
22c30 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67  ** program using
22c40 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f   one of these ro
22c50 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  utines..**.** Th
22c60 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
22c70 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61  , "db", is a [da
22c80 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
22c90 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  n] obtained from
22ca0 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63   a.** prior succ
22cb0 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
22cc0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
22cd0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
22ce0 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  2()] or.** [sqli
22cf0 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20  te3_open16()].  
22d00 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  The database con
22d10 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  nection must not
22d20 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65   have been close
22d30 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  d..**.** The sec
22d40 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a  ond argument, "z
22d50 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61  Sql", is the sta
22d60 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d  tement to be com
22d70 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a  piled, encoded.*
22d80 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d  * as either UTF-
22d90 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68  8 or UTF-16.  Th
22da0 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
22db0 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
22dc0 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20  prepare_v2().** 
22dd0 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 20 55  interfaces use U
22de0 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65  TF-8, and sqlite
22df0 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 61 6e  3_prepare16() an
22e00 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
22e10 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20  e16_v2().** use 
22e20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49  UTF-16..**.** ^I
22e30 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75  f the nByte argu
22e40 6d 65 6e 74 20 69 73 20 6c 65 73 73 20 74 68 61  ment is less tha
22e50 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71  n zero, then zSq
22e60 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20  l is read up to 
22e70 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72  the.** first zer
22e80 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49  o terminator. ^I
22e90 66 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e  f nByte is non-n
22ea0 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74  egative, then it
22eb0 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a   is the maximum.
22ec0 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20 62 79  ** number of  by
22ed0 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53  tes read from zS
22ee0 71 6c 2e 20 20 5e 57 68 65 6e 20 6e 42 79 74 65  ql.  ^When nByte
22ef0 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
22f00 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74  , the.** zSql st
22f10 72 69 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74  ring ends at eit
22f20 68 65 72 20 74 68 65 20 66 69 72 73 74 20 27 5c  her the first '\
22f30 30 30 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27  000' or '\u0000'
22f40 20 63 68 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a   character or.**
22f50 20 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79   the nByte-th by
22f60 74 65 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f  te, whichever co
22f70 6d 65 73 20 66 69 72 73 74 2e 20 49 66 20 74 68  mes first. If th
22f80 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a  e caller knows.*
22f90 2a 20 74 68 61 74 20 74 68 65 20 73 75 70 70 6c  * that the suppl
22fa0 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75  ied string is nu
22fb0 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68  l-terminated, th
22fc0 65 6e 20 74 68 65 72 65 20 69 73 20 61 20 73 6d  en there is a sm
22fd0 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e  all.** performan
22fe0 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20  ce advantage to 
22ff0 62 65 20 67 61 69 6e 65 64 20 62 79 20 70 61 73  be gained by pas
23000 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61  sing an nByte pa
23010 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20  rameter that.** 
23020 69 73 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20  is equal to the 
23030 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
23040 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  in the input str
23050 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67  ing <i>including
23060 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d  </i>.** the nul-
23070 74 65 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73  terminator bytes
23080 20 61 73 20 74 68 69 73 20 73 61 76 65 73 20 53   as this saves S
23090 51 4c 69 74 65 20 66 72 6f 6d 20 68 61 76 69 6e  QLite from havin
230a0 67 20 74 6f 0a 2a 2a 20 6d 61 6b 65 20 61 20 63  g to.** make a c
230b0 6f 70 79 20 6f 66 20 74 68 65 20 69 6e 70 75 74  opy of the input
230c0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e   string..**.** ^
230d0 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74  If pzTail is not
230e0 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61   NULL then *pzTa
230f0 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f  il is made to po
23100 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74  int to the first
23110 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68   byte.** past th
23120 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72  e end of the fir
23130 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  st SQL statement
23140 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65   in zSql.  These
23150 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a   routines only.*
23160 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69  * compile the fi
23170 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  rst statement in
23180 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69   zSql, so *pzTai
23190 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69  l is left pointi
231a0 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65  ng to.** what re
231b0 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64  mains uncompiled
231c0 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74  ..**.** ^*ppStmt
231d0 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
231e0 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20  g to a compiled 
231f0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
23200 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65  ent] that can be
23210 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69  .** executed usi
23220 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
23230 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20  ()].  ^If there 
23240 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70  is an error, *pp
23250 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74  Stmt is set.** t
23260 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65  o NULL.  ^If the
23270 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74   input text cont
23280 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20  ains no SQL (if 
23290 74 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20  the input is an 
232a0 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20  empty.** string 
232b0 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68  or a comment) th
232c0 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65  en *ppStmt is se
232d0 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68  t to NULL..** Th
232e0 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64  e calling proced
232f0 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ure is responsib
23300 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20  le for deleting 
23310 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  the compiled.** 
23320 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73  SQL statement us
23330 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
23340 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69  alize()] after i
23350 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  t has finished w
23360 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d  ith it..** ppStm
23370 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c  t may not be NUL
23380 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63  L..**.** ^On suc
23390 63 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65  cess, the sqlite
233a0 33 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d 69  3_prepare() fami
233b0 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72  ly of routines r
233c0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
233d0 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20  ];.** otherwise 
233e0 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
233f0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
23400 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70  ** The sqlite3_p
23410 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20  repare_v2() and 
23420 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
23430 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  6_v2() interface
23440 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65  s are.** recomme
23450 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77  nded for all new
23460 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74   programs. The t
23470 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61  wo older interfa
23480 63 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64  ces are retained
23490 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64  .** for backward
234a0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c  s compatibility,
234b0 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69   but their use i
234c0 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a  s discouraged..*
234d0 2a 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69  * ^In the "v2" i
234e0 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70  nterfaces, the p
234f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
23500 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74  t.** that is ret
23510 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69  urned (the [sqli
23520 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74  te3_stmt] object
23530 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70  ) contains a cop
23540 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67  y of the.** orig
23550 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54  inal SQL text. T
23560 68 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b  his causes the [
23570 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
23580 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20  interface to.** 
23590 62 65 68 61 76 65 20 64 69 66 66 65 72 65 6e 74  behave different
235a0 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61 79 73  ly in three ways
235b0 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20  :.**.** <ol>.** 
235c0 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  <li>.** ^If the 
235d0 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20  database schema 
235e0 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64  changes, instead
235f0 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53   of returning [S
23600 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73  QLITE_SCHEMA] as
23610 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73   it.** always us
23620 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74  ed to do, [sqlit
23630 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
23640 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65  automatically re
23650 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a  compile the SQL.
23660 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  ** statement and
23670 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61   try to run it a
23680 67 61 69 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  gain..** </li>.*
23690 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68  *.** <li>.** ^Wh
236a0 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  en an error occu
236b0 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  rs, [sqlite3_ste
236c0 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  p()] will return
236d0 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61   one of the deta
236e0 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  iled.** [error c
236f0 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64  odes] or [extend
23700 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e  ed error codes].
23710 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65    ^The legacy be
23720 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a  havior was that.
23730 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
23740 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72  ()] would only r
23750 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20  eturn a generic 
23760 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72  [SQLITE_ERROR] r
23770 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e  esult code.** an
23780 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
23790 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20  n would have to 
237a0 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61  make a second ca
237b0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ll to [sqlite3_r
237c0 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72  eset()].** in or
237d0 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20  der to find the 
237e0 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65  underlying cause
237f0 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e   of the problem.
23800 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70   With the "v2" p
23810 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66  repare.** interf
23820 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c  aces, the underl
23830 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20  ying reason for 
23840 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 65 74  the error is ret
23850 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  urned immediatel
23860 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a  y..** </li>.**.*
23870 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68  * <li>.** ^If th
23880 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65  e specific value
23890 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d   bound to [param
238a0 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61  eter | host para
238b0 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a  meter] in the .*
238c0 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d  * WHERE clause m
238d0 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74  ight influence t
238e0 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65  he choice of que
238f0 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74  ry plan for a st
23900 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e  atement,.** then
23910 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77   the statement w
23920 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63  ill be automatic
23930 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c  ally recompiled,
23940 20 61 73 20 69 66 20 74 68 65 72 65 20 68 61 64   as if there had
23950 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65   been .** a sche
23960 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68  ma change, on th
23970 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65  e first  [sqlite
23980 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66  3_step()] call f
23990 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61  ollowing any cha
239a0 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73  nge.** to the [s
239b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
239c0 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20   | bindings] of 
239d0 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d  that [parameter]
239e0 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69  . .** ^The speci
239f0 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45  fic value of WHE
23a00 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d  RE-clause [param
23a10 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c  eter] might infl
23a20 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68  uence the .** ch
23a30 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c  oice of query pl
23a40 61 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  an if the parame
23a50 74 65 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d  ter is the left-
23a60 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b  hand side of a [
23a70 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f  LIKE].** or [GLO
23a80 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69  B] operator or i
23a90 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
23aa0 69 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61  is compared to a
23ab0 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e  n indexed column
23ac0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c  .** and the [SQL
23ad0 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33  ITE_ENABLE_STAT3
23ae0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
23af0 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ption is enabled
23b00 2e 0a 2a 2a 20 74 68 65 20 0a 2a 2a 20 3c 2f 6c  ..** the .** </l
23b10 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69  i>.** </ol>.*/.i
23b20 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
23b30 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  re(.  sqlite3 *d
23b40 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
23b50 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
23b60 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
23b70 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
23b80 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
23b90 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f  UTF-8 encoded */
23ba0 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
23bb0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
23bc0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
23bd0 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
23be0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
23bf0 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
23c00 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
23c10 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
23c20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20  char **pzTail   
23c30 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
23c40 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
23c50 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
23c60 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
23c70 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69  epare_v2(.  sqli
23c80 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
23c90 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
23ca0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
23cb0 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
23cc0 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
23cd0 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f  ment, UTF-8 enco
23ce0 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
23cf0 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
23d00 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
23d10 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
23d20 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
23d30 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
23d40 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
23d50 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
23d60 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54  const char **pzT
23d70 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
23d80 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
23d90 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
23da0 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  l */.);.int sqli
23db0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20  te3_prepare16(. 
23dc0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
23dd0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
23de0 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
23df0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71   const void *zSq
23e00 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
23e10 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31  statement, UTF-1
23e20 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  6 encoded */.  i
23e30 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
23e40 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
23e50 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
23e60 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
23e70 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
23e80 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
23e90 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
23ea0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
23eb0 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
23ec0 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
23ed0 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
23ee0 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
23ef0 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
23f00 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  e16_v2(.  sqlite
23f10 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
23f20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
23f30 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
23f40 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20  void *zSql,     
23f50 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
23f60 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  nt, UTF-16 encod
23f70 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
23f80 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
23f90 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
23fa0 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
23fb0 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
23fc0 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
23fd0 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
23fe0 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
23ff0 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
24000 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
24010 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
24020 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
24030 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
24040 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 69  PI3REF: Retrievi
24050 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c  ng Statement SQL
24060 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74  .**.** ^This int
24070 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
24080 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 61  ed to retrieve a
24090 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74   saved copy of t
240a0 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53  he original.** S
240b0 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f 20  QL text used to 
240c0 63 72 65 61 74 65 20 61 20 5b 70 72 65 70 61 72  create a [prepar
240d0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66  ed statement] if
240e0 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20   that statement 
240f0 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20  was.** compiled 
24100 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71  using either [sq
24110 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
24120 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
24130 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
24140 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
24150 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69  sqlite3_sql(sqli
24160 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
24170 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
24180 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
24190 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
241a0 20 57 72 69 74 65 73 20 54 68 65 20 44 61 74 61   Writes The Data
241b0 62 61 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  base.**.** ^The 
241c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
241d0 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66 61  donly(X) interfa
241e0 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  ce returns true 
241f0 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a  (non-zero) if.**
24200 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65   and only if the
24210 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
24220 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f  ment] X makes no
24230 20 64 69 72 65 63 74 20 63 68 61 6e 67 65 73 20   direct changes 
24240 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e  to.** the conten
24250 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  t of the databas
24260 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  e file..**.** No
24270 74 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63 61  te that [applica
24280 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
24290 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a   functions] or.*
242a0 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  * [virtual table
242b0 73 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20  s] might change 
242c0 74 68 65 20 64 61 74 61 62 61 73 65 20 69 6e 64  the database ind
242d0 69 72 65 63 74 6c 79 20 61 73 20 61 20 73 69 64  irectly as a sid
242e0 65 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e  e effect.  .** ^
242f0 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66  (For example, if
24300 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
24310 64 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74 69  defines a functi
24320 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61 74  on "eval()" that
24330 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69   .** calls [sqli
24340 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68 65  te3_exec()], the
24350 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  n the following 
24360 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 6f  SQL statement wo
24370 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68  uld.** change th
24380 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
24390 74 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66 66  through side-eff
243a0 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  ects:.**.** <blo
243b0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
243c0 20 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c 28      SELECT eval(
243d0 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31 27  'DELETE FROM t1'
243e0 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f  ) FROM t2;.** </
243f0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
24400 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61  >.**.** But beca
24410 75 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54 5d  use the [SELECT]
24420 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20   statement does 
24430 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 64  not change the d
24440 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20  atabase file.** 
24450 64 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74 65  directly, sqlite
24460 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
24470 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65  ) would still re
24480 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a  turn true.)^.**.
24490 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20  ** ^Transaction 
244a0 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e  control statemen
244b0 74 73 20 73 75 63 68 20 61 73 20 5b 42 45 47 49  ts such as [BEGI
244c0 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52  N], [COMMIT], [R
244d0 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41  OLLBACK],.** [SA
244e0 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52  VEPOINT], and [R
244f0 45 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73 71  ELEASE] cause sq
24500 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
24510 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20  nly() to return 
24520 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74  true,.** since t
24530 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  he statements th
24540 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20  emselves do not 
24550 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20  actually modify 
24560 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75 74  the database but
24570 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79 20  .** rather they 
24580 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d 69  control the timi
24590 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65 72  ng of when other
245a0 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69   statements modi
245b0 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61 62  fy the .** datab
245c0 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54 41  ase.  ^The [ATTA
245d0 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48 5d  CH] and [DETACH]
245e0 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f   statements also
245f0 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65   cause.** sqlite
24600 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
24610 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65  ) to return true
24620 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74 68   since, while th
24630 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  ose statements.*
24640 2a 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f 6e  * change the con
24650 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61 20  figuration of a 
24660 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
24670 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74  ion, they do not
24680 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65   make .** change
24690 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74  s to the content
246a0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
246b0 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a   files on disk..
246c0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
246d0 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c  tmt_readonly(sql
246e0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
246f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
24700 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
24710 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
24720 65 6d 65 6e 74 20 48 61 73 20 42 65 65 6e 20 52  ement Has Been R
24730 65 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eset.**.** ^The 
24740 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73  sqlite3_stmt_bus
24750 79 28 53 29 20 69 6e 74 65 72 66 61 63 65 20 72  y(S) interface r
24760 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e  eturns true (non
24770 2d 7a 65 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a  -zero) if the.**
24780 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
24790 6d 65 6e 74 5d 20 53 20 68 61 73 20 62 65 65 6e  ment] S has been
247a0 20 73 74 65 70 70 65 64 20 61 74 20 6c 65 61 73   stepped at leas
247b0 74 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a  t once using .**
247c0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
247d0 29 5d 20 62 75 74 20 68 61 73 20 6e 6f 74 20 72  )] but has not r
247e0 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  un to completion
247f0 20 61 6e 64 2f 6f 72 20 68 61 73 20 6e 6f 74 20   and/or has not 
24800 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20 75  .** been reset u
24810 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  sing [sqlite3_re
24820 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20 73  set(S)].  ^The s
24830 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79  qlite3_stmt_busy
24840 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  (S).** interface
24850 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 69   returns false i
24860 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  f S is a NULL po
24870 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73 20  inter.  If S is 
24880 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70  not a .** NULL p
24890 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e 6f  ointer and is no
248a0 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  t a pointer to a
248b0 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65 64   valid [prepared
248c0 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f   statement].** o
248d0 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65 20  bject, then the 
248e0 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
248f0 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
24900 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a  ly undesirable..
24910 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72  **.** This inter
24920 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64  face can be used
24930 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20   in combination 
24940 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74  [sqlite3_next_st
24950 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61  mt()].** to loca
24960 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64 20  te all prepared 
24970 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63  statements assoc
24980 69 61 74 65 64 20 77 69 74 68 20 61 20 64 61 74  iated with a dat
24990 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63  abase .** connec
249a0 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69 6e  tion that are in
249b0 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20 72   need of being r
249c0 65 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e 20  eset.  This can 
249d0 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20  be used,.** for 
249e0 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67  example, in diag
249f0 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73 20  nostic routines 
24a00 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70 72  to search for pr
24a10 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74 65  epared .** state
24a20 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65 20 68  ments that are h
24a30 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61 63  olding a transac
24a40 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e  tion open..*/.in
24a50 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62  t sqlite3_stmt_b
24a60 75 73 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  usy(sqlite3_stmt
24a70 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
24a80 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79  REF: Dynamically
24a90 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a   Typed Value Obj
24aa0 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ect.** KEYWORDS:
24ab0 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   {protected sqli
24ac0 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72  te3_value} {unpr
24ad0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
24ae0 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c  value}.**.** SQL
24af0 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c  ite uses the sql
24b00 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
24b10 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61  t to represent a
24b20 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61  ll values.** tha
24b30 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20  t can be stored 
24b40 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61  in a database ta
24b50 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73  ble. SQLite uses
24b60 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a   dynamic typing.
24b70 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65  ** for the value
24b80 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56  s it stores.  ^V
24b90 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20  alues stored in 
24ba0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
24bb0 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20  jects.** can be 
24bc0 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69  integers, floati
24bd0 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c  ng point values,
24be0 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c   strings, BLOBs,
24bf0 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   or NULL..**.** 
24c00 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  An sqlite3_value
24c10 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65   object may be e
24c20 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 64  ither "protected
24c30 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65  " or "unprotecte
24c40 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65  d"..** Some inte
24c50 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 61  rfaces require a
24c60 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
24c70 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72  e3_value.  Other
24c80 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77   interfaces.** w
24c90 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 65  ill accept eithe
24ca0 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72  r a protected or
24cb0 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20   an unprotected 
24cc0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a  sqlite3_value..*
24cd0 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 63  * Every interfac
24ce0 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20 73  e that accepts s
24cf0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67  qlite3_value arg
24d00 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 73  uments specifies
24d10 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e  .** whether or n
24d20 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20 61  ot it requires a
24d30 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
24d40 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20  e3_value..**.** 
24d50 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65  The terms "prote
24d60 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f  cted" and "unpro
24d70 74 65 63 74 65 64 22 20 72 65 66 65 72 20 74 6f  tected" refer to
24d80 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a   whether or not.
24d90 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68 65  ** a mutex is he
24da0 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c  ld.  An internal
24db0 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66   mutex is held f
24dc0 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a  or a protected.*
24dd0 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
24de0 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75  object but no mu
24df0 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20  tex is held for 
24e00 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  an unprotected.*
24e10 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
24e20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69  object.  If SQLi
24e30 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74  te is compiled t
24e40 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65  o be single-thre
24e50 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53  aded.** (with [S
24e60 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
24e70 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71  =0] and with [sq
24e80 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
24e90 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29  ()] returning 0)
24ea0 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65  .** or if SQLite
24eb0 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f   is run in one o
24ec0 66 20 72 65 64 75 63 65 64 20 6d 75 74 65 78 20  f reduced mutex 
24ed0 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54  modes .** [SQLIT
24ee0 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
24ef0 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54  HREAD] or [SQLIT
24f00 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
24f10 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  READ].** then th
24f20 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e  ere is no distin
24f30 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72  ction between pr
24f40 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72  otected and unpr
24f50 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
24f60 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
24f70 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65   and they can be
24f80 20 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67   used interchang
24f90 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c  eably.  However,
24fa0 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20  .** for maximum 
24fb0 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79  code portability
24fc0 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   it is recommend
24fd0 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74  ed that applicat
24fe0 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61  ions.** still ma
24ff0 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69  ke the distincti
25000 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65  on between prote
25010 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65  cted and unprote
25020 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
25030 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76  value objects ev
25040 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69  en when not stri
25050 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a  ctly required..*
25060 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
25070 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
25080 74 68 61 74 20 61 72 65 20 70 61 73 73 65 64 20  that are passed 
25090 61 73 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e  as parameters in
250a0 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d  to the.** implem
250b0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70  entation of [app
250c0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
250d0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20   SQL functions] 
250e0 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a  are protected..*
250f0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
25100 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75  alue object retu
25110 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
25120 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
25130 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74  ()] is unprotect
25140 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74  ed..** Unprotect
25150 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
25160 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c   objects may onl
25170 79 20 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a  y be used with.*
25180 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  * [sqlite3_resul
25190 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b  t_value()] and [
251a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
251b0 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73  ue()]..** The [s
251c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
251d0 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  b | sqlite3_valu
251e0 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79  e_type()] family
251f0 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65   of.** interface
25200 73 20 72 65 71 75 69 72 65 20 70 72 6f 74 65 63  s require protec
25210 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
25220 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79  e objects..*/.ty
25230 70 65 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d  pedef struct Mem
25240 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a   sqlite3_value;.
25250 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
25260 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f   SQL Function Co
25270 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a  ntext Object.**.
25280 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69  ** The context i
25290 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66  n which an SQL f
252a0 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73  unction executes
252b0 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e   is stored in an
252c0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  .** sqlite3_cont
252d0 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20  ext object.  ^A 
252e0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71  pointer to an sq
252f0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62  lite3_context ob
25300 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79  ject.** is alway
25310 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  s first paramete
25320 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f  r to [applicatio
25330 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
25340 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65  nctions]..** The
25350 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
25360 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
25370 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
25380 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a   will pass this.
25390 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75  ** pointer throu
253a0 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f  gh into calls to
253b0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
253c0 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72  _int | sqlite3_r
253d0 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71  esult()],.** [sq
253e0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
253f0 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c  context()], [sql
25400 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
25410 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ],.** [sqlite3_c
25420 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
25430 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65  ()], [sqlite3_ge
25440 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a  t_auxdata()],.**
25450 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33   and/or [sqlite3
25460 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e  _set_auxdata()].
25470 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
25480 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ct sqlite3_conte
25490 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt sqlite3_conte
254a0 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  xt;../*.** CAPI3
254b0 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c  REF: Binding Val
254c0 75 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 20  ues To Prepared 
254d0 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45  Statements.** KE
254e0 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61  YWORDS: {host pa
254f0 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70  rameter} {host p
25500 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74  arameters} {host
25510 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d   parameter name}
25520 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53  .** KEYWORDS: {S
25530 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53  QL parameter} {S
25540 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b  QL parameters} {
25550 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e  parameter bindin
25560 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68  g}.**.** ^(In th
25570 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
25580 74 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73  text input to [s
25590 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
255a0 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72  2()] and its var
255b0 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61  iants,.** litera
255c0 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63  ls may be replac
255d0 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74  ed by a [paramet
255e0 65 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73  er] that matches
255f0 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e   one of followin
25600 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a  g.** templates:.
25610 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
25620 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f  i>  ?.** <li>  ?
25630 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56  NNN.** <li>  :VV
25640 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a  V.** <li>  @VVV.
25650 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a  ** <li>  $VVV.**
25660 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20   </ul>.**.** In 
25670 74 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62  the templates ab
25680 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65  ove, NNN represe
25690 6e 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c  nts an integer l
256a0 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56  iteral,.** and V
256b0 56 56 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  VV represents an
256c0 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64   alphanumeric id
256d0 65 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68  entifier.)^  ^Th
256e0 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73  e values of thes
256f0 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20  e.** parameters 
25700 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f  (also called "ho
25710 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d  st parameter nam
25720 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61  es" or "SQL para
25730 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20  meters").** can 
25740 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65  be set using the
25750 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
25760 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e  ) routines defin
25770 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e  ed here..**.** ^
25780 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
25790 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
257a0 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
257b0 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a  nes is always.**
257c0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
257d0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d  e [sqlite3_stmt]
257e0 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
257f0 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65   from.** [sqlite
25800 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
25810 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e  or its variants.
25820 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f  .**.** ^The seco
25830 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
25840 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
25850 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f  SQL parameter to
25860 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65   be set..** ^The
25870 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61   leftmost SQL pa
25880 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69  rameter has an i
25890 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65  ndex of 1.  ^Whe
258a0 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64  n the same named
258b0 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65  .** SQL paramete
258c0 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74  r is used more t
258d0 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64  han once, second
258e0 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a   and subsequent.
258f0 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68  ** occurrences h
25900 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64  ave the same ind
25910 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ex as the first 
25920 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e  occurrence..** ^
25930 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61  The index for na
25940 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63  med parameters c
25950 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20  an be looked up 
25960 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
25970 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
25980 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50  eter_index()] AP
25990 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e  I if desired.  ^
259a0 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72  The index.** for
259b0 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65   "?NNN" paramete
259c0 72 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  rs is the value 
259d0 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20  of NNN..** ^The 
259e0 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62  NNN value must b
259f0 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20  e between 1 and 
25a00 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  the [sqlite3_lim
25a10 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74  it()].** paramet
25a20 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  er [SQLITE_LIMIT
25a30 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
25a40 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65  ] (default value
25a50 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  : 999)..**.** ^T
25a60 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
25a70 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74  t is the value t
25a80 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61  o bind to the pa
25a90 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  rameter..**.** ^
25aa0 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e  (In those routin
25ab0 65 73 20 74 68 61 74 20 68 61 76 65 20 61 20 66  es that have a f
25ac0 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20  ourth argument, 
25ad0 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 68 65  its value is the
25ae0 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  .** number of by
25af0 74 65 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d  tes in the param
25b00 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65  eter.  To be cle
25b10 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73  ar: the value is
25b20 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
25b30 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69  f <u>bytes</u> i
25b40 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74  n the value, not
25b50 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
25b60 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20  haracters.)^.** 
25b70 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70  ^If the fourth p
25b80 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61  arameter is nega
25b90 74 69 76 65 2c 20 74 68 65 20 6c 65 6e 67 74 68  tive, the length
25ba0 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 69   of the string i
25bb0 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  s.** the number 
25bc0 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f 20 74  of bytes up to t
25bd0 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65  he first zero te
25be0 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20  rminator..** If 
25bf0 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66  a non-negative f
25c00 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
25c10 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73  is provided to s
25c20 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
25c30 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
25c40 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 74  _bind_text16() t
25c50 68 65 6e 20 74 68 61 74 20 70 61 72 61 6d 65 74  hen that paramet
25c60 65 72 20 6d 75 73 74 20 62 65 20 74 68 65 20 62  er must be the b
25c70 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68  yte offset.** wh
25c80 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d  ere the NUL term
25c90 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63  inator would occ
25ca0 75 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65 20  ur assuming the 
25cb0 73 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a  string were NUL.
25cc0 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ** terminated.  
25cd0 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61  If any NUL chara
25ce0 63 74 65 72 73 20 6f 63 63 75 72 20 61 74 20 62  cters occur at b
25cf0 79 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73 73  yte offsets less
25d00 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61   than .** the va
25d10 6c 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72 74  lue of the fourt
25d20 68 20 70 61 72 61 6d 65 74 65 72 20 74 68 65 6e  h parameter then
25d30 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73   the resulting s
25d40 74 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c  tring value will
25d50 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65  .** contain embe
25d60 64 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65 20  dded NULs.  The 
25d70 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73  result of expres
25d80 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20  sions involving 
25d90 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20  strings.** with 
25da0 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73  embedded NULs is
25db0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
25dc0 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67  * ^The fifth arg
25dd0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
25de0 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71  _bind_blob(), sq
25df0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
25e00 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65  ), and.** sqlite
25e10 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20  3_bind_text16() 
25e20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  is a destructor 
25e30 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20  used to dispose 
25e40 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a  of the BLOB or.*
25e50 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 53  * string after S
25e60 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68  QLite has finish
25e70 65 64 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68  ed with it.  ^Th
25e80 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  e destructor is 
25e90 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73  called.** to dis
25ea0 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42  pose of the BLOB
25eb0 20 6f 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20   or string even 
25ec0 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 73  if the call to s
25ed0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
25ee0 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62  (),.** sqlite3_b
25ef0 69 6e 64 5f 74 65 78 74 28 29 2c 20 6f 72 20 73  ind_text(), or s
25f00 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
25f10 31 36 28 29 20 66 61 69 6c 73 2e 20 20 0a 2a 2a  16() fails.  .**
25f20 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61   ^If the fifth a
25f30 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68  rgument is.** th
25f40 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20  e special value 
25f50 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c  [SQLITE_STATIC],
25f60 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73   then SQLite ass
25f70 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  umes that the.**
25f80 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
25f90 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e  in static, unman
25fa0 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64  aged space and d
25fb0 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
25fc0 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66  be freed..** ^If
25fd0 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
25fe0 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75  ent has the valu
25ff0 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  e [SQLITE_TRANSI
26000 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51  ENT], then.** SQ
26010 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f  Lite makes its o
26020 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
26030 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65  of the data imme
26040 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a  diately, before.
26050 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ** the sqlite3_b
26060 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20  ind_*() routine 
26070 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  returns..**.** ^
26080 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
26090 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74  _zeroblob() rout
260a0 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42  ine binds a BLOB
260b0 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61   of length N tha
260c0 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77  t.** is filled w
260d0 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20  ith zeroes.  ^A 
260e0 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20  zeroblob uses a 
260f0 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20  fixed amount of 
26100 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20  memory.** (just 
26110 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f  an integer to ho
26120 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77 68 69  ld its size) whi
26130 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70  le it is being p
26140 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72  rocessed..** Zer
26150 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e  oblobs are inten
26160 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20  ded to serve as 
26170 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72  placeholders for
26180 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20   BLOBs whose.** 
26190 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72  content is later
261a0 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a   written using.*
261b0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  * [sqlite3_blob_
261c0 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74  open | increment
261d0 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75  al BLOB I/O] rou
261e0 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67  tines..** ^A neg
261f0 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20  ative value for 
26200 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73  the zeroblob res
26210 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c  ults in a zero-l
26220 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a  ength BLOB..**.*
26230 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 65  * ^If any of the
26240 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
26250 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  ) routines are c
26260 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c  alled with a NUL
26270 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72  L pointer.** for
26280 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
26290 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74  tatement] or wit
262a0 68 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  h a prepared sta
262b0 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 68  tement for which
262c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
262d0 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61  p()] has been ca
262e0 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e 74  lled more recent
262f0 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33  ly than [sqlite3
26300 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68  _reset()],.** th
26310 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c  en the call will
26320 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
26330 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e 79  MISUSE].  If any
26340 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29   sqlite3_bind_()
26350 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 70  .** routine is p
26360 61 73 73 65 64 20 61 20 5b 70 72 65 70 61 72 65  assed a [prepare
26370 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
26380 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c  t has been final
26390 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73  ized, the.** res
263a0 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ult is undefined
263b0 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 61   and probably ha
263c0 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69  rmful..**.** ^Bi
263d0 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63  ndings are not c
263e0 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 5b 73  leared by the [s
263f0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
26400 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62  routine..** ^Unb
26410 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20  ound parameters 
26420 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20  are interpreted 
26430 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  as NULL..**.** ^
26440 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
26450 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  _* routines retu
26460 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  rn [SQLITE_OK] o
26470 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e 0a  n success or an.
26480 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ** [error code] 
26490 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73  if anything goes
264a0 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c   wrong..** ^[SQL
264b0 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65  ITE_RANGE] is re
264c0 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61  turned if the pa
264d0 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78  rameter.** index
264e0 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
264f0 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  .  ^[SQLITE_NOME
26500 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  M] is returned i
26510 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73  f malloc() fails
26520 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
26530 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
26540 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
26550 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
26560 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
26570 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  ame()], and [sql
26580 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
26590 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
265a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
265b0 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  d_blob(sqlite3_s
265c0 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
265d0 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76   void*, int n, v
265e0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
265f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
26600 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
26610 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62  stmt*, int, doub
26620 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  le);.int sqlite3
26630 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65  _bind_int(sqlite
26640 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e  3_stmt*, int, in
26650 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  t);.int sqlite3_
26660 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74  bind_int64(sqlit
26670 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73  e3_stmt*, int, s
26680 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69  qlite3_int64);.i
26690 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
266a0 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  null(sqlite3_stm
266b0 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71  t*, int);.int sq
266c0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
266d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
266e0 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  nt, const char*,
266f0 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28   int n, void(*)(
26700 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
26710 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
26720 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
26730 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
26740 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
26750 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
26760 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73  te3_bind_value(s
26770 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
26780 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33  t, const sqlite3
26790 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
267a0 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
267b0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
267c0 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a  *, int, int n);.
267d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
267e0 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50   Number Of SQL P
267f0 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20  arameters.**.** 
26800 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61  ^This routine ca
26810 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e  n be used to fin
26820 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  d the number of 
26830 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d  [SQL parameters]
26840 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72  .** in a [prepar
26850 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20  ed statement].  
26860 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61  SQL parameters a
26870 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65  re tokens of the
26880 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f  .** form "?", "?
26890 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24  NNN", ":AAA", "$
268a0 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20  AAA", or "@AAA" 
268b0 74 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a  that serve as.**
268c0 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f   placeholders fo
268d0 72 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72  r values that ar
268e0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
268f0 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a  blob | bound].**
26900 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65   to the paramete
26910 72 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69  rs at a later ti
26920 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73  me..**.** ^(This
26930 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c   routine actuall
26940 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e  y returns the in
26950 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65  dex of the large
26960 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a  st (rightmost).*
26970 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72  * parameter. For
26980 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70   all forms excep
26990 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c  t ?NNN, this wil
269a0 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20  l correspond to 
269b0 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
269c0 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65   unique paramete
269d0 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65  rs.  If paramete
269e0 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66  rs of the ?NNN f
269f0 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a  orm are used,.**
26a00 20 74 68 65 72 65 20 6d 61 79 20 62 65 20 67 61   there may be ga
26a10 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29  ps in the list.)
26a20 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ^.**.** See also
26a30 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
26a40 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
26a50 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
26a60 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
26a70 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a  _name()], and.**
26a80 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
26a90 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
26aa0 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
26ab0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
26ac0 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
26ad0 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
26ae0 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20  PI3REF: Name Of 
26af0 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72  A Host Parameter
26b00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
26b10 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
26b20 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74  er_name(P,N) int
26b30 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a  erface returns.*
26b40 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  * the name of th
26b50 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 61  e N-th [SQL para
26b60 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b 70  meter] in the [p
26b70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
26b80 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70  t] P..** ^(SQL p
26b90 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
26ba0 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20   form "?NNN" or 
26bb0 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22  ":AAA" or "@AAA"
26bc0 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61   or "$AAA".** ha
26bd0 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20  ve a name which 
26be0 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f  is the string "?
26bf0 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f  NNN" or ":AAA" o
26c00 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41  r "@AAA" or "$AA
26c10 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65  A".** respective
26c20 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20  ly..** In other 
26c30 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69  words, the initi
26c40 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72  al ":" or "$" or
26c50 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69   "@" or "?".** i
26c60 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61  s included as pa
26c70 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29  rt of the name.)
26c80 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 73  ^.** ^Parameters
26c90 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22   of the form "?"
26ca0 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f   without a follo
26cb0 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76  wing integer hav
26cc0 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64  e no name.** and
26cd0 20 61 72 65 20 72 65 66 65 72 72 65 64 20 74 6f   are referred to
26ce0 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f   as "nameless" o
26cf0 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72  r "anonymous par
26d00 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20  ameters"..**.** 
26d10 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73 74 20  ^The first host 
26d20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e  parameter has an
26d30 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74   index of 1, not
26d40 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68   0..**.** ^If th
26d50 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75 74  e value N is out
26d60 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20   of range or if 
26d70 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65 74  the N-th paramet
26d80 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73  er is.** nameles
26d90 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20  s, then NULL is 
26da0 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65 20  returned.  ^The 
26db0 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
26dc0 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20  is.** always in 
26dd0 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65  UTF-8 encoding e
26de0 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64  ven if the named
26df0 20 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a   parameter was.*
26e00 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65  * originally spe
26e10 63 69 66 69 65 64 20 61 73 20 55 54 46 2d 31 36  cified as UTF-16
26e20 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   in [sqlite3_pre
26e30 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20  pare16()] or.** 
26e40 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
26e50 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  16_v2()]..**.** 
26e60 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
26e70 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
26e80 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
26e90 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
26ea0 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
26eb0 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
26ec0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
26ed0 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63  r_index()]..*/.c
26ee0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
26ef0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
26f00 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  r_name(sqlite3_s
26f10 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a  tmt*, int);../*.
26f20 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64  ** CAPI3REF: Ind
26f30 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65  ex Of A Paramete
26f40 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e  r With A Given N
26f50 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72  ame.**.** ^Retur
26f60 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61  n the index of a
26f70 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  n SQL parameter 
26f80 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20  given its name. 
26f90 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76   ^The.** index v
26fa0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73  alue returned is
26fb0 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73   suitable for us
26fc0 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a  e as the second.
26fd0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ** parameter to 
26fe0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
26ff0 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
27000 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20  )].  ^A zero.** 
27010 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e  is returned if n
27020 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d  o matching param
27030 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20  eter is found.  
27040 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a  ^The parameter.*
27050 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67  * name must be g
27060 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76  iven in UTF-8 ev
27070 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e  en if the origin
27080 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  al statement.** 
27090 77 61 73 20 70 72 65 70 61 72 65 64 20 66 72 6f  was prepared fro
270a0 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20 75 73  m UTF-16 text us
270b0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
270c0 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a  pare16_v2()]..**
270d0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
270e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
270f0 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
27100 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
27110 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
27120 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  nt()], and.** [s
27130 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
27140 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
27150 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
27160 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
27170 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  dex(sqlite3_stmt
27180 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
27190 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Name);../*.** CA
271a0 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c  PI3REF: Reset Al
271b0 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20  l Bindings On A 
271c0 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
271d0 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61  nt.**.** ^Contra
271e0 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74  ry to the intuit
271f0 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71  ion of many, [sq
27200 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64  lite3_reset()] d
27210 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a  oes not reset.**
27220 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
27230 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e  nd_blob | bindin
27240 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  gs] on a [prepar
27250 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
27260 2a 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74  * ^Use this rout
27270 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c  ine to reset all
27280 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73   host parameters
27290 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74   to NULL..*/.int
272a0 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62   sqlite3_clear_b
272b0 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f  indings(sqlite3_
272c0 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
272d0 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
272e0 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20  Of Columns In A 
272f0 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a  Result Set.**.**
27300 20 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d   ^Return the num
27310 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
27320 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
27330 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
27340 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
27350 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20  atement]. ^This 
27360 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
27370 30 20 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e  0 if pStmt is an
27380 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   SQL.** statemen
27390 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  t that does not 
273a0 72 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72  return data (for
273b0 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44   example an [UPD
273c0 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  ATE])..**.** See
273d0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
273e0 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f  data_count()].*/
273f0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
27400 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  umn_count(sqlite
27410 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
27420 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
27430 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e   Column Names In
27440 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a   A Result Set.**
27450 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
27460 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e  nes return the n
27470 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20  ame assigned to 
27480 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c  a particular col
27490 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65  umn.** in the re
274a0 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53  sult set of a [S
274b0 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
274c0 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
274d0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a  column_name().**
274e0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
274f0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
27500 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
27510 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a  d UTF-8 string.*
27520 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  * and sqlite3_co
27530 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65  lumn_name16() re
27540 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
27550 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
27560 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73  ated.** UTF-16 s
27570 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72  tring.  ^The fir
27580 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
27590 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
275a0 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74  atement].** that
275b0 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
275c0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
275d0 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  nt. ^The second 
275e0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
275f0 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65  .** column numbe
27600 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  r.  ^The leftmos
27610 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62  t column is numb
27620 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  er 0..**.** ^The
27630 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
27640 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69   pointer is vali
27650 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74  d until either t
27660 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
27670 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65  tement].** is de
27680 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69  stroyed by [sqli
27690 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
276a0 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61  or until the sta
276b0 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61  tement is automa
276c0 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65  tically.** repre
276d0 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72  pared by the fir
276e0 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  st call to [sqli
276f0 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20  te3_step()] for 
27700 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e  a particular run
27710 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  .** or until the
27720 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a   next call to.**
27730 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
27740 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65  name() or sqlite
27750 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
27760 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f  ) on the same co
27770 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  lumn..**.** ^If 
27780 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
27790 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68   fails during th
277a0 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20  e processing of 
277b0 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a  either routine.*
277c0 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64  * (for example d
277d0 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69  uring a conversi
277e0 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f  on from UTF-8 to
277f0 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a   UTF-16) then a.
27800 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
27810 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
27820 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
27830 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  a result column 
27840 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
27850 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20  the "AS" clause 
27860 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75  for.** that colu
27870 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20  mn, if there is 
27880 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49  an AS clause.  I
27890 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53  f there is no AS
278a0 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20   clause.** then 
278b0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
278c0 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63  column is unspec
278d0 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68  ified and may ch
278e0 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65  ange from.** one
278f0 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
27900 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a  te to the next..
27910 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
27920 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
27930 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
27940 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20  , int N);.const 
27950 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
27960 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69  lumn_name16(sqli
27970 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e  te3_stmt*, int N
27980 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
27990 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61  EF: Source Of Da
279a0 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 65  ta In A Query Re
279b0 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  sult.**.** ^Thes
279c0 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69  e routines provi
279d0 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65  de a means to de
279e0 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61  termine the data
279f0 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64  base, table, and
27a00 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  .** table column
27a10 20 74 68 61 74 20 69 73 20 74 68 65 20 6f 72 69   that is the ori
27a20 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75  gin of a particu
27a30 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  lar result colum
27a40 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d  n in.** [SELECT]
27a50 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e   statement..** ^
27a60 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
27a70 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c  database or tabl
27a80 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20  e or column can 
27a90 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a  be returned as.*
27aa0 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d 38  * either a UTF-8
27ab0 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e   or UTF-16 strin
27ac0 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61  g.  ^The _databa
27ad0 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  se_ routines ret
27ae0 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  urn.** the datab
27af0 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74  ase name, the _t
27b00 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72  able_ routines r
27b10 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20  eturn the table 
27b20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65  name, and.** the
27b30 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65   origin_ routine
27b40 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c  s return the col
27b50 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68  umn name..** ^Th
27b60 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
27b70 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  g is valid until
27b80 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
27b90 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73  tatement] is des
27ba0 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20  troyed.** using 
27bb0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
27bc0 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68  e()] or until th
27bd0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
27be0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20  utomatically.** 
27bf0 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68  reprepared by th
27c00 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20  e first call to 
27c10 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
27c20 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
27c30 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69  r run.** or unti
27c40 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72  l the same infor
27c50 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73  mation is reques
27c60 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20  ted.** again in 
27c70 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f  a different enco
27c80 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ding..**.** ^The
27c90 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20   names returned 
27ca0 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  are the original
27cb0 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65   un-aliased name
27cc0 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61  s of the.** data
27cd0 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64  base, table, and
27ce0 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e   column..**.** ^
27cf0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
27d00 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65  nt to these inte
27d10 72 66 61 63 65 73 20 69 73 20 61 20 5b 70 72 65  rfaces is a [pre
27d20 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
27d30 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63  ..** ^These func
27d40 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66  tions return inf
27d50 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74  ormation about t
27d60 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f  he Nth result co
27d70 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79  lumn returned by
27d80 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e  .** the statemen
27d90 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  t, where N is th
27da0 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f  e second functio
27db0 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  n argument..** ^
27dc0 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f  The left-most co
27dd0 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30  lumn is column 0
27de0 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69   for these routi
27df0 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  nes..**.** ^If t
27e00 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65  he Nth column re
27e10 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 74  turned by the st
27e20 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78  atement is an ex
27e30 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73  pression or.** s
27e40 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e  ubquery and is n
27e50 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75  ot a column valu
27e60 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74  e, then all of t
27e70 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  hese functions r
27e80 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20  eturn.** NULL.  
27e90 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d  ^These routine m
27ea0 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e  ight also return
27eb0 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72   NULL if a memor
27ec0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
27ed0 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e  or.** occurs.  ^
27ee0 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20  Otherwise, they 
27ef0 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20  return the name 
27f00 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64 20  of the attached 
27f10 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
27f20 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68  .** or column th
27f30 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 20  at query result 
27f40 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61  column was extra
27f50 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a  cted from..**.**
27f60 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74   ^As with all ot
27f70 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c  her SQLite APIs,
27f80 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d   those whose nam
27f90 65 73 20 65 6e 64 20 77 69 74 68 20 22 31 36 22  es end with "16"
27fa0 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31   return.** UTF-1
27fb0 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67  6 encoded string
27fc0 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20  s and the other 
27fd0 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
27fe0 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54   UTF-8..**.** ^T
27ff0 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e  hese APIs are on
28000 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
28010 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20  the library was 
28020 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
28030 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41  e.** [SQLITE_ENA
28040 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44  BLE_COLUMN_METAD
28050 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73  ATA] C-preproces
28060 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a  sor symbol..**.*
28070 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65  * If two or more
28080 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e   threads call on
28090 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65  e or more of the
280a0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69  se routines agai
280b0 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  nst the same.** 
280c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
280d0 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74  nt and column at
280e0 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74   the same time t
280f0 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
28100 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64  are.** undefined
28110 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f  ..**.** If two o
28120 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63  r more threads c
28130 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  all one or more.
28140 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
28150 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
28160 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61   | column metada
28170 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a  ta interfaces].*
28180 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b  * for the same [
28190 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
281a0 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63  nt] and result c
281b0 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20  olumn.** at the 
281c0 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74  same time then t
281d0 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
281e0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e  ndefined..*/.con
281f0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
28200 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
28210 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
28220 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
28230 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
28240 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
28250 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
28260 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63  t*,int);.const c
28270 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
28280 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73  umn_table_name(s
28290 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
282a0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
282b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
282c0 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ble_name16(sqlit
282d0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
282e0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
282f0 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e  e3_column_origin
28300 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
28310 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
28320 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
28330 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
28340 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
28350 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ,int);../*.** CA
28360 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64  PI3REF: Declared
28370 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51   Datatype Of A Q
28380 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a  uery Result.**.*
28390 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20 70 61  * ^(The first pa
283a0 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72  rameter is a [pr
283b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
283c0 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74  ]..** If this st
283d0 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45  atement is a [SE
283e0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20  LECT] statement 
283f0 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  and the Nth colu
28400 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74  mn of the.** ret
28410 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74  urned result set
28420 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54   of that [SELECT
28430 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c  ] is a table col
28440 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65  umn (not an.** e
28450 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
28460 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20  query) then the 
28470 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66  declared type of
28480 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f   the table.** co
28490 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64  lumn is returned
284a0 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68  .)^  ^If the Nth
284b0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
284c0 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a  esult set is an.
284d0 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  ** expression or
284e0 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20   subquery, then 
284f0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
28500 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e  s returned..** ^
28510 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
28520 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55 54  ing is always UT
28530 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a  F-8 encoded..**.
28540 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65  ** ^(For example
28550 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 61  , given the data
28560 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a  base schema:.**.
28570 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20  ** CREATE TABLE 
28580 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a  t1(c1 VARIANT);.
28590 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f  **.** and the fo
285a0 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e  llowing statemen
285b0 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64  t to be compiled
285c0 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63  :.**.** SELECT c
285d0 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74  1 + 1, c1 FROM t
285e0 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f  1;.**.** this ro
285f0 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75  utine would retu
28600 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56  rn the string "V
28610 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20  ARIANT" for the 
28620 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a  second result.**
28630 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20   column (i==1), 
28640 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  and a NULL point
28650 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  er for the first
28660 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28   result column (
28670 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  i==0).)^.**.** ^
28680 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61  SQLite uses dyna
28690 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70  mic run-time typ
286a0 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62  ing.  ^So just b
286b0 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a  ecause a column.
286c0 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20 74  ** is declared t
286d0 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74  o contain a part
286e0 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73  icular type does
286f0 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74   not mean that t
28700 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65  he.** data store
28710 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e  d in that column
28720 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61   is of the decla
28730 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74  red type.  SQLit
28740 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79  e is.** strongly
28750 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 65 20   typed, but the 
28760 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69  typing is dynami
28770 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e  c not static.  ^
28780 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63  Type.** is assoc
28790 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69 76  iated with indiv
287a0 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f  idual values, no
287b0 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61  t with the conta
287c0 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f  iners.** used to
287d0 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75   hold those valu
287e0 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  es..*/.const cha
287f0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
28800 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74  n_decltype(sqlit
28810 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
28820 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
28830 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
28840 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  pe16(sqlite3_stm
28850 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t*,int);../*.** 
28860 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61  CAPI3REF: Evalua
28870 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  te An SQL Statem
28880 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20  ent.**.** After 
28890 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
288a0 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20  ement] has been 
288b0 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 65  prepared using e
288c0 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ither.** [sqlite
288d0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
288e0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
288f0 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f  are16_v2()] or o
28900 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79  ne of the legacy
28910 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b  .** interfaces [
28920 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
28930 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
28940 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69  repare16()], thi
28950 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75  s function.** mu
28960 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65  st be called one
28970 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74   or more times t
28980 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 73  o evaluate the s
28990 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  tatement..**.** 
289a0 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74  The details of t
289b0 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74  he behavior of t
289c0 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  he sqlite3_step(
289d0 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 65  ) interface depe
289e0 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72  nd.** on whether
289f0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77   the statement w
28a00 61 73 20 70 72 65 70 61 72 65 64 20 75 73 69 6e  as prepared usin
28a10 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 32 22  g the newer "v2"
28a20 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73   interface.** [s
28a30 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
28a40 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
28a50 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
28a60 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c  ] or the older l
28a70 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
28a80 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ce [sqlite3_prep
28a90 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  are()] and [sqli
28aa0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
28ab0 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68  .  The use of th
28ac0 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e  e.** new "v2" in
28ad0 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d  terface is recom
28ae0 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61  mended for new a
28af0 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20  pplications but 
28b00 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  the legacy.** in
28b10 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e  terface will con
28b20 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70  tinue to be supp
28b30 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e  orted..**.** ^In
28b40 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
28b50 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 72  rface, the retur
28b60 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20  n value will be 
28b70 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42  either [SQLITE_B
28b80 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  USY],.** [SQLITE
28b90 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  _DONE], [SQLITE_
28ba0 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52  ROW], [SQLITE_ER
28bb0 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ROR], or [SQLITE
28bc0 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69  _MISUSE]..** ^Wi
28bd0 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  th the "v2" inte
28be0 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68  rface, any of th
28bf0 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20  e other [result 
28c00 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78  codes] or.** [ex
28c10 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
28c20 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65  des] might be re
28c30 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a  turned as well..
28c40 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42  **.** ^[SQLITE_B
28c50 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  USY] means that 
28c60 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67  the database eng
28c70 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74  ine was unable t
28c80 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a  o acquire the.**
28c90 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20   database locks 
28ca0 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69  it needs to do i
28cb0 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65  ts job.  ^If the
28cc0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20   statement is a 
28cd0 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f  [COMMIT].** or o
28ce0 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66  ccurs outside of
28cf0 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61   an explicit tra
28d00 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79  nsaction, then y
28d10 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65  ou can retry the
28d20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  .** statement.  
28d30 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  If the statement
28d40 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49   is not a [COMMI
28d50 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69  T] and occurs wi
28d60 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69  thin an.** expli
28d70 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  cit transaction 
28d80 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20  then you should 
28d90 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61  rollback the tra
28da0 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a  nsaction before.
28db0 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a  ** continuing..*
28dc0 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f  *.** ^[SQLITE_DO
28dd0 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  NE] means that t
28de0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73  he statement has
28df0 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
28e00 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  ing.** successfu
28e10 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74  lly.  sqlite3_st
28e20 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ep() should not 
28e30 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  be called again 
28e40 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a  on this virtual.
28e50 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f  ** machine witho
28e60 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67  ut first calling
28e70 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
28e80 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  )] to reset the 
28e90 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69  virtual.** machi
28ea0 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69  ne back to its i
28eb0 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a  nitial state..**
28ec0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20  .** ^If the SQL 
28ed0 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20  statement being 
28ee0 65 78 65 63 75 74 65 64 20 72 65 74 75 72 6e 73  executed returns
28ef0 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20   any data, then 
28f00 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20  [SQLITE_ROW].** 
28f10 69 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68  is returned each
28f20 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20   time a new row 
28f30 6f 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79  of data is ready
28f40 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20   for processing 
28f50 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72  by the.** caller
28f60 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79  . The values may
28f70 20 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69   be accessed usi
28f80 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61  ng the [column a
28f90 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d  ccess functions]
28fa0 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  ..** sqlite3_ste
28fb0 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67  p() is called ag
28fc0 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20  ain to retrieve 
28fd0 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20  the next row of 
28fe0 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51  data..**.** ^[SQ
28ff0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e  LITE_ERROR] mean
29000 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d  s that a run-tim
29010 65 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 73  e error (such as
29020 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a   a constraint.**
29030 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20   violation) has 
29040 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74  occurred.  sqlit
29050 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64  e3_step() should
29060 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61   not be called a
29070 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56  gain on.** the V
29080 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74  M. More informat
29090 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64  ion may be found
290a0 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
290b0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a  ite3_errmsg()]..
290c0 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67  ** ^With the leg
290d0 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61  acy interface, a
290e0 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65   more specific e
290f0 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65  rror code (for e
29100 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49  xample,.** [SQLI
29110 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b  TE_INTERRUPT], [
29120 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20  SQLITE_SCHEMA], 
29130 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d  [SQLITE_CORRUPT]
29140 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a  , and so forth).
29150 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e  ** can be obtain
29160 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  ed by calling [s
29170 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
29180 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  on the.** [prepa
29190 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
291a0 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e   ^In the "v2" in
291b0 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20  terface,.** the 
291c0 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72  more specific er
291d0 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75  ror code is retu
291e0 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79  rned directly by
291f0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
29200 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d  .**.** [SQLITE_M
29210 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61  ISUSE] means tha
29220 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69  t the this routi
29230 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e  ne was called in
29240 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a  appropriately..*
29250 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73  * Perhaps it was
29260 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72   called on a [pr
29270 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
29280 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c  ] that has.** al
29290 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69  ready been [sqli
292a0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66  te3_finalize | f
292b0 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20  inalized] or on 
292c0 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20  one that had.** 
292d0 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72  previously retur
292e0 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ned [SQLITE_ERRO
292f0 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f  R] or [SQLITE_DO
29300 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c  NE].  Or it coul
29310 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65  d.** be the case
29320 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64   that the same d
29330 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
29340 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64  on is being used
29350 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f   by two or.** mo
29360 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68  re threads at th
29370 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e  e same moment in
29380 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72   time..**.** For
29390 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66   all versions of
293a0 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e   SQLite up to an
293b0 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e  d including 3.6.
293c0 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a  23.1, a call to.
293d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
293e0 74 28 29 5d 20 77 61 73 20 72 65 71 75 69 72 65  t()] was require
293f0 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f  d after sqlite3_
29400 73 74 65 70 28 29 20 72 65 74 75 72 6e 65 64 20  step() returned 
29410 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65  anything.** othe
29420 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52  r than [SQLITE_R
29430 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73  OW] before any s
29440 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61  ubsequent invoca
29450 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74  tion of.** sqlit
29460 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c  e3_step().  Fail
29470 75 72 65 20 74 6f 20 72 65 73 65 74 20 74 68 65  ure to reset the
29480 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
29490 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73  ent using .** [s
294a0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
294b0 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20  would result in 
294c0 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  an [SQLITE_MISUS
294d0 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a  E] return from.*
294e0 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
294f0 2e 20 20 42 75 74 20 61 66 74 65 72 20 76 65 72  .  But after ver
29500 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73  sion 3.6.23.1, s
29510 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62 65  qlite3_step() be
29520 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b  gan.** calling [
29530 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
29540 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69   automatically i
29550 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73 74 61  n this circumsta
29560 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74 68  nce rather.** th
29570 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51  an returning [SQ
29580 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54  LITE_MISUSE].  T
29590 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69  his is not consi
295a0 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69 62  dered a compatib
295b0 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62  ility.** break b
295c0 65 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c 69  ecause any appli
295d0 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65 72  cation that ever
295e0 20 72 65 63 65 69 76 65 73 20 61 6e 20 53 51 4c   receives an SQL
295f0 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f 72  ITE_MISUSE error
29600 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62 79  .** is broken by
29610 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68   definition.  Th
29620 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  e [SQLITE_OMIT_A
29630 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c  UTORESET] compil
29640 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a  e-time option.**
29650 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
29660 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67 61  restore the lega
29670 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a  cy behavior..**.
29680 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65  ** <b>Goofy Inte
29690 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e  rface Alert:</b>
296a0 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69   In the legacy i
296b0 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73 71  nterface, the sq
296c0 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20  lite3_step().** 
296d0 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 72  API always retur
296e0 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 72  ns a generic err
296f0 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45  or code, [SQLITE
29700 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69  _ERROR], followi
29710 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20  ng any.** error 
29720 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
29730 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51  TE_BUSY] and [SQ
29740 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59  LITE_MISUSE].  Y
29750 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20  ou must call.** 
29760 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
29770 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
29780 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64  nalize()] in ord
29790 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f  er to find one o
297a0 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69  f the.** specifi
297b0 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  c [error codes] 
297c0 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73 63  that better desc
297d0 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e  ribes the error.
297e0 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61  .** We admit tha
297f0 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66  t this is a goof
29800 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70  y design.  The p
29810 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20  roblem has been 
29820 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68  fixed.** with th
29830 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
29840 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 72  .  If you prepar
29850 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51  e all of your SQ
29860 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
29870 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71  using either [sq
29880 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
29890 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
298a0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
298b0 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68  instead.** of th
298c0 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65  e legacy [sqlite
298d0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64  3_prepare()] and
298e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
298f0 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65  e16()] interface
29900 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d  s,.** then the m
29910 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 72  ore specific [er
29920 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72  ror codes] are r
29930 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79  eturned directly
29940 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73  .** by sqlite3_s
29950 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 20  tep().  The use 
29960 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  of the "v2" inte
29970 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65  rface is recomme
29980 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  nded..*/.int sql
29990 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65  ite3_step(sqlite
299a0 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
299b0 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
299c0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
299d0 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 0a  a result set.**.
299e0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
299f0 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e  data_count(P) in
29a00 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
29a10 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
29a20 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20  lumns in the.** 
29a30 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74  current row of t
29a40 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  he result set of
29a50 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
29a60 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20  ment] P..** ^If 
29a70 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
29a80 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 20 68 61  nt P does not ha
29a90 76 65 20 72 65 73 75 6c 74 73 20 72 65 61 64 79  ve results ready
29aa0 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76   to return.** (v
29ab0 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20  ia calls to the 
29ac0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
29ad0 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f  int | sqlite3_co
29ae0 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20  lumn_*()] of.** 
29af0 69 6e 74 65 72 66 61 63 65 73 29 20 74 68 65 6e  interfaces) then
29b00 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
29b10 75 6e 74 28 50 29 20 72 65 74 75 72 6e 73 20 30  unt(P) returns 0
29b20 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
29b30 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
29b40 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72 65 74  routine also ret
29b50 75 72 6e 73 20 30 20 69 66 20 50 20 69 73 20 61  urns 0 if P is a
29b60 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
29b70 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
29b80 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75  ata_count(P) rou
29b90 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69  tine returns 0 i
29ba0 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63  f the previous c
29bb0 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
29bc0 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75  e3_step](P) retu
29bd0 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  rned [SQLITE_DON
29be0 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  E].  ^The sqlite
29bf0 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a  3_data_count(P).
29c00 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e  ** will return n
29c10 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65 76 69  on-zero if previ
29c20 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ous call to [sql
29c30 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65  ite3_step](P) re
29c40 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54  turned.** [SQLIT
29c50 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74 20 69  E_ROW], except i
29c60 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 74 68  n the case of th
29c70 65 20 5b 50 52 41 47 4d 41 20 69 6e 63 72 65 6d  e [PRAGMA increm
29c80 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a  ental_vacuum].**
29c90 20 77 68 65 72 65 20 69 74 20 61 6c 77 61 79 73   where it always
29ca0 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 73 69   returns zero si
29cb0 6e 63 65 20 65 61 63 68 20 73 74 65 70 20 6f 66  nce each step of
29cc0 20 74 68 61 74 20 6d 75 6c 74 69 2d 73 74 65 70   that multi-step
29cd0 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65 74 75 72  .** pragma retur
29ce0 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20  ns 0 columns of 
29cf0 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  data..**.** See 
29d00 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63  also: [sqlite3_c
29d10 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a  olumn_count()].*
29d20 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61  /.int sqlite3_da
29d30 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  ta_count(sqlite3
29d40 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
29d50 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
29d60 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61  Fundamental Data
29d70 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  types.** KEYWORD
29d80 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a  S: SQLITE_TEXT.*
29d90 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c  *.** ^(Every val
29da0 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73  ue in SQLite has
29db0 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e   one of five fun
29dc0 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70  damental datatyp
29dd0 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
29de0 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69  * <li> 64-bit si
29df0 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
29e00 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45  <li> 64-bit IEEE
29e10 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
29e20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73  number.** <li> s
29e30 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c  tring.** <li> BL
29e40 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a  OB.** <li> NULL.
29e50 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  ** </ul>)^.**.**
29e60 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
29e70 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65   are codes for e
29e80 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70  ach of those typ
29e90 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  es..**.** Note t
29ea0 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54  hat the SQLITE_T
29eb0 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73  EXT constant was
29ec0 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51   also used in SQ
29ed0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a  Lite version 2.*
29ee0 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65  * for a complete
29ef0 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61  ly different mea
29f00 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20  ning.  Software 
29f10 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e  that links again
29f20 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74  st both.** SQLit
29f30 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20  e version 2 and 
29f40 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
29f50 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49   should use SQLI
29f60 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a  TE3_TEXT, not.**
29f70 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f   SQLITE_TEXT..*/
29f80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
29f90 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 69  INTEGER  1.#defi
29fa0 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20  ne SQLITE_FLOAT 
29fb0 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
29fc0 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23  ITE_BLOB     4.#
29fd0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55  define SQLITE_NU
29fe0 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 20  LL     5.#ifdef 
29ff0 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e  SQLITE_TEXT.# un
2a000 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  def SQLITE_TEXT.
2a010 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53  #else.# define S
2a020 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 33  QLITE_TEXT     3
2a030 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20  .#endif.#define 
2a040 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20  SQLITE3_TEXT    
2a050 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   3../*.** CAPI3R
2a060 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65  EF: Result Value
2a070 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a  s From A Query.*
2a080 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c  * KEYWORDS: {col
2a090 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
2a0a0 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ions}.**.** Thes
2a0b0 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20  e routines form 
2a0c0 74 68 65 20 22 72 65 73 75 6c 74 20 73 65 74 22  the "result set"
2a0d0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
2a0e0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
2a0f0 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61  s return informa
2a100 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e  tion about a sin
2a110 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  gle column of th
2a120 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73  e current.** res
2a130 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65  ult row of a que
2a140 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 63  ry.  ^In every c
2a150 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61 72  ase the first ar
2a160 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
2a170 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70  ter.** to the [p
2a180 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2a190 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e 67  t] that is being
2a1a0 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65 20   evaluated (the 
2a1b0 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a  [sqlite3_stmt*].
2a1c0 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 74 75  ** that was retu
2a1d0 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  rned from [sqlit
2a1e0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2a1f0 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76   or one of its v
2a200 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20  ariants).** and 
2a210 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
2a220 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78  ent is the index
2a230 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66   of the column f
2a240 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61  or which informa
2a250 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62  tion.** should b
2a260 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 65  e returned. ^The
2a270 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e   leftmost column
2a280 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
2a290 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 65 78  et has the index
2a2a0 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62   0..** ^The numb
2a2b0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
2a2c0 20 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e 20   the result can 
2a2d0 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73  be determined us
2a2e0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
2a2f0 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e  column_count()].
2a300 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51  .**.** If the SQ
2a310 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73  L statement does
2a320 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70   not currently p
2a330 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20  oint to a valid 
2a340 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a  row, or if the.*
2a350 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69  * column index i
2a360 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20  s out of range, 
2a370 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e  the result is un
2a380 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73  defined..** Thes
2a390 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f  e routines may o
2a3a0 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68  nly be called wh
2a3b0 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  en the most rece
2a3c0 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  nt call to.** [s
2a3d0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
2a3e0 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  as returned [SQL
2a3f0 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69  ITE_ROW] and nei
2a400 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ther.** [sqlite3
2a410 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73  _reset()] nor [s
2a420 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2a430 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c  )] have been cal
2a440 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79  led subsequently
2a450 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74  ..** If any of t
2a460 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
2a470 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b  e called after [
2a480 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2a490 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
2a4a0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61  finalize()] or a
2a4b0 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74  fter [sqlite3_st
2a4c0 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e  ep()] has return
2a4d0 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20  ed.** something 
2a4e0 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
2a4f0 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73  TE_ROW], the res
2a500 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
2a510 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74  ed..** If [sqlit
2a520 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73  e3_step()] or [s
2a530 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2a540 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
2a550 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63  lize()].** are c
2a560 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66  alled from a dif
2a570 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77 68  ferent thread wh
2a580 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65  ile any of these
2a590 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65   routines.** are
2a5a0 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74   pending, then t
2a5b0 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
2a5c0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
2a5d0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ^The sqlite3_col
2a5e0 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69  umn_type() routi
2a5f0 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a  ne returns the.*
2a600 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  * [SQLITE_INTEGE
2a610 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64  R | datatype cod
2a620 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69  e] for the initi
2a630 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20  al data type.** 
2a640 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f  of the result co
2a650 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74 75  lumn.  ^The retu
2a660 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e  rned value is on
2a670 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54  e of [SQLITE_INT
2a680 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  EGER],.** [SQLIT
2a690 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54  E_FLOAT], [SQLIT
2a6a0 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45  E_TEXT], [SQLITE
2a6b0 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49  _BLOB], or [SQLI
2a6c0 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76  TE_NULL].  The v
2a6d0 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  alue.** returned
2a6e0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
2a6f0 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c  mn_type() is onl
2a700 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20  y meaningful if 
2a710 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65  no type.** conve
2a720 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75  rsions have occu
2a730 72 72 65 64 20 61 73 20 64 65 73 63 72 69 62 65  rred as describe
2a740 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20  d below.  After 
2a750 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
2a760 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20  n,.** the value 
2a770 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
2a780 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
2a790 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20  ) is undefined. 
2a7a0 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69   Future.** versi
2a7b0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61  ons of SQLite ma
2a7c0 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68  y change the beh
2a7d0 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33  avior of sqlite3
2a7e0 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a  _column_type().*
2a7f0 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79  * following a ty
2a800 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a  pe conversion..*
2a810 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  *.** ^If the res
2a820 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72  ult is a BLOB or
2a830 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68   UTF-8 string th
2a840 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  en the sqlite3_c
2a850 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a  olumn_bytes().**
2a860 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
2a870 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2a880 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f  ytes in that BLO
2a890 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  B or string..** 
2a8a0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2a8b0 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  s a UTF-16 strin
2a8c0 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  g, then sqlite3_
2a8d0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63  column_bytes() c
2a8e0 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73  onverts.** the s
2a8f0 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61  tring to UTF-8 a
2a900 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20  nd then returns 
2a910 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2a920 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  tes..** ^If the 
2a930 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65  result is a nume
2a940 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73  ric value then s
2a950 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2a960 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73  tes() uses.** [s
2a970 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
2a980 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  )] to convert th
2a990 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54  at value to a UT
2a9a0 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72  F-8 string and r
2a9b0 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75  eturns.** the nu
2a9c0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
2a9d0 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a   that string..**
2a9e0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
2a9f0 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71  is NULL, then sq
2aa00 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2aa10 65 73 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72  es() returns zer
2aa20 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  o..**.** ^If the
2aa30 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f   result is a BLO
2aa40 42 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69  B or UTF-16 stri
2aa50 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  ng then the sqli
2aa60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2aa70 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  16().** routine 
2aa80 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
2aa90 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
2aaa0 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  hat BLOB or stri
2aab0 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
2aac0 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 38  esult is a UTF-8
2aad0 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71   string, then sq
2aae0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2aaf0 65 73 31 36 28 29 20 63 6f 6e 76 65 72 74 73 0a  es16() converts.
2ab00 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f  ** the string to
2ab10 20 55 54 46 2d 31 36 20 61 6e 64 20 74 68 65 6e   UTF-16 and then
2ab20 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
2ab30 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a  ber of bytes..**
2ab40 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
2ab50 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c  is a numeric val
2ab60 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ue then sqlite3_
2ab70 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2ab80 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65   uses.** [sqlite
2ab90 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f  3_snprintf()] to
2aba0 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61   convert that va
2abb0 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 31 36 20  lue to a UTF-16 
2abc0 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72  string and retur
2abd0 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  ns.** the number
2abe0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
2abf0 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  t string..** ^If
2ac00 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e   the result is N
2ac10 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ULL, then sqlite
2ac20 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2ac30 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e  () returns zero.
2ac40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75  .**.** ^The valu
2ac50 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  es returned by [
2ac60 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2ac70 79 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20  ytes()] and .** 
2ac80 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2ac90 62 79 74 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f  bytes16()] do no
2aca0 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65  t include the ze
2acb0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73 20 61  ro terminators a
2acc0 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20  t the end.** of 
2acd0 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f  the string.  ^Fo
2ace0 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76  r clarity: the v
2acf0 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
2ad00 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
2ad10 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e  lumn_bytes()] an
2ad20 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d [sqlite3_colum
2ad30 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 61 72 65  n_bytes16()] are
2ad40 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
2ad50 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73  * bytes in the s
2ad60 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e  tring, not the n
2ad70 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
2ad80 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69  ers..**.** ^Stri
2ad90 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
2ada0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2adb0 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ext() and sqlite
2adc0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2add0 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79  ),.** even empty
2ade0 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c   strings, are al
2adf0 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  ways zero-termin
2ae00 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75  ated.  ^The retu
2ae10 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d  rn.** value from
2ae20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2ae30 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72  blob() for a zer
2ae40 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73  o-length BLOB is
2ae50 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
2ae60 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65  .**.** ^The obje
2ae70 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  ct returned by [
2ae80 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
2ae90 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a  alue()] is an.**
2aea0 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
2aeb0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2aec0 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65  ect.  An unprote
2aed0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2aee0 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79  ue object.** may
2aef0 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69   only be used wi
2af00 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  th [sqlite3_bind
2af10 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73  _value()] and [s
2af20 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
2af30 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68  lue()]..** If th
2af40 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  e [unprotected s
2af50 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2af60 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
2af70 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
2af80 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
2af90 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65  used in any othe
2afa0 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67  r way, including
2afb0 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75   calls.** to rou
2afc0 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69  tines like [sqli
2afd0 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d  te3_value_int()]
2afe0 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
2aff0 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20  _text()],.** or 
2b000 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
2b010 79 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 74 68  ytes()], then th
2b020 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
2b030 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  defined..**.** T
2b040 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74  hese routines at
2b050 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74  tempt to convert
2b060 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 65   the value where
2b070 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e   appropriate.  ^
2b080 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20  For.** example, 
2b090 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  if the internal 
2b0a0 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69  representation i
2b0b0 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65  s FLOAT and a te
2b0c0 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20  xt result.** is 
2b0d0 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69  requested, [sqli
2b0e0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
2b0f0 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c  is used internal
2b100 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68  ly to perform th
2b110 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20  e.** conversion 
2b120 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
2b130 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  ^(The following 
2b140 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68  table details th
2b150 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a  e conversions.**
2b160 20 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 65   that are applie
2b170 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  d:.**.** <blockq
2b180 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20  uote>.** <table 
2b190 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c  border="1">.** <
2b1a0 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c  tr><th> Internal
2b1b0 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65  <br>Type <th> Re
2b1c0 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20  quested<br>Type 
2b1d0 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e  <th>  Conversion
2b1e0 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  .**.** <tr><td> 
2b1f0 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e   NULL    <td> IN
2b200 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73  TEGER   <td> Res
2b210 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e  ult is 0.** <tr>
2b220 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
2b230 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
2b240 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a  > Result is 0.0.
2b250 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
2b260 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  L    <td>   TEXT
2b270 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
2b280 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a  is NULL pointer.
2b290 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
2b2a0 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  L    <td>   BLOB
2b2b0 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
2b2c0 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a  is NULL pointer.
2b2d0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
2b2e0 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  GER  <td>  FLOAT
2b2f0 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74      <td> Convert
2b300 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f   from integer to
2b310 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74   float.** <tr><t
2b320 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
2b330 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
2b340 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20  ASCII rendering 
2b350 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a  of the integer.*
2b360 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
2b370 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20  ER  <td>   BLOB 
2b380 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20     <td> Same as 
2b390 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a  INTEGER->TEXT.**
2b3a0 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
2b3b0 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
2b3c0 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66    <td> Convert f
2b3d0 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74  rom float to int
2b3e0 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  eger.** <tr><td>
2b3f0 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20    FLOAT   <td>  
2b400 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53   TEXT    <td> AS
2b410 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  CII rendering of
2b420 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74   the float.** <t
2b430 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
2b440 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
2b450 74 64 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f 41  td> Same as FLOA
2b460 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c  T->TEXT.** <tr><
2b470 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
2b480 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
2b490 20 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c   Use atoi().** <
2b4a0 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
2b4b0 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
2b4c0 3c 74 64 3e 20 55 73 65 20 61 74 6f 66 28 29 0a  <td> Use atof().
2b4d0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58  ** <tr><td>  TEX
2b4e0 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  T    <td>   BLOB
2b4f0 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e      <td> No chan
2b500 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ge.** <tr><td>  
2b510 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54  BLOB    <td> INT
2b520 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76  EGER   <td> Conv
2b530 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e  ert to TEXT then
2b540 20 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c   use atoi().** <
2b550 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
2b560 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
2b570 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20  <td> Convert to 
2b580 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74  TEXT then use at
2b590 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  of().** <tr><td>
2b5a0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20    BLOB    <td>  
2b5b0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64   TEXT    <td> Ad
2b5c0 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  d a zero termina
2b5d0 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a  tor if needed.**
2b5e0 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62   </table>.** </b
2b5f0 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a  lockquote>)^.**.
2b600 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f  ** The table abo
2b610 76 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e  ve makes referen
2b620 63 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43  ce to standard C
2b630 20 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f   library functio
2b640 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64  ns atoi().** and
2b650 20 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65   atof().  SQLite
2b660 20 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79   does not really
2b670 20 75 73 65 20 74 68 65 73 65 20 66 75 6e 63 74   use these funct
2b680 69 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74  ions.  It has it
2b690 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c  s.** own equival
2b6a0 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75  ent internal rou
2b6b0 74 69 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69  tines.  The atoi
2b6c0 28 29 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61  () and atof() na
2b6d0 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20  mes are.** used 
2b6e0 69 6e 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72  in the table for
2b6f0 20 62 72 65 76 69 74 79 20 61 6e 64 20 62 65 63   brevity and bec
2b700 61 75 73 65 20 74 68 65 79 20 61 72 65 20 66 61  ause they are fa
2b710 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a  miliar to most.*
2b720 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e  * C programmers.
2b730 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
2b740 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65   when type conve
2b750 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f  rsions occur, po
2b760 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20  inters returned 
2b770 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c  by prior.** call
2b780 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
2b790 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69  umn_blob(), sqli
2b7a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2b7b0 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c  ), and/or.** sql
2b7c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2b7d0 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61  16() may be inva
2b7e0 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65  lidated..** Type
2b7f0 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64   conversions and
2b800 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64   pointer invalid
2b810 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63  ations might occ
2b820 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c  ur.** in the fol
2b830 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a  lowing cases:.**
2b840 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
2b850 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
2b860 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61  tent is a BLOB a
2b870 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
2b880 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20  n_text() or.**  
2b890 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
2b8a0 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63  mn_text16() is c
2b8b0 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74  alled.  A zero-t
2b8c0 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a  erminator might.
2b8d0 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20  **      need to 
2b8e0 62 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 20  be added to the 
2b8f0 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20  string.</li>.** 
2b900 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c  <li> The initial
2b910 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d   content is UTF-
2b920 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74  8 text and sqlit
2b930 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2b940 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  6() or.**      s
2b950 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2b960 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64  xt16() is called
2b970 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d  .  The content m
2b980 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
2b990 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d  .**      to UTF-
2b9a0 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e  16.</li>.** <li>
2b9b0 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
2b9c0 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74  tent is UTF-16 t
2b9d0 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
2b9e0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
2b9f0 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
2ba00 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
2ba10 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20  is called.  The 
2ba20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20  content must be 
2ba30 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20  converted.**    
2ba40 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e    to UTF-8.</li>
2ba50 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
2ba60 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74  ^Conversions bet
2ba70 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e  ween UTF-16be an
2ba80 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61  d UTF-16le are a
2ba90 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c  lways done in pl
2baa0 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f  ace and do.** no
2bab0 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70  t invalidate a p
2bac0 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68  rior pointer, th
2bad0 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74  ough of course t
2bae0 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
2baf0 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74  e buffer.** that
2bb00 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74   the prior point
2bb10 65 72 20 72 65 66 65 72 65 6e 63 65 73 20 77 69  er references wi
2bb20 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64  ll have been mod
2bb30 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69  ified.  Other ki
2bb40 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72  nds.** of conver
2bb50 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e  sion are done in
2bb60 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69   place when it i
2bb70 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20  s possible, but 
2bb80 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a  sometimes they.*
2bb90 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62  * are not possib
2bba0 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20  le and in those 
2bbb0 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e  cases prior poin
2bbc0 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64  ters are invalid
2bbd0 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ated..**.** The 
2bbe0 73 61 66 65 73 74 20 61 6e 64 20 65 61 73 69 65  safest and easie
2bbf0 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 70  st to remember p
2bc00 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f  olicy is to invo
2bc10 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  ke these routine
2bc20 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74  s.** in one of t
2bc30 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79  he following way
2bc40 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
2bc50 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
2bc60 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c  lumn_text() foll
2bc70 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
2bc80 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f  column_bytes()</
2bc90 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  li>.**  <li>sqli
2bca0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
2bcb0 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
2bcc0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2bcd0 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c  es()</li>.**  <l
2bce0 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
2bcf0 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77  _text16() follow
2bd00 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
2bd10 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f  lumn_bytes16()</
2bd20 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  li>.** </ul>.**.
2bd30 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  ** In other word
2bd40 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61  s, you should ca
2bd50 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ll sqlite3_colum
2bd60 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c  n_text(),.** sql
2bd70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
2bd80 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  (), or sqlite3_c
2bd90 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66  olumn_text16() f
2bda0 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68  irst to force th
2bdb0 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f  e result.** into
2bdc0 20 74 68 65 20 64 65 73 69 72 65 64 20 66 6f 72   the desired for
2bdd0 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65  mat, then invoke
2bde0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2bdf0 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71  bytes() or.** sq
2be00 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2be10 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74  es16() to find t
2be20 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72  he size of the r
2be30 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d  esult.  Do not m
2be40 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73  ix calls.** to s
2be50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2be60 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  xt() or sqlite3_
2be70 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69  column_blob() wi
2be80 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73  th calls to.** s
2be90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2bea0 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20  tes16(), and do 
2beb0 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f  not mix calls to
2bec0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2bed0 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68  text16().** with
2bee0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
2bef0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2bf00 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69  ..**.** ^The poi
2bf10 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 61  nters returned a
2bf20 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61  re valid until a
2bf30 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
2bf40 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65   occurs as.** de
2bf50 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f  scribed above, o
2bf60 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33  r until [sqlite3
2bf70 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c  _step()] or [sql
2bf80 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
2bf90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
2bfa0 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c  alize()] is call
2bfb0 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79  ed.  ^The memory
2bfc0 20 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 68   space used to h
2bfd0 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61  old strings.** a
2bfe0 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65  nd BLOBs is free
2bff0 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  d automatically.
2c000 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20    Do <b>not</b> 
2c010 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72  pass the pointer
2c020 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73  s returned.** [s
2c030 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2c040 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ob()], [sqlite3_
2c050 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20  column_text()], 
2c060 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71  etc. into.** [sq
2c070 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a  lite3_free()]..*
2c080 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f  *.** ^(If a memo
2c090 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
2c0a0 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e  ror occurs durin
2c0b0 67 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e  g the evaluation
2c0c0 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68   of any.** of th
2c0d0 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20  ese routines, a 
2c0e0 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73  default value is
2c0f0 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
2c100 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a  default value.**
2c110 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20 69   is either the i
2c120 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c  nteger 0, the fl
2c130 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d  oating point num
2c140 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55  ber 0.0, or a NU
2c150 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20  LL.** pointer.  
2c160 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  Subsequent calls
2c170 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   to [sqlite3_err
2c180 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74  code()] will ret
2c190 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e  urn.** [SQLITE_N
2c1a0 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73  OMEM].)^.*/.cons
2c1b0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2c1c0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69  column_blob(sqli
2c1d0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2c1e0 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
2c1f0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73  3_column_bytes(s
2c200 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2c210 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
2c220 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2c230 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  s16(sqlite3_stmt
2c240 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f  *, int iCol);.do
2c250 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  uble sqlite3_col
2c260 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  umn_double(sqlit
2c270 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2c280 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
2c290 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69  _column_int(sqli
2c2a0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2c2b0 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  Col);.sqlite3_in
2c2c0 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  t64 sqlite3_colu
2c2d0 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  mn_int64(sqlite3
2c2e0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2c2f0 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65  );.const unsigne
2c300 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  d char *sqlite3_
2c310 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69  column_text(sqli
2c320 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2c330 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  Col);.const void
2c340 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2c350 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
2c360 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2c370 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
2c380 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65  lumn_type(sqlite
2c390 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2c3a0 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75  l);.sqlite3_valu
2c3b0 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e *sqlite3_colum
2c3c0 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  n_value(sqlite3_
2c3d0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2c3e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2c3f0 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65  F: Destroy A Pre
2c400 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
2c410 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  Object.**.** ^Th
2c420 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  e sqlite3_finali
2c430 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  ze() function is
2c440 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74   called to delet
2c450 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  e a [prepared st
2c460 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66  atement]..** ^If
2c470 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
2c480 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74   evaluation of t
2c490 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63  he statement enc
2c4a0 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f  ountered no erro
2c4b0 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 20  rs.** or if the 
2c4c0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 76  statement is nev
2c4d0 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74 65  er been evaluate
2c4e0 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  d, then sqlite3_
2c4f0 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 72  finalize() retur
2c500 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e  ns.** SQLITE_OK.
2c510 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72    ^If the most r
2c520 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e  ecent evaluation
2c530 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53 20   of statement S 
2c540 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20  failed, then.** 
2c550 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2c560 28 53 29 20 72 65 74 75 72 6e 73 20 74 68 65 20  (S) returns the 
2c570 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72  appropriate [err
2c580 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b  or code] or.** [
2c590 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
2c5a0 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ode]..**.** ^The
2c5b0 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
2c5c0 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61 6e  e(S) routine can
2c5d0 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e   be called at an
2c5e0 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a  y point during.*
2c5f0 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c 65  * the life cycle
2c600 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74   of [prepared st
2c610 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62  atement] S:.** b
2c620 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 20  efore statement 
2c630 53 20 69 73 20 65 76 65 72 20 65 76 61 6c 75 61  S is ever evalua
2c640 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e  ted, after.** on
2c650 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20  e or more calls 
2c660 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
2c670 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 61  t()], or after a
2c680 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73  ny call.** to [s
2c690 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72  qlite3_step()] r
2c6a0 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
2c6b0 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
2c6c0 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a  statement has.**
2c6d0 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75   completed execu
2c6e0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76  tion..**.** ^Inv
2c6f0 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69  oking sqlite3_fi
2c700 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55  nalize() on a NU
2c710 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20  LL pointer is a 
2c720 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a  harmless no-op..
2c730 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  **.** The applic
2c740 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c  ation must final
2c750 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70 61  ize every [prepa
2c760 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
2c770 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 64  n order to avoid
2c780 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 61  .** resource lea
2c790 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67 72 69  ks.  It is a gri
2c7a0 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 20  evous error for 
2c7b0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
2c7c0 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a  to try to use.**
2c7d0 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74   a prepared stat
2c7e0 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68  ement after it h
2c7f0 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  as been finalize
2c800 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20 61  d.  Any use of a
2c810 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
2c820 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20  tement after it 
2c830 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  has been finaliz
2c840 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e  ed can result in
2c850 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a   undefined and.*
2c860 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65  * undesirable be
2c870 68 61 76 69 6f 72 20 73 75 63 68 20 61 73 20 73  havior such as s
2c880 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65 61  egfaults and hea
2c890 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f  p corruption..*/
2c8a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e  .int sqlite3_fin
2c8b0 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74  alize(sqlite3_st
2c8c0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
2c8d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
2c8e0 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74  et A Prepared St
2c8f0 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
2c900 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2c910 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f  _reset() functio
2c920 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72  n is called to r
2c930 65 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64  eset a [prepared
2c940 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f   statement].** o
2c950 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74  bject back to it
2c960 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c  s initial state,
2c970 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d   ready to be re-
2c980 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e  executed..** ^An
2c990 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  y SQL statement 
2c9a0 76 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68  variables that h
2c9b0 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20  ad values bound 
2c9c0 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a  to them using.**
2c9d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
2c9e0 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65  nd_blob | sqlite
2c9f0 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20  3_bind_*() API] 
2ca00 72 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c  retain their val
2ca10 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c  ues..** Use [sql
2ca20 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69  ite3_clear_bindi
2ca30 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20  ngs()] to reset 
2ca40 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a  the bindings..**
2ca50 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
2ca60 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65  3_reset(S)] inte
2ca70 72 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65  rface resets the
2ca80 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2ca90 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20  ment] S.** back 
2caa0 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  to the beginning
2cab0 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e   of its program.
2cac0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  .**.** ^If the m
2cad0 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
2cae0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
2caf0 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20  (S)] for the.** 
2cb00 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2cb10 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20  ent] S returned 
2cb20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20  [SQLITE_ROW] or 
2cb30 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a  [SQLITE_DONE],.*
2cb40 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33  * or if [sqlite3
2cb50 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65  _step(S)] has ne
2cb60 76 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20  ver before been 
2cb70 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20  called on S,.** 
2cb80 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  then [sqlite3_re
2cb90 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20  set(S)] returns 
2cba0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a  [SQLITE_OK]..**.
2cbb0 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
2cbc0 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
2cbd0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
2cbe0 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65   for the.** [pre
2cbf0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2cc00 20 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20   S indicated an 
2cc10 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b  error, then.** [
2cc20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
2cc30 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70  ] returns an app
2cc40 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20  ropriate [error 
2cc50 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  code]..**.** ^Th
2cc60 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
2cc70 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64  (S)] interface d
2cc80 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
2cc90 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20  he values.** of 
2cca0 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  any [sqlite3_bin
2ccb0 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d  d_blob|bindings]
2ccc0 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65   on the [prepare
2ccd0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a  d statement] S..
2cce0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72  */.int sqlite3_r
2ccf0 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  eset(sqlite3_stm
2cd00 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
2cd10 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61  * CAPI3REF: Crea
2cd20 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53  te Or Redefine S
2cd30 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  QL Functions.** 
2cd40 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74  KEYWORDS: {funct
2cd50 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75  ion creation rou
2cd60 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52  tines}.** KEYWOR
2cd70 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e  DS: {application
2cd80 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
2cd90 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52  ction}.** KEYWOR
2cda0 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e  DS: {application
2cdb0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
2cdc0 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54  ctions}.**.** ^T
2cdd0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28  hese functions (
2cde0 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f  collectively kno
2cdf0 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20  wn as "function 
2ce00 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  creation routine
2ce10 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20  s").** are used 
2ce20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74  to add SQL funct
2ce30 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74  ions or aggregat
2ce40 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e  es or to redefin
2ce50 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a  e the behavior.*
2ce60 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51  * of existing SQ
2ce70 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61  L functions or a
2ce80 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20  ggregates.  The 
2ce90 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73  only differences
2cea0 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73   between.** thes
2ceb0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74  e routines are t
2cec0 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  he text encoding
2ced0 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a   expected for.**
2cee0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
2cef0 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20  meter (the name 
2cf00 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  of the function 
2cf10 62 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a  being created).*
2cf20 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e  * and the presen
2cf30 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66  ce or absence of
2cf40 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 63 61   a destructor ca
2cf50 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68  llback for.** th
2cf60 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  e application da
2cf70 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  ta pointer..**.*
2cf80 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72  * ^The first par
2cf90 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 64  ameter is the [d
2cfa0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2cfb0 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65  on] to which the
2cfc0 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   SQL.** function
2cfd0 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e   is to be added.
2cfe0 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61    ^If an applica
2cff0 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74  tion uses more t
2d000 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65  han one database
2d010 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  .** connection t
2d020 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  hen application-
2d030 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
2d040 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64  tions must be ad
2d050 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64  ded.** to each d
2d060 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2d070 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a  on separately..*
2d080 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64  *.** ^The second
2d090 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
2d0a0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51  e name of the SQ
2d0b0 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  L function to be
2d0c0 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72   created or.** r
2d0d0 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20  edefined.  ^The 
2d0e0 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61  length of the na
2d0f0 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f  me is limited to
2d100 20 32 35 35 20 62 79 74 65 73 20 69 6e 20 61 20   255 bytes in a 
2d110 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65  UTF-8.** represe
2d120 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69  ntation, exclusi
2d130 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74  ve of the zero-t
2d140 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74  erminator.  ^Not
2d150 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a  e that the name.
2d160 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20  ** length limit 
2d170 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65  is in UTF-8 byte
2d180 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s, not character
2d190 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74  s nor UTF-16 byt
2d1a0 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74  es.  .** ^Any at
2d1b0 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20  tempt to create 
2d1c0 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  a function with 
2d1d0 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a  a longer name.**
2d1e0 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20   will result in 
2d1f0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
2d200 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a  being returned..
2d210 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64  **.** ^The third
2d220 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67   parameter (nArg
2d230 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62  ).** is the numb
2d240 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
2d250 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e  that the SQL fun
2d260 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
2d270 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66  egate takes. ^If
2d280 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20   this parameter 
2d290 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20  is -1, then the 
2d2a0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
2d2b0 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79  ** aggregate may
2d2c0 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72   take any number
2d2d0 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65   of arguments be
2d2e0 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20  tween 0 and the 
2d2f0 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20  limit.** set by 
2d300 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28  [sqlite3_limit](
2d310 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  [SQLITE_LIMIT_FU
2d320 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49  NCTION_ARG]).  I
2d330 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70  f the third.** p
2d340 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73  arameter is less
2d350 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61   than -1 or grea
2d360 74 65 72 20 74 68 61 6e 20 31 32 37 20 74 68 65  ter than 127 the
2d370 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
2d380 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a  s.** undefined..
2d390 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74  **.** ^The fourt
2d3a0 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65  h parameter, eTe
2d3b0 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73  xtRep, specifies
2d3c0 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45   what.** [SQLITE
2d3d0 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63  _UTF8 | text enc
2d3e0 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20  oding] this SQL 
2d3f0 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73  function prefers
2d400 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61   for.** its para
2d410 6d 65 74 65 72 73 2e 20 20 45 76 65 72 79 20 53  meters.  Every S
2d420 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  QL function impl
2d430 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20  ementation must 
2d440 62 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a  be able to work.
2d450 2a 2a 20 77 69 74 68 20 55 54 46 2d 38 2c 20 55  ** with UTF-8, U
2d460 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d  TF-16le, or UTF-
2d470 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65 20  16be.  But some 
2d480 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
2d490 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65  may be.** more e
2d4a0 66 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f 6e  fficient with on
2d4b0 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20  e encoding than 
2d4c0 61 6e 6f 74 68 65 72 2e 20 20 5e 41 6e 20 61 70  another.  ^An ap
2d4d0 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a  plication may.**
2d4e0 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
2d4f0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2d500 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65  ) or sqlite3_cre
2d510 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
2d520 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d   multiple.** tim
2d530 65 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  es with the same
2d540 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69   function but wi
2d550 74 68 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c  th different val
2d560 75 65 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e  ues of eTextRep.
2d570 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70  .** ^When multip
2d580 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
2d590 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66  ns of the same f
2d5a0 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69  unction are avai
2d5b0 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a  lable, SQLite.**
2d5c0 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f   will pick the o
2d5d0 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73  ne that involves
2d5e0 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e   the least amoun
2d5f0 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72  t of data conver
2d600 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72  sion..** If ther
2d610 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67  e is only a sing
2d620 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
2d630 6e 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74  n which does not
2d640 20 63 61 72 65 20 77 68 61 74 20 74 65 78 74 0a   care what text.
2d650 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75  ** encoding is u
2d660 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f  sed, then the fo
2d670 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68  urth argument sh
2d680 6f 75 6c 64 20 62 65 20 5b 53 51 4c 49 54 45 5f  ould be [SQLITE_
2d690 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ANY]..**.** ^(Th
2d6a0 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65  e fifth paramete
2d6b0 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72  r is an arbitrar
2d6c0 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20  y pointer.  The 
2d6d0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
2d6e0 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  f the.** functio
2d6f0 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73  n can gain acces
2d700 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65  s to this pointe
2d710 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  r using [sqlite3
2d720 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e  _user_data()].)^
2d730 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74  .**.** ^The sixt
2d740 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20 65  h, seventh and e
2d750 69 67 68 74 68 20 70 61 72 61 6d 65 74 65 72 73  ighth parameters
2d760 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61  , xFunc, xStep a
2d770 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a  nd xFinal, are.*
2d780 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d  * pointers to C-
2d790 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f  language functio
2d7a0 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ns that implemen
2d7b0 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
2d7c0 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
2d7d0 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51  te. ^A scalar SQ
2d7e0 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  L function requi
2d7f0 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74  res an implement
2d800 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75  ation of the xFu
2d810 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f  nc.** callback o
2d820 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  nly; NULL pointe
2d830 72 73 20 6d 75 73 74 20 62 65 20 70 61 73 73 65  rs must be passe
2d840 64 20 61 73 20 74 68 65 20 78 53 74 65 70 20 61  d as the xStep a
2d850 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72  nd xFinal.** par
2d860 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67  ameters. ^An agg
2d870 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
2d880 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20  ion requires an 
2d890 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
2d8a0 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78  f xStep.** and x
2d8b0 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70  Final and NULL p
2d8c0 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20 70  ointer must be p
2d8d0 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e  assed for xFunc.
2d8e0 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65   ^To delete an e
2d8f0 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66  xisting.** SQL f
2d900 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65  unction or aggre
2d910 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20  gate, pass NULL 
2d920 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c  pointers for all
2d930 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a   three function.
2d940 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a  ** callbacks..**
2d950 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 6e  .** ^(If the nin
2d960 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
2d970 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2d980 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20  unction_v2() is 
2d990 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65  not NULL,.** the
2d9a0 6e 20 69 74 20 69 73 20 64 65 73 74 72 75 63 74  n it is destruct
2d9b0 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69  or for the appli
2d9c0 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
2d9d0 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73  ter. .** The des
2d9e0 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b  tructor is invok
2d9f0 65 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63  ed when the func
2da00 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c  tion is deleted,
2da10 20 65 69 74 68 65 72 20 62 79 20 62 65 69 6e 67   either by being
2da20 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f  .** overloaded o
2da30 72 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62  r when the datab
2da40 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  ase connection c
2da50 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65  loses.)^.** ^The
2da60 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 61   destructor is a
2da70 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74  lso invoked if t
2da80 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71  he call to.** sq
2da90 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2daa0 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73  ction_v2() fails
2dab0 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64  ..** ^When the d
2dac0 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61  estructor callba
2dad0 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20  ck of the tenth 
2dae0 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76  parameter is inv
2daf0 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70  oked, it.** is p
2db00 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61  assed a single a
2db10 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
2db20 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61   a copy of the a
2db30 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
2db40 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63  .** pointer whic
2db50 68 20 77 61 73 20 74 68 65 20 66 69 66 74 68 20  h was the fifth 
2db60 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
2db70 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2db80 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  tion_v2()..**.**
2db90 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74 65   ^It is permitte
2dba0 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75  d to register mu
2dbb0 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
2dbc0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
2dbd0 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  me.** functions 
2dbe0 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61  with the same na
2dbf0 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74 68  me but with eith
2dc00 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d  er differing num
2dc10 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d  bers of.** argum
2dc20 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e  ents or differin
2dc30 67 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74  g preferred text
2dc40 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51   encodings.  ^SQ
2dc50 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a  Lite will use.**
2dc60 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
2dc70 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c  ion that most cl
2dc80 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68  osely matches th
2dc90 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74  e way in which t
2dca0 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69  he.** SQL functi
2dcb0 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20  on is used.  ^A 
2dcc0 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
2dcd0 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e  ntation with a n
2dce0 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e  on-negative.** n
2dcf0 41 72 67 20 70 61 72 61 6d 65 74 65 72 20 69 73  Arg parameter is
2dd00 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 68 20   a better match 
2dd10 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20  than a function 
2dd20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
2dd30 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76  ith.** a negativ
2dd40 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63  e nArg.  ^A func
2dd50 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70  tion where the p
2dd60 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
2dd70 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65  coding.** matche
2dd80 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65  s the database e
2dd90 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74  ncoding is a bet
2dda0 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61  ter.** match tha
2ddb0 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  n a function whe
2ddc0 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
2ddd0 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a  is different.  .
2dde0 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77  ** ^A function w
2ddf0 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
2de00 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 20  g difference is 
2de10 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20  between UTF16le 
2de20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69  and UTF16be.** i
2de30 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68  s a closer match
2de40 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e   than a function
2de50 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64   where the encod
2de60 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69  ing difference i
2de70 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46  s.** between UTF
2de80 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a  8 and UTF16..**.
2de90 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e  ** ^Built-in fun
2dea0 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76  ctions may be ov
2deb0 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20  erloaded by new 
2dec0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2ded0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a  ned functions..*
2dee0 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61  *.** ^An applica
2def0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
2df00 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74  ction is permitt
2df10 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72  ed to call other
2df20 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72  .** SQLite inter
2df30 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c  faces.  However,
2df40 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74   such calls must
2df50 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68   not.** close th
2df60 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2df70 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69  ction nor finali
2df80 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 65 20  ze or reset the 
2df90 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74  prepared.** stat
2dfa0 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74  ement in which t
2dfb0 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  he function is r
2dfc0 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73  unning..*/.int s
2dfd0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2dfe0 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65  nction(.  sqlite
2dff0 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63  3 *db,.  const c
2e000 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  har *zFunctionNa
2e010 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
2e020 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
2e030 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
2e040 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
2e050 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
2e060 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
2e070 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
2e080 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
2e090 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
2e0a0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
2e0b0 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
2e0c0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29  ite3_context*).)
2e0d0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
2e0e0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
2e0f0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a  .  sqlite3 *db,.
2e100 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46    const void *zF
2e110 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69  unctionName,.  i
2e120 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65  nt nArg,.  int e
2e130 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20  TextRep,.  void 
2e140 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a  *pApp,.  void (*
2e150 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
2e160 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
2e170 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
2e180 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71  void (*xStep)(sq
2e190 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
2e1a0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
2e1b0 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  **),.  void (*xF
2e1c0 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f  inal)(sqlite3_co
2e1d0 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73  ntext*).);.int s
2e1e0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2e1f0 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c  nction_v2(.  sql
2e200 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
2e210 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f  t char *zFunctio
2e220 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
2e230 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
2e240 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
2e250 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
2e260 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2e270 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
2e280 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
2e290 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
2e2a0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
2e2b0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
2e2c0 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
2e2d0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2e2e0 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74  ),.  void(*xDest
2e2f0 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a  roy)(void*).);..
2e300 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2e310 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a  Text Encodings.*
2e320 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
2e330 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67  ant define integ
2e340 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 72 65  er codes that re
2e350 70 72 65 73 65 6e 74 20 74 68 65 20 76 61 72 69  present the vari
2e360 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f  ous.** text enco
2e370 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20  dings supported 
2e380 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64  by SQLite..*/.#d
2e390 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
2e3a0 38 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64  8           1.#d
2e3b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
2e3c0 31 36 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64  16LE        2.#d
2e3d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
2e3e0 31 36 42 45 20 20 20 20 20 20 20 20 33 0a 23 64  16BE        3.#d
2e3f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
2e400 31 36 20 20 20 20 20 20 20 20 20 20 34 20 20 20  16          4   
2e410 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62   /* Use native b
2e420 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65  yte order */.#de
2e430 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20  fine SQLITE_ANY 
2e440 20 20 20 20 20 20 20 20 20 20 20 35 20 20 20 20             5    
2e450 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  /* sqlite3_creat
2e460 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20  e_function only 
2e470 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2e480 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20  E_UTF16_ALIGNED 
2e490 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33   8    /* sqlite3
2e4a0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2e4b0 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  n only */../*.**
2e4c0 20 43 41 50 49 33 52 45 46 3a 20 44 65 70 72 65   CAPI3REF: Depre
2e4d0 63 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a  cated Functions.
2e4e0 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a  ** DEPRECATED.**
2e4f0 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
2e500 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63 61  ons are [depreca
2e510 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20  ted].  In order 
2e520 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62  to maintain.** b
2e530 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
2e540 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65  bility with olde
2e550 72 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75  r code, these fu
2e560 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65  nctions continue
2e570 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f   .** to be suppo
2e580 72 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20  rted.  However, 
2e590 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  new applications
2e5a0 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a   should avoid.**
2e5b0 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 73   the use of thes
2e5c0 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f  e functions.  To
2e5d0 20 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20   help encourage 
2e5e0 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a  people to avoid.
2e5f0 2a 2a 20 75 73 69 6e 67 20 74 68 65 73 65 20 66  ** using these f
2e600 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65  unctions, we are
2e610 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65   not going to te
2e620 6c 6c 20 79 6f 75 20 77 68 61 74 20 74 68 65 79  ll you what they
2e630 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20   do..*/.#ifndef 
2e640 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52  SQLITE_OMIT_DEPR
2e650 45 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 44 45  ECATED.SQLITE_DE
2e660 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
2e670 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
2e680 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  ount(sqlite3_con
2e690 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44  text*);.SQLITE_D
2e6a0 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
2e6b0 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 71  lite3_expired(sq
2e6c0 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51  lite3_stmt*);.SQ
2e6d0 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
2e6e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e  int sqlite3_tran
2e6f0 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71  sfer_bindings(sq
2e700 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c  lite3_stmt*, sql
2e710 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c  ite3_stmt*);.SQL
2e720 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
2e730 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61  nt sqlite3_globa
2e740 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b  l_recover(void);
2e750 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
2e760 45 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  ED void sqlite3_
2e770 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76  thread_cleanup(v
2e780 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  oid);.SQLITE_DEP
2e790 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
2e7a0 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d  te3_memory_alarm
2e7b0 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73  (void(*)(void*,s
2e7c0 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74  qlite3_int64,int
2e7d0 29 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f  ),void*,sqlite3_
2e7e0 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a  int64);.#endif..
2e7f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2e800 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75  Obtaining SQL Fu
2e810 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72  nction Parameter
2e820 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68   Values.**.** Th
2e830 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70  e C-language imp
2e840 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53  lementation of S
2e850 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
2e860 20 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73   aggregates uses
2e870 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20  .** this set of 
2e880 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e  interface routin
2e890 65 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  es to access the
2e8a0 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65   parameter value
2e8b0 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63  s on.** the func
2e8c0 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74  tion or aggregat
2e8d0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75  e..**.** The xFu
2e8e0 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66  nc (for scalar f
2e8f0 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74  unctions) or xSt
2e900 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74  ep (for aggregat
2e910 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  es) parameters.*
2e920 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  * to [sqlite3_cr
2e930 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
2e940 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
2e950 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
2e960 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c  )].** define cal
2e970 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c  lbacks that impl
2e980 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75  ement the SQL fu
2e990 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
2e9a0 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33  egates..** The 3
2e9b0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
2e9c0 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20  these callbacks 
2e9d0 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
2e9e0 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70  ointers to.** [p
2e9f0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2ea00 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
2ea10 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b    There is one [
2ea20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2ea30 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63  bject for.** eac
2ea40 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
2ea50 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e  he SQL function.
2ea60 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73    These routines
2ea70 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20   are used to.** 
2ea80 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66  extract values f
2ea90 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33  rom the [sqlite3
2eaa0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
2eab0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
2eac0 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20  tines work only 
2ead0 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20  with [protected 
2eae0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2eaf0 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61  bjects..** Any a
2eb00 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68  ttempt to use th
2eb10 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20  ese routines on 
2eb20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  an [unprotected 
2eb30 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a  sqlite3_value].*
2eb40 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73  * object results
2eb50 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65   in undefined be
2eb60 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  havior..**.** ^T
2eb70 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f  hese routines wo
2eb80 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65  rk just like the
2eb90 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b   corresponding [
2eba0 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
2ebb0 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65  nctions].** exce
2ebc0 70 74 20 74 68 61 74 20 20 74 68 65 73 65 20 72  pt that  these r
2ebd0 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73  outines take a s
2ebe0 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64  ingle [protected
2ebf0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2ec00 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65  object.** pointe
2ec10 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b  r instead of a [
2ec20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70  sqlite3_stmt*] p
2ec30 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e  ointer and an in
2ec40 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d  teger column num
2ec50 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ber..**.** ^The 
2ec60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2ec70 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 65  xt16() interface
2ec80 20 65 78 74 72 61 63 74 73 20 61 20 55 54 46 2d   extracts a UTF-
2ec90 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20  16 string.** in 
2eca0 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d  the native byte-
2ecb0 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73  order of the hos
2ecc0 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65  t machine.  ^The
2ecd0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
2ece0 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64  e_text16be() and
2ecf0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
2ed00 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66  ext16le() interf
2ed10 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20  aces.** extract 
2ed20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61  UTF-16 strings a
2ed30 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64  s big-endian and
2ed40 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72   little-endian r
2ed50 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a  espectively..**.
2ed60 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33  ** ^(The sqlite3
2ed70 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74  _value_numeric_t
2ed80 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ype() interface 
2ed90 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c  attempts to appl
2eda0 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66  y.** numeric aff
2edb0 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c  inity to the val
2edc0 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20  ue.  This means 
2edd0 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20  that an attempt 
2ede0 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f  is.** made to co
2edf0 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20  nvert the value 
2ee00 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72  to an integer or
2ee10 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e   floating point.
2ee20 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63    If.** such a c
2ee30 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73  onversion is pos
2ee40 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f  sible without lo
2ee50 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f  ss of informatio
2ee60 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77  n (in other.** w
2ee70 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c  ords, if the val
2ee80 75 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 74  ue is a string t
2ee90 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61  hat looks like a
2eea0 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e   number).** then
2eeb0 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20   the conversion 
2eec0 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f  is performed.  O
2eed0 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76  therwise no conv
2eee0 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a  ersion occurs..*
2eef0 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e  * The [SQLITE_IN
2ef00 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65  TEGER | datatype
2ef10 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69  ] after conversi
2ef20 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  on is returned.)
2ef30 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70  ^.**.** Please p
2ef40 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74  ay particular at
2ef50 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66  tention to the f
2ef60 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69  act that the poi
2ef70 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a  nter returned.**
2ef80 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76   from [sqlite3_v
2ef90 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73  alue_blob()], [s
2efa0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2efb0 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  t()], or.** [sql
2efc0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2efd0 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61  6()] can be inva
2efe0 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62  lidated by a sub
2eff0 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a  sequent call to.
2f000 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
2f010 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c  e_bytes()], [sql
2f020 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
2f030 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  16()], [sqlite3_
2f040 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a  value_text()],.*
2f050 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61  * or [sqlite3_va
2f060 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a  lue_text16()]..*
2f070 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
2f080 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  nes must be call
2f090 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
2f0a0 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68   thread as.** th
2f0b0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  e SQL function t
2f0c0 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65  hat supplied the
2f0d0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a   [sqlite3_value*
2f0e0 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f  ] parameters..*/
2f0f0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
2f100 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
2f110 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2f120 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
2f130 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33  ue_bytes(sqlite3
2f140 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
2f150 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
2f160 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  s16(sqlite3_valu
2f170 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69  e*);.double sqli
2f180 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65  te3_value_double
2f190 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
2f1a0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
2f1b0 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  lue_int(sqlite3_
2f1c0 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33  value*);.sqlite3
2f1d0 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76  _int64 sqlite3_v
2f1e0 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74  alue_int64(sqlit
2f1f0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73  e3_value*);.cons
2f200 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20  t unsigned char 
2f210 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
2f220 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ext(sqlite3_valu
2f230 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  e*);.const void 
2f240 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
2f250 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61  ext16(sqlite3_va
2f260 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  lue*);.const voi
2f270 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
2f280 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65  _text16le(sqlite
2f290 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
2f2a0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
2f2b0 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71  alue_text16be(sq
2f2c0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
2f2d0 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
2f2e0 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61  _type(sqlite3_va
2f2f0 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
2f300 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63  e3_value_numeric
2f310 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61  _type(sqlite3_va
2f320 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  lue*);../*.** CA
2f330 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41  PI3REF: Obtain A
2f340 67 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f  ggregate Functio
2f350 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20  n Context.**.** 
2f360 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  Implementations 
2f370 6f 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  of aggregate SQL
2f380 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74   functions use t
2f390 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74  his.** routine t
2f3a0 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
2f3b0 79 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68  y for storing th
2f3c0 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  eir state..**.**
2f3d0 20 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65   ^The first time
2f3e0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67   the sqlite3_agg
2f3f0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
2f400 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63  ,N) routine is c
2f410 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20  alled .** for a 
2f420 70 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65  particular aggre
2f430 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53  gate function, S
2f440 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74  QLite.** allocat
2f450 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20  es N of memory, 
2f460 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20  zeroes out that 
2f470 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75  memory, and retu
2f480 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  rns a pointer.**
2f490 20 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f   to the new memo
2f4a0 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61  ry. ^On second a
2f4b0 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  nd subsequent ca
2f4c0 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  lls to.** sqlite
2f4d0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
2f4e0 65 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 61  ext() for the sa
2f4f0 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  me aggregate fun
2f500 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a  ction instance,.
2f510 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 66  ** the same buff
2f520 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  er is returned. 
2f530 20 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   Sqlite3_aggrega
2f540 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20  te_context() is 
2f550 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c  normally.** call
2f560 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68  ed once for each
2f570 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74   invocation of t
2f580 68 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63  he xStep callbac
2f590 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a  k and then one.*
2f5a0 2a 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e  * last time when
2f5b0 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c   the xFinal call
2f5c0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e  back is invoked.
2f5d0 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73    ^(When no rows
2f5e0 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67   match.** an agg
2f5f0 72 65 67 61 74 65 20 71 75 65 72 79 2c 20 74 68  regate query, th
2f600 65 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61  e xStep() callba
2f610 63 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65 67  ck of the aggreg
2f620 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ate function.** 
2f630 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
2f640 73 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61  s never called a
2f650 6e 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63  nd xFinal() is c
2f660 61 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e  alled exactly on
2f670 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20  ce..** In those 
2f680 63 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61  cases, sqlite3_a
2f690 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
2f6a0 28 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c  () might be call
2f6b0 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69  ed for the.** fi
2f6c0 72 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69  rst time from wi
2f6d0 74 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e  thin xFinal().)^
2f6e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2f6f0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
2f700 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69  ntext(C,N) routi
2f710 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  ne returns a NUL
2f720 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 4e 20 69  L pointer if N i
2f730 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 6f  s.** less than o
2f740 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20  r equal to zero 
2f750 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61  or if a memory a
2f760 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63  llocate error oc
2f770 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  curs..**.** ^(Th
2f780 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63  e amount of spac
2f790 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73  e allocated by s
2f7a0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
2f7b0 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73  _context(C,N) is
2f7c0 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62  .** determined b
2f7d0 79 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65  y the N paramete
2f7e0 72 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65  r on first succe
2f7f0 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61  ssful call.  Cha
2f800 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c  nging the.** val
2f810 75 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65  ue of N in subse
2f820 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71  quent call to sq
2f830 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
2f840 63 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e  context() within
2f850 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67  .** the same agg
2f860 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20  regate function 
2f870 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f  instance will no
2f880 74 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d  t resize the mem
2f890 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f  ory.** allocatio
2f8a0 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  n.)^.**.** ^SQLi
2f8b0 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  te automatically
2f8c0 20 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72   frees the memor
2f8d0 79 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a  y allocated by .
2f8e0 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  ** sqlite3_aggre
2f8f0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77  gate_context() w
2f900 68 65 6e 20 74 68 65 20 61 67 67 72 65 67 61 74  hen the aggregat
2f910 65 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65  e query conclude
2f920 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  s..**.** The fir
2f930 73 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73  st parameter mus
2f940 74 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74  t be a copy of t
2f950 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  he.** [sqlite3_c
2f960 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e  ontext | SQL fun
2f970 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74  ction context] t
2f980 68 61 74 20 69 73 20 74 68 65 20 66 69 72 73 74  hat is the first
2f990 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f   parameter.** to
2f9a0 20 74 68 65 20 78 53 74 65 70 20 6f 72 20 78 46   the xStep or xF
2f9b0 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f  inal callback ro
2f9c0 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65  utine that imple
2f9d0 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 67  ments the aggreg
2f9e0 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e  ate.** function.
2f9f0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
2fa00 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  ine must be call
2fa10 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
2fa20 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
2fa30 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 74  .** the aggregat
2fa40 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  e SQL function i
2fa50 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f  s running..*/.vo
2fa60 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72  id *sqlite3_aggr
2fa70 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71  egate_context(sq
2fa80 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2fa90 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a  int nBytes);../*
2faa0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73  .** CAPI3REF: Us
2fab0 65 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63  er Data For Func
2fac0 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tions.**.** ^The
2fad0 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61   sqlite3_user_da
2fae0 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ta() interface r
2faf0 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
2fb00 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20  .** the pointer 
2fb10 74 68 61 74 20 77 61 73 20 74 68 65 20 70 55 73  that was the pUs
2fb20 65 72 44 61 74 61 20 70 61 72 61 6d 65 74 65 72  erData parameter
2fb30 20 28 74 68 65 20 35 74 68 20 70 61 72 61 6d 65   (the 5th parame
2fb40 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  ter).** of the [
2fb50 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2fb60 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e  unction()].** an
2fb70 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
2fb80 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20  e_function16()] 
2fb90 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72  routines that or
2fba0 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69  iginally.** regi
2fbb0 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69  stered the appli
2fbc0 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66  cation defined f
2fbd0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  unction..**.** T
2fbe0 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74  his routine must
2fbf0 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
2fc00 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
2fc10 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
2fc20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2fc30 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ned function is 
2fc40 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64  running..*/.void
2fc50 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   *sqlite3_user_d
2fc60 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
2fc70 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ext*);../*.** CA
2fc80 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
2fc90 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20   Connection For 
2fca0 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
2fcb0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e  ^The sqlite3_con
2fcc0 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29  text_db_handle()
2fcd0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2fce0 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  ns a copy of.** 
2fcf0 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  the pointer to t
2fd00 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
2fd10 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73  nection] (the 1s
2fd20 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20  t parameter).** 
2fd30 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
2fd40 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2fd50 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
2fd60 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2fd70 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73  on16()] routines
2fd80 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79   that originally
2fd90 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74  .** registered t
2fda0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
2fdb0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
2fdc0 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c  .*/.sqlite3 *sql
2fdd0 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
2fde0 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63  handle(sqlite3_c
2fdf0 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  ontext*);../*.**
2fe00 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74   CAPI3REF: Funct
2fe10 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61  ion Auxiliary Da
2fe20 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c  ta.**.** The fol
2fe30 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e 63 74  lowing two funct
2fe40 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64  ions may be used
2fe50 20 62 79 20 73 63 61 6c 61 72 20 53 51 4c 20 66   by scalar SQL f
2fe60 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61  unctions to.** a
2fe70 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74  ssociate metadat
2fe80 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20  a with argument 
2fe90 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73  values. If the s
2fea0 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61 73  ame value is pas
2feb0 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70  sed to.** multip
2fec0 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  le invocations o
2fed0 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66  f the same SQL f
2fee0 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71  unction during q
2fef0 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20  uery execution, 
2ff00 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69  under.** some ci
2ff10 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20  rcumstances the 
2ff20 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64  associated metad
2ff30 61 74 61 20 6d 61 79 20 62 65 20 70 72 65 73 65  ata may be prese
2ff40 72 76 65 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a  rved. This may.*
2ff50 2a 20 62 65 20 75 73 65 64 2c 20 66 6f 72 20 65  * be used, for e
2ff60 78 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20 61  xample, to add a
2ff70 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73   regular-express
2ff80 69 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73 63 61  ion matching sca
2ff90 6c 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e  lar.** function.
2ffa0 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65   The compiled ve
2ffb0 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67  rsion of the reg
2ffc0 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20  ular expression 
2ffd0 69 73 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20  is stored as.** 
2ffe0 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61  metadata associa
2fff0 74 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c  ted with the SQL
30000 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73   value passed as
30010 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70   the regular exp
30020 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65  ression.** patte
30030 72 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c 65  rn.  The compile
30040 64 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73  d regular expres
30050 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73  sion can be reus
30060 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a  ed on multiple.*
30070 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  * invocations of
30080 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
30090 6f 6e 20 73 6f 20 74 68 61 74 20 74 68 65 20 6f  on so that the o
300a0 72 69 67 69 6e 61 6c 20 70 61 74 74 65 72 6e 20  riginal pattern 
300b0 73 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e  string.** does n
300c0 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 72 65  ot need to be re
300d0 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63 68  compiled on each
300e0 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a   invocation..**.
300f0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
30100 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  get_auxdata() in
30110 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
30120 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
30130 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73   metadata.** ass
30140 6f 63 69 61 74 65 64 20 62 79 20 74 68 65 20 73  ociated by the s
30150 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
30160 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69  ta() function wi
30170 74 68 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d  th the Nth argum
30180 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20  ent.** value to 
30190 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
301a0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
301b0 2e 20 5e 49 66 20 6e 6f 20 6d 65 74 61 64 61 74  . ^If no metadat
301c0 61 20 68 61 73 20 62 65 65 6e 20 65 76 65 72 0a  a has been ever.
301d0 2a 2a 20 62 65 65 6e 20 73 65 74 20 66 6f 72 20  ** been set for 
301e0 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74  the Nth argument
301f0 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
30200 2c 20 6f 72 20 69 66 20 74 68 65 20 63 6f 72 72  , or if the corr
30210 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e  esponding.** fun
30220 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20  ction parameter 
30230 68 61 73 20 63 68 61 6e 67 65 64 20 73 69 6e 63  has changed sinc
30240 65 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20  e the meta-data 
30250 77 61 73 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e  was set,.** then
30260 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
30270 64 61 74 61 28 29 20 72 65 74 75 72 6e 73 20 61  data() returns a
30280 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
30290 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
302a0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
302b0 69 6e 74 65 72 66 61 63 65 20 73 61 76 65 73 20  interface saves 
302c0 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20  the metadata.** 
302d0 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 69 74  pointed to by it
302e0 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  s 3rd parameter 
302f0 61 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  as the metadata 
30300 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20  for the N-th.** 
30310 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20  argument of the 
30320 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
30330 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53  ned function.  S
30340 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c  ubsequent.** cal
30350 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65  ls to sqlite3_ge
30360 74 5f 61 75 78 64 61 74 61 28 29 20 6d 69 67 68  t_auxdata() migh
30370 74 20 72 65 74 75 72 6e 20 74 68 69 73 20 64 61  t return this da
30380 74 61 2c 20 69 66 20 69 74 20 68 61 73 0a 2a 2a  ta, if it has.**
30390 20 6e 6f 74 20 62 65 65 6e 20 64 65 73 74 72 6f   not been destro
303a0 79 65 64 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69  yed..** ^If it i
303b0 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69  s not NULL, SQLi
303c0 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74  te will invoke t
303d0 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a  he destructor.**
303e0 20 66 75 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20   function given 
303f0 62 79 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  by the 4th param
30400 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
30410 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 6f 6e  set_auxdata() on
30420 0a 2a 2a 20 74 68 65 20 6d 65 74 61 64 61 74 61  .** the metadata
30430 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73   when the corres
30440 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e  ponding function
30450 20 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67   parameter chang
30460 65 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68  es.** or when th
30470 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
30480 63 6f 6d 70 6c 65 74 65 73 2c 20 77 68 69 63 68  completes, which
30490 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74  ever comes first
304a0 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ..**.** SQLite i
304b0 73 20 66 72 65 65 20 74 6f 20 63 61 6c 6c 20 74  s free to call t
304c0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 61 6e  he destructor an
304d0 64 20 64 72 6f 70 20 6d 65 74 61 64 61 74 61 20  d drop metadata 
304e0 6f 6e 20 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65  on any.** parame
304f0 74 65 72 20 6f 66 20 61 6e 79 20 66 75 6e 63 74  ter of any funct
30500 69 6f 6e 20 61 74 20 61 6e 79 20 74 69 6d 65 2e  ion at any time.
30510 20 20 5e 54 68 65 20 6f 6e 6c 79 20 67 75 61 72    ^The only guar
30520 61 6e 74 65 65 20 69 73 20 74 68 61 74 0a 2a 2a  antee is that.**
30530 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
30540 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 62  will be called b
30550 65 66 6f 72 65 20 74 68 65 20 6d 65 74 61 64 61  efore the metada
30560 74 61 20 69 73 20 64 72 6f 70 70 65 64 2e 0a 2a  ta is dropped..*
30570 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74 69  *.** ^(In practi
30580 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20  ce, metadata is 
30590 70 72 65 73 65 72 76 65 64 20 62 65 74 77 65 65  preserved betwee
305a0 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73  n function calls
305b0 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73 69   for.** expressi
305c0 6f 6e 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e  ons that are con
305d0 73 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65  stant at compile
305e0 20 74 69 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c   time. This incl
305f0 75 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20  udes literal.** 
30600 76 61 6c 75 65 73 20 61 6e 64 20 5b 70 61 72 61  values and [para
30610 6d 65 74 65 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a 2a  meters].)^.**.**
30620 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
30630 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
30640 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
30650 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
30660 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
30670 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
30680 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65  void *sqlite3_ge
30690 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65  t_auxdata(sqlite
306a0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
306b0 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  N);.void sqlite3
306c0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c  _set_auxdata(sql
306d0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
306e0 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69  nt N, void*, voi
306f0 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a  d (*)(void*));..
30700 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
30710 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e   Constants Defin
30720 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 74  ing Special Dest
30730 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 0a  ructor Behavior.
30740 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20  **.** These are 
30750 73 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66  special values f
30760 6f 72 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  or the destructo
30770 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64  r that is passed
30780 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69   in as the.** fi
30790 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  nal argument to 
307a0 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73  routines like [s
307b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
307c0 6f 62 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 20  ob()].  ^If the 
307d0 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72  destructor.** ar
307e0 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45  gument is SQLITE
307f0 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e  _STATIC, it mean
30800 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65  s that the conte
30810 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f  nt pointer is co
30820 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69  nstant.** and wi
30830 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e  ll never change.
30840 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65    It does not ne
30850 65 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79  ed to be destroy
30860 65 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c  ed.  ^The.** SQL
30870 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61  ITE_TRANSIENT va
30880 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74  lue means that t
30890 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20  he content will 
308a0 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e  likely change in
308b0 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74  .** the near fut
308c0 75 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c  ure and that SQL
308d0 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20  ite should make 
308e0 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
308f0 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63  copy of.** the c
30900 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65  ontent before re
30910 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54  turning..**.** T
30920 68 65 20 74 79 70 65 64 65 66 20 69 73 20 6e 65  he typedef is ne
30930 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20  cessary to work 
30940 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20  around problems 
30950 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b  in certain.** C+
30960 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65  + compilers.  Se
30970 65 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a  e ticket #2191..
30980 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20  */.typedef void 
30990 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  (*sqlite3_destru
309a0 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a  ctor_type)(void*
309b0 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  );.#define SQLIT
309c0 45 5f 53 54 41 54 49 43 20 20 20 20 20 20 28 28  E_STATIC      ((
309d0 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
309e0 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69  or_type)0).#defi
309f0 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  ne SQLITE_TRANSI
30a00 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f  ENT   ((sqlite3_
30a10 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
30a20 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  -1)../*.** CAPI3
30a30 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65  REF: Setting The
30a40 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51   Result Of An SQ
30a50 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a  L Function.**.**
30a60 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
30a70 61 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20  are used by the 
30a80 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20  xFunc or xFinal 
30a90 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a  callbacks that.*
30aa0 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20  * implement SQL 
30ab0 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
30ac0 67 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a  gregates.  See.*
30ad0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  * [sqlite3_creat
30ae0 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e  e_function()] an
30af0 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
30b00 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a  e_function16()].
30b10 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  ** for additiona
30b20 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
30b30 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
30b40 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d  ions work very m
30b50 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61  uch like the [pa
30b60 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d  rameter binding]
30b70 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75   family of.** fu
30b80 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20  nctions used to 
30b90 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68  bind values to h
30ba0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 69  ost parameters i
30bb0 6e 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  n prepared state
30bc0 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20  ments..** Refer 
30bd0 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61  to the [SQL para
30be0 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61  meter] documenta
30bf0 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f  tion for additio
30c00 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
30c10 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
30c20 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
30c30 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
30c40 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
30c50 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69  .** an applicati
30c60 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
30c70 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c  ion to be the BL
30c80 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74  OB whose content
30c90 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74   is pointed.** t
30ca0 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  o by the second 
30cb0 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68  parameter and wh
30cc0 69 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c  ich is N bytes l
30cd0 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 74  ong where N is t
30ce0 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61  he.** third para
30cf0 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  meter..**.** ^Th
30d00 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
30d10 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65  _zeroblob() inte
30d20 72 66 61 63 65 73 20 73 65 74 20 74 68 65 20 72  rfaces set the r
30d30 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20  esult of.** the 
30d40 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
30d50 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
30d60 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69  be a BLOB contai
30d70 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a  ning all zero.**
30d80 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74   bytes and N byt
30d90 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72  es in size, wher
30da0 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65  e N is the value
30db0 20 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72 61   of the 2nd para
30dc0 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  meter..**.** ^Th
30dd0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
30de0 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66  _double() interf
30df0 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
30e00 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61  ult from.** an a
30e10 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
30e20 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
30e30 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  e a floating poi
30e40 6e 74 20 76 61 6c 75 65 20 73 70 65 63 69 66 69  nt value specifi
30e50 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64  ed.** by its 2nd
30e60 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
30e70 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
30e80 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64  sult_error() and
30e90 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
30ea0 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69  error16() functi
30eb0 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65  ons.** cause the
30ec0 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c   implemented SQL
30ed0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72   function to thr
30ee0 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e  ow an exception.
30ef0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73  .** ^SQLite uses
30f00 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e   the string poin
30f10 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a  ted to by the.**
30f20 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
30f30 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  f sqlite3_result
30f40 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69  _error() or sqli
30f50 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
30f60 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74  16().** as the t
30f70 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20  ext of an error 
30f80 6d 65 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74  message.  ^SQLit
30f90 65 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65  e interprets the
30fa0 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67   error.** messag
30fb0 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71  e string from sq
30fc0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
30fd0 6f 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e  or() as UTF-8. ^
30fe0 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70  SQLite.** interp
30ff0 72 65 74 73 20 74 68 65 20 73 74 72 69 6e 67 20  rets the string 
31000 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73  from sqlite3_res
31010 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73  ult_error16() as
31020 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76   UTF-16 in nativ
31030 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e  e.** byte order.
31040 20 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20    ^If the third 
31050 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
31060 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
31070 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  r().** or sqlite
31080 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
31090 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 20 74  () is negative t
310a0 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73  hen SQLite takes
310b0 20 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a   as the error.**
310c0 20 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78   message all tex
310d0 74 20 75 70 20 74 68 72 6f 75 67 68 20 74 68 65  t up through the
310e0 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72   first zero char
310f0 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68  acter..** ^If th
31100 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
31110 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  r to sqlite3_res
31120 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a  ult_error() or.*
31130 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
31140 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f  _error16() is no
31150 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  n-negative then 
31160 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61  SQLite takes tha
31170 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20  t many.** bytes 
31180 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29  (not characters)
31190 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61   from the 2nd pa
311a0 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 65  rameter as the e
311b0 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
311c0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
311d0 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64  sult_error() and
311e0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
311f0 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75  error16().** rou
31200 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69  tines make a pri
31210 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65  vate copy of the
31220 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74   error message t
31230 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68  ext before.** th
31240 65 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63  ey return.  Henc
31250 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66  e, the calling f
31260 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c  unction can deal
31270 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64  locate or.** mod
31280 69 66 79 20 74 68 65 20 74 65 78 74 20 61 66 74  ify the text aft
31290 65 72 20 74 68 65 79 20 72 65 74 75 72 6e 20 77  er they return w
312a0 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20  ithout harm..** 
312b0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
312c0 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29  ult_error_code()
312d0 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65   function change
312e0 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  s the error code
312f0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20  .** returned by 
31300 53 51 4c 69 74 65 20 61 73 20 61 20 72 65 73 75  SQLite as a resu
31310 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69  lt of an error i
31320 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e  n a function.  ^
31330 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74  By default,.** t
31340 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73  he error code is
31350 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20   SQLITE_ERROR.  
31360 5e 41 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  ^A subsequent ca
31370 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  ll to sqlite3_re
31380 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20  sult_error().** 
31390 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
313a0 74 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73 65  t_error16() rese
313b0 74 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  ts the error cod
313c0 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f  e to SQLITE_ERRO
313d0 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  R..**.** ^The sq
313e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f  lite3_result_too
313f0 62 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  big() interface 
31400 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f  causes SQLite to
31410 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a   throw an error.
31420 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  ** indicating th
31430 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42  at a string or B
31440 4c 4f 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20  LOB is too long 
31450 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a  to represent..**
31460 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
31470 5f 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20  _result_nomem() 
31480 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
31490 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77   SQLite to throw
314a0 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64   an error.** ind
314b0 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d  icating that a m
314c0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
314d0 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e   failed..**.** ^
314e0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
314f0 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61  lt_int() interfa
31500 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
31510 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
31520 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
31530 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
31540 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74  to be the 32-bit
31550 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
31560 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69  ** value given i
31570 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65  n the 2nd argume
31580 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  nt..** ^The sqli
31590 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34  te3_result_int64
315a0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
315b0 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
315c0 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
315d0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
315e0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
315f0 74 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65  the 64-bit signe
31600 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c  d integer.** val
31610 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20  ue given in the 
31620 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
31630 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
31640 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69  _result_null() i
31650 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
31660 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
31670 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
31680 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
31690 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c  ction to be NULL
316a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
316b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
316c0 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75  (), sqlite3_resu
316d0 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20  lt_text16(),.** 
316e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
316f0 65 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73  ext16le(), and s
31700 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
31710 78 74 31 36 62 65 28 29 20 69 6e 74 65 72 66 61  xt16be() interfa
31720 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72  ces.** set the r
31730 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
31740 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
31750 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
31760 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20  to be.** a text 
31770 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 20  string which is 
31780 72 65 70 72 65 73 65 6e 74 65 64 20 61 73 20 55  represented as U
31790 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74  TF-8, UTF-16 nat
317a0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a  ive byte order,.
317b0 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65  ** UTF-16 little
317c0 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d   endian, or UTF-
317d0 31 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72  16 big endian, r
317e0 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
317f0 5e 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68  ^SQLite takes th
31800 65 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 72  e text result fr
31810 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  om the applicati
31820 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32  on from.** the 2
31830 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  nd parameter of 
31840 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
31850 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
31860 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ces..** ^If the 
31870 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
31880 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
31890 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
318a0 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74  aces.** is negat
318b0 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ive, then SQLite
318c0 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65   takes result te
318d0 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20  xt from the 2nd 
318e0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72  parameter.** thr
318f0 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a  ough the first z
31900 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ero character..*
31910 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61  * ^If the 3rd pa
31920 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
31930 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
31940 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
31950 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  * is non-negativ
31960 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20  e, then as many 
31970 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61  bytes (not chara
31980 63 74 65 72 73 29 20 6f 66 20 74 68 65 20 74 65  cters) of the te
31990 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f  xt.** pointed to
319a0 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61   by the 2nd para
319b0 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20  meter are taken 
319c0 61 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  as the applicati
319d0 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75  on-defined.** fu
319e0 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 20 20  nction result.  
319f0 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
31a00 65 74 65 72 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  eter is non-nega
31a10 74 69 76 65 2c 20 74 68 65 6e 20 69 74 0a 2a 2a  tive, then it.**
31a20 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74   must be the byt
31a30 65 20 6f 66 66 73 65 74 20 69 6e 74 6f 20 74 68  e offset into th
31a40 65 20 73 74 72 69 6e 67 20 77 68 65 72 65 20 74  e string where t
31a50 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f  he NUL terminato
31a60 72 20 77 6f 75 6c 64 0a 2a 2a 20 61 70 70 65 61  r would.** appea
31a70 72 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 20  r if the string 
31a80 77 68 65 72 65 20 4e 55 4c 20 74 65 72 6d 69 6e  where NUL termin
31a90 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55  ated.  If any NU
31aa0 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 63  L characters occ
31ab0 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 73 74 72  ur.** in the str
31ac0 69 6e 67 20 61 74 20 61 20 62 79 74 65 20 6f 66  ing at a byte of
31ad0 66 73 65 74 20 74 68 61 74 20 69 73 20 6c 65 73  fset that is les
31ae0 73 20 74 68 61 6e 20 74 68 65 20 76 61 6c 75 65  s than the value
31af0 20 6f 66 20 74 68 65 20 33 72 64 0a 2a 2a 20 70   of the 3rd.** p
31b00 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74  arameter, then t
31b10 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72  he resulting str
31b20 69 6e 67 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e  ing will contain
31b30 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 61   embedded NULs a
31b40 6e 64 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  nd the.** result
31b50 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20   of expressions 
31b60 6f 70 65 72 61 74 69 6e 67 20 6f 6e 20 73 74 72  operating on str
31b70 69 6e 67 73 20 77 69 74 68 20 65 6d 62 65 64 64  ings with embedd
31b80 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66  ed NULs is undef
31b90 69 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ined..** ^If the
31ba0 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
31bb0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
31bc0 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
31bd0 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69  faces.** or sqli
31be0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
31bf0 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  is a non-NULL po
31c00 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69  inter, then SQLi
31c10 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a  te calls that.**
31c20 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65   function as the
31c30 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74   destructor on t
31c40 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20  he text or BLOB 
31c50 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68  result when it h
31c60 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75  as.** finished u
31c70 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74  sing that result
31c80 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68  ..** ^If the 4th
31c90 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
31ca0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
31cb0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
31cc0 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  s or to.** sqlit
31cd0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69  e3_result_blob i
31ce0 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f  s the special co
31cf0 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54  nstant SQLITE_ST
31d00 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74  ATIC, then SQLit
31d10 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61  e.** assumes tha
31d20 74 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c  t the text or BL
31d30 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20  OB result is in 
31d40 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61  constant space a
31d50 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63  nd does not.** c
31d60 6f 70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  opy the content 
31d70 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  of the parameter
31d80 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74   nor call a dest
31d90 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f  ructor on the co
31da0 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74  ntent.** when it
31db0 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73   has finished us
31dc0 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e  ing that result.
31dd0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20  .** ^If the 4th 
31de0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
31df0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
31e00 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
31e10 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
31e20 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68  esult_blob is th
31e30 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61  e special consta
31e40 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  nt SQLITE_TRANSI
31e50 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69  ENT.** then SQLi
31e60 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  te makes a copy 
31e70 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e  of the result in
31e80 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65  to space obtaine
31e90 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b  d from.** from [
31ea0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
31eb0 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 75  ] before it retu
31ec0 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rns..**.** ^The 
31ed0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
31ee0 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65  alue() interface
31ef0 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74   sets the result
31f00 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
31f10 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
31f20 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
31f30 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70  copy the.** [unp
31f40 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
31f50 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73  _value] object s
31f60 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
31f70 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  2nd parameter.  
31f80 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ^The.** sqlite3_
31f90 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69  result_value() i
31fa0 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61  nterface makes a
31fb0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71   copy of the [sq
31fc0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20  lite3_value].** 
31fd0 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c  so that the [sql
31fe0 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63  ite3_value] spec
31ff0 69 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 72  ified in the par
32000 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67  ameter may chang
32010 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c  e or.** be deall
32020 6f 63 61 74 65 64 20 61 66 74 65 72 20 73 71 6c  ocated after sql
32030 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
32040 65 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 68  e() returns with
32050 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20  out harm..** ^A 
32060 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
32070 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
32080 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 75   may always be u
32090 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20  sed where an.** 
320a0 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
320b0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
320c0 63 74 20 69 73 20 72 65 71 75 69 72 65 64 2c 20  ct is required, 
320d0 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e  so either.** kin
320e0 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61  d of [sqlite3_va
320f0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20  lue] object can 
32100 62 65 20 75 73 65 64 20 77 69 74 68 20 74 68 69  be used with thi
32110 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  s interface..**.
32120 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 74  ** If these rout
32130 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
32140 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20  from within the 
32150 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
32160 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65  .** than the one
32170 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
32180 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
32190 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  ned function tha
321a0 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68  t received.** th
321b0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  e [sqlite3_conte
321c0 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  xt] pointer, the
321d0 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
321e0 65 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20  efined..*/.void 
321f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
32200 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lob(sqlite3_cont
32210 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
32220 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
32230 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
32240 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75  lite3_result_dou
32250 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ble(sqlite3_cont
32260 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76  ext*, double);.v
32270 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
32280 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33  lt_error(sqlite3
32290 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
322a0 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f   char*, int);.vo
322b0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
322c0 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65  t_error16(sqlite
322d0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
322e0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76  t void*, int);.v
322f0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
32300 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28  lt_error_toobig(
32310 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
32320 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
32330 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d  result_error_nom
32340 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  em(sqlite3_conte
32350 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  xt*);.void sqlit
32360 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
32370 63 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  code(sqlite3_con
32380 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  text*, int);.voi
32390 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
323a0 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  _int(sqlite3_con
323b0 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  text*, int);.voi
323c0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
323d0 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63  _int64(sqlite3_c
323e0 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33  ontext*, sqlite3
323f0 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71  _int64);.void sq
32400 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c  lite3_result_nul
32410 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  l(sqlite3_contex
32420 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  t*);.void sqlite
32430 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71  3_result_text(sq
32440 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
32450 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
32460 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
32470 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
32480 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71  result_text16(sq
32490 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
324a0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
324b0 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
324c0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
324d0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28  result_text16le(
324e0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
324f0 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
32500 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  nt,void(*)(void*
32510 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
32520 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65  _result_text16be
32530 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
32540 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
32550 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64  int,void(*)(void
32560 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
32570 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73  3_result_value(s
32580 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
32590 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29   sqlite3_value*)
325a0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
325b0 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73  esult_zeroblob(s
325c0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
325d0 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20   int n);../*.** 
325e0 43 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65  CAPI3REF: Define
325f0 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53   New Collating S
32600 65 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e  equences.**.** ^
32610 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
32620 61 64 64 2c 20 72 65 6d 6f 76 65 2c 20 6f 72 20  add, remove, or 
32630 6d 6f 64 69 66 79 20 61 20 5b 63 6f 6c 6c 61 74  modify a [collat
32640 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 0a  ion] associated.
32650 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ** with the [dat
32660 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
32670 5d 20 73 70 65 63 69 66 69 65 64 20 61 73 20 74  ] specified as t
32680 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
32690 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61  t..**.** ^The na
326a0 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74  me of the collat
326b0 69 6f 6e 20 69 73 20 61 20 55 54 46 2d 38 20 73  ion is a UTF-8 s
326c0 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c  tring.** for sql
326d0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
326e0 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69  ation() and sqli
326f0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
32700 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64  tion_v2().** and
32710 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
32720 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20   in native byte 
32730 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65  order for sqlite
32740 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
32750 6f 6e 31 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c  on16()..** ^Coll
32760 61 74 69 6f 6e 20 6e 61 6d 65 73 20 74 68 61 74  ation names that
32770 20 63 6f 6d 70 61 72 65 20 65 71 75 61 6c 20 61   compare equal a
32780 63 63 6f 72 64 69 6e 67 20 74 6f 20 5b 73 71 6c  ccording to [sql
32790 69 74 65 33 5f 73 74 72 6e 69 63 6d 70 28 29 5d  ite3_strnicmp()]
327a0 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72   are.** consider
327b0 65 64 20 74 6f 20 62 65 20 74 68 65 20 73 61 6d  ed to be the sam
327c0 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28  e name..**.** ^(
327d0 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
327e0 6e 74 20 28 65 54 65 78 74 52 65 70 29 20 6d 75  nt (eTextRep) mu
327f0 73 74 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65  st be one of the
32800 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c   constants:.** <
32810 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
32820 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c  ITE_UTF8],.** <l
32830 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  i> [SQLITE_UTF16
32840 4c 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  LE],.** <li> [SQ
32850 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a  LITE_UTF16BE],.*
32860 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55  * <li> [SQLITE_U
32870 54 46 31 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69  TF16], or.** <li
32880 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  > [SQLITE_UTF16_
32890 41 4c 49 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75  ALIGNED]..** </u
328a0 6c 3e 29 5e 0a 2a 2a 20 5e 54 68 65 20 65 54 65  l>)^.** ^The eTe
328b0 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74 20 64  xtRep argument d
328c0 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20 65 6e  etermines the en
328d0 63 6f 64 69 6e 67 20 6f 66 20 73 74 72 69 6e 67  coding of string
328e0 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 6f 20 74  s passed.** to t
328f0 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
32900 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c 20  ction callback, 
32910 78 43 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54  xCallback..** ^T
32920 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  he [SQLITE_UTF16
32930 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 55 54  ] and [SQLITE_UT
32940 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c  F16_ALIGNED] val
32950 75 65 73 20 66 6f 72 20 65 54 65 78 74 52 65 70  ues for eTextRep
32960 0a 2a 2a 20 66 6f 72 63 65 20 73 74 72 69 6e 67  .** force string
32970 73 20 74 6f 20 62 65 20 55 54 46 31 36 20 77 69  s to be UTF16 wi
32980 74 68 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  th native byte o
32990 72 64 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53  rder..** ^The [S
329a0 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
329b0 4e 45 44 5d 20 76 61 6c 75 65 20 66 6f 72 20 65  NED] value for e
329c0 54 65 78 74 52 65 70 20 66 6f 72 63 65 73 20 73  TextRep forces s
329d0 74 72 69 6e 67 73 20 74 6f 20 62 65 67 69 6e 0a  trings to begin.
329e0 2a 2a 20 6f 6e 20 61 6e 20 65 76 65 6e 20 62 79  ** on an even by
329f0 74 65 20 61 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a  te address..**.*
32a00 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 61 72  * ^The fourth ar
32a10 67 75 6d 65 6e 74 2c 20 70 41 72 67 2c 20 69 73  gument, pArg, is
32a20 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
32a30 64 61 74 61 20 70 6f 69 6e 74 65 72 20 74 68 61  data pointer tha
32a40 74 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 74  t is passed.** t
32a50 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69  hrough as the fi
32a60 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
32a70 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  the collating fu
32a80 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e  nction callback.
32a90 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74  .**.** ^The fift
32aa0 68 20 61 72 67 75 6d 65 6e 74 2c 20 78 43 61 6c  h argument, xCal
32ab0 6c 62 61 63 6b 2c 20 69 73 20 61 20 70 6f 69 6e  lback, is a poin
32ac0 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61  ter to the colla
32ad0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ting function..*
32ae0 2a 20 5e 4d 75 6c 74 69 70 6c 65 20 63 6f 6c 6c  * ^Multiple coll
32af0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20  ating functions 
32b00 63 61 6e 20 62 65 20 72 65 67 69 73 74 65 72 65  can be registere
32b10 64 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65  d using the same
32b20 20 6e 61 6d 65 20 62 75 74 0a 2a 2a 20 77 69 74   name but.** wit
32b30 68 20 64 69 66 66 65 72 65 6e 74 20 65 54 65 78  h different eTex
32b40 74 52 65 70 20 70 61 72 61 6d 65 74 65 72 73 20  tRep parameters 
32b50 61 6e 64 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  and SQLite will 
32b60 75 73 65 20 77 68 69 63 68 65 76 65 72 0a 2a 2a  use whichever.**
32b70 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
32b80 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f  es the least amo
32b90 75 6e 74 20 6f 66 20 64 61 74 61 20 74 72 61 6e  unt of data tran
32ba0 73 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e  sformation..** ^
32bb0 49 66 20 74 68 65 20 78 43 61 6c 6c 62 61 63 6b  If the xCallback
32bc0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 4e 55 4c   argument is NUL
32bd0 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61  L then the colla
32be0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73  ting function is
32bf0 0a 2a 2a 20 64 65 6c 65 74 65 64 2e 20 20 5e 57  .** deleted.  ^W
32c00 68 65 6e 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e  hen all collatin
32c10 67 20 66 75 6e 63 74 69 6f 6e 73 20 68 61 76 69  g functions havi
32c20 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  ng the same name
32c30 20 61 72 65 20 64 65 6c 65 74 65 64 2c 0a 2a 2a   are deleted,.**
32c40 20 74 68 61 74 20 63 6f 6c 6c 61 74 69 6f 6e 20   that collation 
32c50 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 75 73 61  is no longer usa
32c60 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ble..**.** ^The 
32c70 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
32c80 6f 6e 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  on callback is i
32c90 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 63 6f  nvoked with a co
32ca0 70 79 20 6f 66 20 74 68 65 20 70 41 72 67 20 0a  py of the pArg .
32cb0 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  ** application d
32cc0 61 74 61 20 70 6f 69 6e 74 65 72 20 61 6e 64 20  ata pointer and 
32cd0 77 69 74 68 20 74 77 6f 20 73 74 72 69 6e 67 73  with two strings
32ce0 20 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67   in the encoding
32cf0 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79   specified.** by
32d00 20 74 68 65 20 65 54 65 78 74 52 65 70 20 61 72   the eTextRep ar
32d10 67 75 6d 65 6e 74 2e 20 20 54 68 65 20 63 6f 6c  gument.  The col
32d20 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
32d30 6d 75 73 74 20 72 65 74 75 72 6e 20 61 6e 0a 2a  must return an.*
32d40 2a 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 69  * integer that i
32d50 73 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f  s negative, zero
32d60 2c 20 6f 72 20 70 6f 73 69 74 69 76 65 0a 2a 2a  , or positive.**
32d70 20 69 66 20 74 68 65 20 66 69 72 73 74 20 73 74   if the first st
32d80 72 69 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61  ring is less tha
32d90 6e 2c 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20  n, equal to, or 
32da0 67 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 65  greater than the
32db0 20 73 65 63 6f 6e 64 2c 0a 2a 2a 20 72 65 73 70   second,.** resp
32dc0 65 63 74 69 76 65 6c 79 2e 20 20 41 20 63 6f 6c  ectively.  A col
32dd0 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
32de0 6d 75 73 74 20 61 6c 77 61 79 73 20 72 65 74 75  must always retu
32df0 72 6e 20 74 68 65 20 73 61 6d 65 20 61 6e 73 77  rn the same answ
32e00 65 72 0a 2a 2a 20 67 69 76 65 6e 20 74 68 65 20  er.** given the 
32e10 73 61 6d 65 20 69 6e 70 75 74 73 2e 20 20 49 66  same inputs.  If
32e20 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 63 6f 6c   two or more col
32e30 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73  lating functions
32e40 20 61 72 65 20 72 65 67 69 73 74 65 72 65 64 0a   are registered.
32e50 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 63  ** to the same c
32e60 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 28 75  ollation name (u
32e70 73 69 6e 67 20 64 69 66 66 65 72 65 6e 74 20 65  sing different e
32e80 54 65 78 74 52 65 70 20 76 61 6c 75 65 73 29 20  TextRep values) 
32e90 74 68 65 6e 20 61 6c 6c 0a 2a 2a 20 6d 75 73 74  then all.** must
32ea0 20 67 69 76 65 20 61 6e 20 65 71 75 69 76 61 6c   give an equival
32eb0 65 6e 74 20 61 6e 73 77 65 72 20 77 68 65 6e 20  ent answer when 
32ec0 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 65 71 75  invoked with equ
32ed0 69 76 61 6c 65 6e 74 20 73 74 72 69 6e 67 73 2e  ivalent strings.
32ee0 0a 2a 2a 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e  .** The collatin
32ef0 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  g function must 
32f00 6f 62 65 79 20 74 68 65 20 66 6f 6c 6c 6f 77 69  obey the followi
32f10 6e 67 20 70 72 6f 70 65 72 74 69 65 73 20 66 6f  ng properties fo
32f20 72 20 61 6c 6c 0a 2a 2a 20 73 74 72 69 6e 67 73  r all.** strings
32f30 20 41 2c 20 42 2c 20 61 6e 64 20 43 3a 0a 2a 2a   A, B, and C:.**
32f40 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
32f50 20 49 66 20 41 3d 3d 42 20 74 68 65 6e 20 42 3d   If A==B then B=
32f60 3d 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41  =A..** <li> If A
32f70 3d 3d 42 20 61 6e 64 20 42 3d 3d 43 20 74 68 65  ==B and B==C the
32f80 6e 20 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e 20  n A==C..** <li> 
32f90 49 66 20 41 26 6c 74 3b 42 20 54 48 45 4e 20 42  If A&lt;B THEN B
32fa0 26 67 74 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49  &gt;A..** <li> I
32fb0 66 20 41 26 6c 74 3b 42 20 61 6e 64 20 42 26 6c  f A&lt;B and B&l
32fc0 74 3b 43 20 74 68 65 6e 20 41 26 6c 74 3b 43 2e  t;C then A&lt;C.
32fd0 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ol>.**.** 
32fe0 49 66 20 61 20 63 6f 6c 6c 61 74 69 6e 67 20 66  If a collating f
32ff0 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 20 61 6e  unction fails an
33000 79 20 6f 66 20 74 68 65 20 61 62 6f 76 65 20 63  y of the above c
33010 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e 64 20 74  onstraints and t
33020 68 61 74 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6e 67  hat.** collating
33030 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 20 72 65   function is  re
33040 67 69 73 74 65 72 65 64 20 61 6e 64 20 75 73 65  gistered and use
33050 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  d, then the beha
33060 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a  vior of SQLite.*
33070 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  * is undefined..
33080 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
33090 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
330a0 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c  ion_v2() works l
330b0 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  ike sqlite3_crea
330c0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a  te_collation().*
330d0 2a 20 77 69 74 68 20 74 68 65 20 61 64 64 69 74  * with the addit
330e0 69 6f 6e 20 74 68 61 74 20 74 68 65 20 78 44 65  ion that the xDe
330f0 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69  stroy callback i
33100 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 70 41 72  s invoked on pAr
33110 67 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f  g when.** the co
33120 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
33130 20 69 73 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20   is deleted..** 
33140 5e 43 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74  ^Collating funct
33150 69 6f 6e 73 20 61 72 65 20 64 65 6c 65 74 65 64  ions are deleted
33160 20 77 68 65 6e 20 74 68 65 79 20 61 72 65 20 6f   when they are o
33170 76 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74  verridden by lat
33180 65 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 74  er.** calls to t
33190 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65  he collation cre
331a0 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20  ation functions 
331b0 6f 72 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  or when the.** [
331c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
331d0 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64 20 75  ion] is closed u
331e0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c  sing [sqlite3_cl
331f0 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ose()]..**.** ^T
33200 68 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c 6c  he xDestroy call
33210 62 61 63 6b 20 69 73 20 3c 75 3e 6e 6f 74 3c 2f  back is <u>not</
33220 75 3e 20 63 61 6c 6c 65 64 20 69 66 20 74 68 65  u> called if the
33230 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65   .** sqlite3_cre
33240 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
33250 28 29 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c  () function fail
33260 73 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  s.  Applications
33270 20 74 68 61 74 20 69 6e 76 6f 6b 65 0a 2a 2a 20   that invoke.** 
33280 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
33290 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 69  ollation_v2() wi
332a0 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 44  th a non-NULL xD
332b0 65 73 74 72 6f 79 20 61 72 67 75 6d 65 6e 74 20  estroy argument 
332c0 73 68 6f 75 6c 64 20 0a 2a 2a 20 63 68 65 63 6b  should .** check
332d0 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65   the return code
332e0 20 61 6e 64 20 64 69 73 70 6f 73 65 20 6f 66 20   and dispose of 
332f0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
33300 64 61 74 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  data pointer.** 
33310 74 68 65 6d 73 65 6c 76 65 73 20 72 61 74 68 65  themselves rathe
33320 72 20 74 68 61 6e 20 65 78 70 65 63 74 69 6e 67  r than expecting
33330 20 53 51 4c 69 74 65 20 74 6f 20 64 65 61 6c 20   SQLite to deal 
33340 77 69 74 68 20 69 74 20 66 6f 72 20 74 68 65 6d  with it for them
33350 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 64 69 66  ..** This is dif
33360 66 65 72 65 6e 74 20 66 72 6f 6d 20 65 76 65 72  ferent from ever
33370 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
33380 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 69  nterface.  The i
33390 6e 63 6f 6e 73 69 73 74 65 6e 63 79 20 0a 2a 2a  nconsistency .**
333a0 20 69 73 20 75 6e 66 6f 72 74 75 6e 61 74 65 20   is unfortunate 
333b0 62 75 74 20 63 61 6e 6e 6f 74 20 62 65 20 63 68  but cannot be ch
333c0 61 6e 67 65 64 20 77 69 74 68 6f 75 74 20 62 72  anged without br
333d0 65 61 6b 69 6e 67 20 62 61 63 6b 77 61 72 64 73  eaking backwards
333e0 20 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69   .** compatibili
333f0 74 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ty..**.** See al
33400 73 6f 3a 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f  so:  [sqlite3_co
33410 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29  llation_needed()
33420 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
33430 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
33440 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  6()]..*/.int sql
33450 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
33460 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33  ation(.  sqlite3
33470 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  *, .  const char
33480 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20   *zName, .  int 
33490 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69  eTextRep, .  voi
334a0 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a  d *pArg,.  int(*
334b0 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c  xCompare)(void*,
334c0 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  int,const void*,
334d0 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  int,const void*)
334e0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
334f0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
33500 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  _v2(.  sqlite3*,
33510 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a   .  const char *
33520 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54  zName, .  int eT
33530 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20  extRep, .  void 
33540 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43  *pArg,.  int(*xC
33550 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e  ompare)(void*,in
33560 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e  t,const void*,in
33570 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a  t,const void*),.
33580 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79    void(*xDestroy
33590 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20  )(void*).);.int 
335a0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
335b0 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73 71  ollation16(.  sq
335c0 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74  lite3*, .  const
335d0 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20   void *zName,.  
335e0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20  int eTextRep, . 
335f0 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69   void *pArg,.  i
33600 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f  nt(*xCompare)(vo
33610 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
33620 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
33630 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  id*).);../*.** C
33640 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69  API3REF: Collati
33650 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61  on Needed Callba
33660 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76  cks.**.** ^To av
33670 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72 65  oid having to re
33680 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61  gister all colla
33690 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 62  tion sequences b
336a0 65 66 6f 72 65 20 61 20 64 61 74 61 62 61 73 65  efore a database
336b0 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c  .** can be used,
336c0 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61   a single callba
336d0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20  ck function may 
336e0 62 65 20 72 65 67 69 73 74 65 72 65 64 20 77 69  be registered wi
336f0 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62  th the.** [datab
33700 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
33710 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68  to be invoked wh
33720 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69  enever an undefi
33730 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a  ned collation.**
33740 20 73 65 71 75 65 6e 63 65 20 69 73 20 72 65 71   sequence is req
33750 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  uired..**.** ^If
33760 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73   the function is
33770 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e   registered usin
33780 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  g the sqlite3_co
33790 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29  llation_needed()
337a0 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74   API,.** then it
337b0 20 69 73 20 70 61 73 73 65 64 20 74 68 65 20 6e   is passed the n
337c0 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e 65  ames of undefine
337d0 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  d collation sequ
337e0 65 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67 73  ences as strings
337f0 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 55  .** encoded in U
33800 54 46 2d 38 2e 20 5e 49 66 20 73 71 6c 69 74 65  TF-8. ^If sqlite
33810 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
33820 65 64 31 36 28 29 20 69 73 20 75 73 65 64 2c 0a  ed16() is used,.
33830 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20 61 72 65  ** the names are
33840 20 70 61 73 73 65 64 20 61 73 20 55 54 46 2d 31   passed as UTF-1
33850 36 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74  6 in machine nat
33860 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
33870 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 65 69  ** ^A call to ei
33880 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 72 65  ther function re
33890 70 6c 61 63 65 73 20 74 68 65 20 65 78 69 73 74  places the exist
338a0 69 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65  ing collation-ne
338b0 65 64 65 64 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  eded callback..*
338c0 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20 74 68 65 20  *.** ^(When the 
338d0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
338e0 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74 20 61  ked, the first a
338f0 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69  rgument passed i
33900 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74  s a copy.** of t
33910 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
33920 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  nt to sqlite3_co
33930 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29  llation_needed()
33940 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   or.** sqlite3_c
33950 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
33960 36 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  6().  The second
33970 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
33980 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
33990 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 74 68  nection.  The th
339a0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
339b0 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55  one of [SQLITE_U
339c0 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54  TF8], [SQLITE_UT
339d0 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53  F16BE],.** or [S
339e0 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20  QLITE_UTF16LE], 
339f0 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d  indicating the m
33a00 6f 73 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f  ost desirable fo
33a10 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74  rm of the collat
33a20 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20  ion.** sequence 
33a30 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
33a40 64 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70  d.  The fourth p
33a50 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
33a60 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72  name of the.** r
33a70 65 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f  equired collatio
33a80 6e 20 73 65 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a  n sequence.)^.**
33a90 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  .** The callback
33aa0 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64   function should
33ab0 20 72 65 67 69 73 74 65 72 20 74 68 65 20 64 65   register the de
33ac0 73 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  sired collation 
33ad0 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
33ae0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
33af0 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  on()], [sqlite3_
33b00 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
33b10 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  16()], or.** [sq
33b20 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
33b30 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f  lation_v2()]..*/
33b40 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
33b50 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20  lation_needed(. 
33b60 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f   sqlite3*, .  vo
33b70 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28  id*, .  void(*)(
33b80 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69  void*,sqlite3*,i
33b90 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73  nt eTextRep,cons
33ba0 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20  t char*).);.int 
33bb0 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
33bc0 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20 20 73 71  n_needed16(.  sq
33bd0 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a  lite3*, .  void*
33be0 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  ,.  void(*)(void
33bf0 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65  *,sqlite3*,int e
33c00 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f  TextRep,const vo
33c10 69 64 2a 29 0a 29 3b 0a 0a 23 69 66 64 65 66 20  id*).);..#ifdef 
33c20 53 51 4c 49 54 45 5f 48 41 53 5f 43 4f 44 45 43  SQLITE_HAS_CODEC
33c30 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74  ./*.** Specify t
33c40 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e  he key for an en
33c50 63 72 79 70 74 65 64 20 64 61 74 61 62 61 73 65  crypted database
33c60 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  .  This routine 
33c70 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c  should be.** cal
33c80 6c 65 64 20 72 69 67 68 74 20 61 66 74 65 72 20  led right after 
33c90 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a  sqlite3_open()..
33ca0 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74  **.** The code t
33cb0 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73  o implement this
33cc0 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69   API is not avai
33cd0 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62  lable in the pub
33ce0 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f  lic release.** o
33cf0 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74  f SQLite..*/.int
33d00 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20   sqlite3_key(.  
33d10 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
33d20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
33d30 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65  * Database to be
33d40 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f   rekeyed */.  co
33d50 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20  nst void *pKey, 
33d60 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20  int nKey     /* 
33d70 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f  The key */.);../
33d80 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20  *.** Change the 
33d90 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64  key on an open d
33da0 61 74 61 62 61 73 65 2e 20 20 49 66 20 74 68 65  atabase.  If the
33db0 20 63 75 72 72 65 6e 74 20 64 61 74 61 62 61 73   current databas
33dc0 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72  e is not.** encr
33dd0 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74  ypted, this rout
33de0 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74  ine will encrypt
33df0 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30   it.  If pNew==0
33e00 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65   or nNew==0, the
33e10 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73 20  .** database is 
33e20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a  decrypted..**.**
33e30 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70   The code to imp
33e40 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20  lement this API 
33e50 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65  is not available
33e60 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72   in the public r
33e70 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c  elease.** of SQL
33e80 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ite..*/.int sqli
33e90 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c  te3_rekey(.  sql
33ea0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
33eb0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
33ec0 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65  atabase to be re
33ed0 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74  keyed */.  const
33ee0 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74   void *pKey, int
33ef0 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65   nKey     /* The
33f00 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a   new key */.);..
33f10 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68  /*.** Specify th
33f20 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 79  e activation key
33f30 20 66 6f 72 20 61 20 53 45 45 20 64 61 74 61 62   for a SEE datab
33f40 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a  ase.  Unless .**
33f50 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65   activated, none
33f60 20 6f 66 20 74 68 65 20 53 45 45 20 72 6f 75 74   of the SEE rout
33f70 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a  ines will work..
33f80 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
33f90 61 63 74 69 76 61 74 65 5f 73 65 65 28 0a 20 20  activate_see(.  
33fa0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 73  const char *zPas
33fb0 73 50 68 72 61 73 65 20 20 20 20 20 20 20 20 2f  sPhrase        /
33fc0 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68 72  * Activation phr
33fd0 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66  ase */.);.#endif
33fe0 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  ..#ifdef SQLITE_
33ff0 45 4e 41 42 4c 45 5f 43 45 52 4f 44 0a 2f 2a 0a  ENABLE_CEROD./*.
34000 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 61  ** Specify the a
34010 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f  ctivation key fo
34020 72 20 61 20 43 45 52 4f 44 20 64 61 74 61 62 61  r a CEROD databa
34030 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20  se.  Unless .** 
34040 61 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20  activated, none 
34050 6f 66 20 74 68 65 20 43 45 52 4f 44 20 72 6f 75  of the CEROD rou
34060 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e  tines will work.
34070 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
34080 5f 61 63 74 69 76 61 74 65 5f 63 65 72 6f 64 28  _activate_cerod(
34090 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
340a0 50 61 73 73 50 68 72 61 73 65 20 20 20 20 20 20  PassPhrase      
340b0 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20    /* Activation 
340c0 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e  phrase */.);.#en
340d0 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
340e0 52 45 46 3a 20 53 75 73 70 65 6e 64 20 45 78 65  REF: Suspend Exe
340f0 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f  cution For A Sho
34100 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 54 68  rt Time.**.** Th
34110 65 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28  e sqlite3_sleep(
34120 29 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65  ) function cause
34130 73 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 68  s the current th
34140 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e 64 20  read to suspend 
34150 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72  execution.** for
34160 20 61 74 20 6c 65 61 73 74 20 61 20 6e 75 6d 62   at least a numb
34170 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
34180 64 73 20 73 70 65 63 69 66 69 65 64 20 69 6e 20  ds specified in 
34190 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  its parameter..*
341a0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 65 72  *.** If the oper
341b0 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64 6f 65  ating system doe
341c0 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 73 6c  s not support sl
341d0 65 65 70 20 72 65 71 75 65 73 74 73 20 77 69 74  eep requests wit
341e0 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  h.** millisecond
341f0 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e   time resolution
34200 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d 65 20  , then the time 
34210 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64 20  will be rounded 
34220 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61  up to.** the nea
34230 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 54 68 65  rest second. The
34240 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69   number of milli
34250 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
34260 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71   actually.** req
34270 75 65 73 74 65 64 20 66 72 6f 6d 20 74 68 65 20  uested from the 
34280 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
34290 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
342a0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 69 6d 70 6c  .** ^SQLite impl
342b0 65 6d 65 6e 74 73 20 74 68 69 73 20 69 6e 74 65  ements this inte
342c0 72 66 61 63 65 20 62 79 20 63 61 6c 6c 69 6e 67  rface by calling
342d0 20 74 68 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a   the xSleep().**
342e0 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64   method of the d
342f0 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
34300 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 49 66  vfs] object.  If
34310 20 74 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65   the xSleep() me
34320 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 64  thod.** of the d
34330 65 66 61 75 6c 74 20 56 46 53 20 69 73 20 6e 6f  efault VFS is no
34340 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 63 6f  t implemented co
34350 72 72 65 63 74 6c 79 2c 20 6f 72 20 6e 6f 74 20  rrectly, or not 
34360 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 74 0a 2a  implemented at.*
34370 2a 20 61 6c 6c 2c 20 74 68 65 6e 20 74 68 65 20  * all, then the 
34380 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69  behavior of sqli
34390 74 65 33 5f 73 6c 65 65 70 28 29 20 6d 61 79 20  te3_sleep() may 
343a0 64 65 76 69 61 74 65 20 66 72 6f 6d 20 74 68 65  deviate from the
343b0 20 64 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 20   description.** 
343c0 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  in the previous 
343d0 70 61 72 61 67 72 61 70 68 73 2e 0a 2a 2f 0a 69  paragraphs..*/.i
343e0 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70  nt sqlite3_sleep
343f0 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  (int);../*.** CA
34400 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20  PI3REF: Name Of 
34410 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69  The Folder Holdi
34420 6e 67 20 54 65 6d 70 6f 72 61 72 79 20 46 69 6c  ng Temporary Fil
34430 65 73 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68  es.**.** ^(If th
34440 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62  is global variab
34450 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f  le is made to po
34460 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20  int to a string 
34470 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20  which is.** the 
34480 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72  name of a folder
34490 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f   (a.k.a. directo
344a0 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65  ry), then all te
344b0 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a  mporary files.**
344c0 20 63 72 65 61 74 65 64 20 62 79 20 53 51 4c 69   created by SQLi
344d0 74 65 20 77 68 65 6e 20 75 73 69 6e 67 20 61 20  te when using a 
344e0 62 75 69 6c 74 2d 69 6e 20 5b 73 71 6c 69 74 65  built-in [sqlite
344f0 33 5f 76 66 73 20 7c 20 56 46 53 5d 0a 2a 2a 20  3_vfs | VFS].** 
34500 77 69 6c 6c 20 62 65 20 70 6c 61 63 65 64 20 69  will be placed i
34510 6e 20 74 68 61 74 20 64 69 72 65 63 74 6f 72 79  n that directory
34520 2e 29 5e 20 20 5e 49 66 20 74 68 69 73 20 76 61  .)^  ^If this va
34530 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 61 20 4e  riable.** is a N
34540 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
34550 6e 20 53 51 4c 69 74 65 20 70 65 72 66 6f 72 6d  n SQLite perform
34560 73 20 61 20 73 65 61 72 63 68 20 66 6f 72 20 61  s a search for a
34570 6e 20 61 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a  n appropriate.**
34580 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 20   temporary file 
34590 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a  directory..**.**
345a0 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20   It is not safe 
345b0 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66  to read or modif
345c0 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  y this variable 
345d0 69 6e 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  in more than one
345e0 0a 2a 2a 20 74 68 72 65 61 64 20 61 74 20 61 20  .** thread at a 
345f0 74 69 6d 65 2e 20 20 49 74 20 69 73 20 6e 6f 74  time.  It is not
34600 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72   safe to read or
34610 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72   modify this var
34620 69 61 62 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64  iable.** if a [d
34630 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
34640 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 75 73 65  on] is being use
34650 64 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  d at the same ti
34660 6d 65 20 69 6e 20 61 20 73 65 70 61 72 61 74 65  me in a separate
34670 0a 2a 2a 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49  .** thread..** I
34680 74 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68  t is intended th
34690 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  at this variable
346a0 20 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20   be set once.** 
346b0 61 73 20 70 61 72 74 20 6f 66 20 70 72 6f 63 65  as part of proce
346c0 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ss initializatio
346d0 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79  n and before any
346e0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
346f0 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 61  e.** routines ha
34700 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 61  ve been called a
34710 6e 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72  nd that this var
34720 69 61 62 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63  iable remain unc
34730 68 61 6e 67 65 64 0a 2a 2a 20 74 68 65 72 65 61  hanged.** therea
34740 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  fter..**.** ^The
34750 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72   [temp_store_dir
34760 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d  ectory pragma] m
34770 61 79 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76  ay modify this v
34780 61 72 69 61 62 6c 65 20 61 6e 64 20 63 61 75 73  ariable and caus
34790 65 0a 2a 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74  e.** it to point
347a0 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69   to memory obtai
347b0 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
347c0 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72  3_malloc].  ^Fur
347d0 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65  thermore,.** the
347e0 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72   [temp_store_dir
347f0 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 61  ectory pragma] a
34800 6c 77 61 79 73 20 61 73 73 75 6d 65 73 20 74 68  lways assumes th
34810 61 74 20 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a  at any string.**
34820 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61   that this varia
34830 62 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73  ble points to is
34840 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20   held in memory 
34850 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a  obtained from .*
34860 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
34870 63 5d 20 61 6e 64 20 74 68 65 20 70 72 61 67 6d  c] and the pragm
34880 61 20 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f  a may attempt to
34890 20 66 72 65 65 20 74 68 61 74 20 6d 65 6d 6f 72   free that memor
348a0 79 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69  y.** using [sqli
348b0 74 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65  te3_free]..** He
348c0 6e 63 65 2c 20 69 66 20 74 68 69 73 20 76 61 72  nce, if this var
348d0 69 61 62 6c 65 20 69 73 20 6d 6f 64 69 66 69 65  iable is modifie
348e0 64 20 64 69 72 65 63 74 6c 79 2c 20 65 69 74 68  d directly, eith
348f0 65 72 20 69 74 20 73 68 6f 75 6c 64 20 62 65 0a  er it should be.
34900 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20  ** made NULL or 
34910 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f  made to point to
34920 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
34930 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
34940 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73  alloc].** or els
34950 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65  e the use of the
34960 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72   [temp_store_dir
34970 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 73  ectory pragma] s
34980 68 6f 75 6c 64 20 62 65 20 61 76 6f 69 64 65 64  hould be avoided
34990 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45  ..*/.SQLITE_EXTE
349a0 52 4e 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  RN char *sqlite3
349b0 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b  _temp_directory;
349c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
349d0 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f  : Name Of The Fo
349e0 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 44 61 74  lder Holding Dat
349f0 61 62 61 73 65 20 46 69 6c 65 73 0a 2a 2a 0a 2a  abase Files.**.*
34a00 2a 20 5e 28 49 66 20 74 68 69 73 20 67 6c 6f 62  * ^(If this glob
34a10 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d  al variable is m
34a20 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
34a30 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69  a string which i
34a40 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66  s.** the name of
34a50 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61   a folder (a.k.a
34a60 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68  . directory), th
34a70 65 6e 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20  en all database 
34a80 66 69 6c 65 73 0a 2a 2a 20 73 70 65 63 69 66 69  files.** specifi
34a90 65 64 20 77 69 74 68 20 61 20 72 65 6c 61 74 69  ed with a relati
34aa0 76 65 20 70 61 74 68 6e 61 6d 65 20 61 6e 64 20  ve pathname and 
34ab0 63 72 65 61 74 65 64 20 6f 72 20 61 63 63 65 73  created or acces
34ac0 73 65 64 20 62 79 0a 2a 2a 20 53 51 4c 69 74 65  sed by.** SQLite
34ad0 20 77 68 65 6e 20 75 73 69 6e 67 20 61 20 62 75   when using a bu
34ae0 69 6c 74 2d 69 6e 20 5b 73 71 6c 69 74 65 33 5f  ilt-in [sqlite3_
34af0 76 66 73 20 7c 20 56 46 53 5d 20 77 69 6c 6c 20  vfs | VFS] will 
34b00 62 65 20 61 73 73 75 6d 65 64 0a 2a 2a 20 74 6f  be assumed.** to
34b10 20 62 65 20 72 65 6c 61 74 69 76 65 20 74 6f 20   be relative to 
34b20 74 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e 29  that directory.)
34b30 5e 20 5e 49 66 20 74 68 69 73 20 76 61 72 69 61  ^ ^If this varia
34b40 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 0a 2a 2a  ble is a NULL.**
34b50 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53   pointer, then S
34b60 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68  QLite assumes th
34b70 61 74 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20  at all database 
34b80 66 69 6c 65 73 20 73 70 65 63 69 66 69 65 64 0a  files specified.
34b90 2a 2a 20 77 69 74 68 20 61 20 72 65 6c 61 74 69  ** with a relati
34ba0 76 65 20 70 61 74 68 6e 61 6d 65 20 61 72 65 20  ve pathname are 
34bb0 72 65 6c 61 74 69 76 65 20 74 6f 20 74 68 65 20  relative to the 
34bc0 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72  current director
34bd0 79 0a 2a 2a 20 66 6f 72 20 74 68 65 20 70 72 6f  y.** for the pro
34be0 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 43 68 61 6e  cess..**.** Chan
34bf0 67 69 6e 67 20 74 68 65 20 76 61 6c 75 65 20 6f  ging the value o
34c00 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  f this variable 
34c10 77 68 69 6c 65 20 61 20 64 61 74 61 62 61 73 65  while a database
34c20 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 0a 2a   connection is.*
34c30 2a 20 6f 70 65 6e 20 63 61 6e 20 72 65 73 75 6c  * open can resul
34c40 74 20 69 6e 20 61 20 63 6f 72 72 75 70 74 20 64  t in a corrupt d
34c50 61 74 61 62 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 49  atabase..**.** I
34c60 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
34c70 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20   read or modify 
34c80 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 6e  this variable in
34c90 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a   more than one.*
34ca0 2a 20 74 68 72 65 61 64 20 61 74 20 61 20 74 69  * thread at a ti
34cb0 6d 65 2e 20 20 49 74 20 69 73 20 6e 6f 74 20 73  me.  It is not s
34cc0 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d  afe to read or m
34cd0 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61  odify this varia
34ce0 62 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74  ble.** if a [dat
34cf0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
34d00 5d 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20  ] is being used 
34d10 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
34d20 20 69 6e 20 61 20 73 65 70 61 72 61 74 65 0a 2a   in a separate.*
34d30 2a 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20  * thread..** It 
34d40 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74  is intended that
34d50 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 62   this variable b
34d60 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73  e set once.** as
34d70 20 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73   part of process
34d80 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
34d90 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53  and before any S
34da0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a  QLite interface.
34db0 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65  ** routines have
34dc0 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64   been called and
34dd0 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61   that this varia
34de0 62 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63 68 61  ble remain uncha
34df0 6e 67 65 64 0a 2a 2a 20 74 68 65 72 65 61 66 74  nged.** thereaft
34e00 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  er..**.** ^The [
34e10 64 61 74 61 5f 73 74 6f 72 65 5f 64 69 72 65 63  data_store_direc
34e20 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d 61 79  tory pragma] may
34e30 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72   modify this var
34e40 69 61 62 6c 65 20 61 6e 64 20 63 61 75 73 65 0a  iable and cause.
34e50 2a 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 20 74  ** it to point t
34e60 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
34e70 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
34e80 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 68  malloc].  ^Furth
34e90 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b  ermore,.** the [
34ea0 64 61 74 61 5f 73 74 6f 72 65 5f 64 69 72 65 63  data_store_direc
34eb0 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 6c 77  tory pragma] alw
34ec0 61 79 73 20 61 73 73 75 6d 65 73 20 74 68 61 74  ays assumes that
34ed0 20 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74   any string.** t
34ee0 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c  hat this variabl
34ef0 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 68  e points to is h
34f00 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62  eld in memory ob
34f10 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20  tained from .** 
34f20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d  [sqlite3_malloc]
34f30 20 61 6e 64 20 74 68 65 20 70 72 61 67 6d 61 20   and the pragma 
34f40 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 66  may attempt to f
34f50 72 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a  ree that memory.
34f60 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ** using [sqlite
34f70 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63  3_free]..** Henc
34f80 65 2c 20 69 66 20 74 68 69 73 20 76 61 72 69 61  e, if this varia
34f90 62 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20  ble is modified 
34fa0 64 69 72 65 63 74 6c 79 2c 20 65 69 74 68 65 72  directly, either
34fb0 20 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a   it should be.**
34fc0 20 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61   made NULL or ma
34fd0 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d  de to point to m
34fe0 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
34ff0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
35000 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20  loc].** or else 
35010 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b  the use of the [
35020 64 61 74 61 5f 73 74 6f 72 65 5f 64 69 72 65 63  data_store_direc
35030 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 68 6f  tory pragma] sho
35040 75 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a  uld be avoided..
35050 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e  */.SQLITE_EXTERN
35060 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 64   char *sqlite3_d
35070 61 74 61 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a  ata_directory;..
35080 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
35090 54 65 73 74 20 46 6f 72 20 41 75 74 6f 2d 43 6f  Test For Auto-Co
350a0 6d 6d 69 74 20 4d 6f 64 65 0a 2a 2a 20 4b 45 59  mmit Mode.** KEY
350b0 57 4f 52 44 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d  WORDS: {autocomm
350c0 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 5e  it mode}.**.** ^
350d0 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
350e0 61 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e 74  autocommit() int
350f0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 6e  erface returns n
35100 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65  on-zero or.** ze
35110 72 6f 20 69 66 20 74 68 65 20 67 69 76 65 6e 20  ro if the given 
35120 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
35130 69 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f 74  ion is or is not
35140 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d   in autocommit m
35150 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69  ode,.** respecti
35160 76 65 6c 79 2e 20 20 5e 41 75 74 6f 63 6f 6d 6d  vely.  ^Autocomm
35170 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79  it mode is on by
35180 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 5e 41 75   default..** ^Au
35190 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73  tocommit mode is
351a0 20 64 69 73 61 62 6c 65 64 20 62 79 20 61 20 5b   disabled by a [
351b0 42 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74  BEGIN] statement
351c0 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74  ..** ^Autocommit
351d0 20 6d 6f 64 65 20 69 73 20 72 65 2d 65 6e 61 62   mode is re-enab
351e0 6c 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49 54  led by a [COMMIT
351f0 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e  ] or [ROLLBACK].
35200 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61 69  .**.** If certai
35210 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f 72  n kinds of error
35220 73 20 6f 63 63 75 72 20 6f 6e 20 61 20 73 74 61  s occur on a sta
35230 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20  tement within a 
35240 6d 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74 0a  multi-statement.
35250 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 28  ** transaction (
35260 65 72 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e 67  errors including
35270 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20   [SQLITE_FULL], 
35280 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c 0a  [SQLITE_IOERR],.
35290 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ** [SQLITE_NOMEM
352a0 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ], [SQLITE_BUSY]
352b0 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49 4e  , and [SQLITE_IN
352c0 54 45 52 52 55 50 54 5d 29 20 74 68 65 6e 20 74  TERRUPT]) then t
352d0 68 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f  he.** transactio
352e0 6e 20 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c 65  n might be rolle
352f0 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63  d back automatic
35300 61 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79 20  ally.  The only 
35310 77 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f  way to.** find o
35320 75 74 20 77 68 65 74 68 65 72 20 53 51 4c 69 74  ut whether SQLit
35330 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
35340 72 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68 65 20  rolled back the 
35350 74 72 61 6e 73 61 63 74 69 6f 6e 20 61 66 74 65  transaction afte
35360 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69 73  r.** an error is
35370 20 74 6f 20 75 73 65 20 74 68 69 73 20 66 75 6e   to use this fun
35380 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ction..**.** If 
35390 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 63  another thread c
353a0 68 61 6e 67 65 73 20 74 68 65 20 61 75 74 6f 63  hanges the autoc
353b0 6f 6d 6d 69 74 20 73 74 61 74 75 73 20 6f 66 20  ommit status of 
353c0 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
353d0 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65  connection while
353e0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
353f0 20 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74   running, then t
35400 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
35410 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  ** is undefined.
35420 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
35430 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73  get_autocommit(s
35440 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
35450 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20   CAPI3REF: Find 
35460 54 68 65 20 44 61 74 61 62 61 73 65 20 48 61 6e  The Database Han
35470 64 6c 65 20 4f 66 20 41 20 50 72 65 70 61 72 65  dle Of A Prepare
35480 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a  d Statement.**.*
35490 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
354a0 62 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72 66 61  b_handle interfa
354b0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b  ce returns the [
354c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
354d0 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 74  ion] handle.** t
354e0 6f 20 77 68 69 63 68 20 61 20 5b 70 72 65 70 61  o which a [prepa
354f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 62  red statement] b
35500 65 6c 6f 6e 67 73 2e 20 20 5e 54 68 65 20 5b 64  elongs.  ^The [d
35510 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
35520 6f 6e 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  on].** returned 
35530 62 79 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  by sqlite3_db_ha
35540 6e 64 6c 65 20 69 73 20 74 68 65 20 73 61 6d 65  ndle is the same
35550 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
35560 63 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20 77  ction].** that w
35570 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
35580 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20  ument.** to the 
35590 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
355a0 5f 76 32 28 29 5d 20 63 61 6c 6c 20 28 6f 72 20  _v2()] call (or 
355b0 69 74 73 20 76 61 72 69 61 6e 74 73 29 20 74 68  its variants) th
355c0 61 74 20 77 61 73 20 75 73 65 64 20 74 6f 0a 2a  at was used to.*
355d0 2a 20 63 72 65 61 74 65 20 74 68 65 20 73 74 61  * create the sta
355e0 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 66 69  tement in the fi
355f0 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2f 0a 73 71  rst place..*/.sq
35600 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 64  lite3 *sqlite3_d
35610 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33  b_handle(sqlite3
35620 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
35630 43 41 50 49 33 52 45 46 3a 20 52 65 74 75 72 6e  CAPI3REF: Return
35640 20 54 68 65 20 46 69 6c 65 6e 61 6d 65 20 46 6f   The Filename Fo
35650 72 20 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e  r A Database Con
35660 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54  nection.**.** ^T
35670 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 66 69  he sqlite3_db_fi
35680 6c 65 6e 61 6d 65 28 44 2c 4e 29 20 69 6e 74 65  lename(D,N) inte
35690 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
356a0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 69 6c  pointer to a fil
356b0 65 6e 61 6d 65 0a 2a 2a 20 61 73 73 6f 63 69 61  ename.** associa
356c0 74 65 64 20 77 69 74 68 20 64 61 74 61 62 61 73  ted with databas
356d0 65 20 4e 20 6f 66 20 63 6f 6e 6e 65 63 74 69 6f  e N of connectio
356e0 6e 20 44 2e 20 20 5e 54 68 65 20 6d 61 69 6e 20  n D.  ^The main 
356f0 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a  database file.**
35700 20 68 61 73 20 74 68 65 20 6e 61 6d 65 20 22 6d   has the name "m
35710 61 69 6e 22 2e 20 20 49 66 20 74 68 65 72 65 20  ain".  If there 
35720 69 73 20 6e 6f 20 61 74 74 61 63 68 65 64 20 64  is no attached d
35730 61 74 61 62 61 73 65 20 4e 20 6f 6e 20 74 68 65  atabase N on the
35740 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
35750 6e 65 63 74 69 6f 6e 20 44 2c 20 6f 72 20 69 66  nection D, or if
35760 20 64 61 74 61 62 61 73 65 20 4e 20 69 73 20 61   database N is a
35770 20 74 65 6d 70 6f 72 61 72 79 20 6f 72 20 69 6e   temporary or in
35780 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
35790 2c 20 74 68 65 6e 0a 2a 2a 20 61 20 4e 55 4c 4c  , then.** a NULL
357a0 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75   pointer is retu
357b0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rned..**.** ^The
357c0 20 66 69 6c 65 6e 61 6d 65 20 72 65 74 75 72 6e   filename return
357d0 65 64 20 62 79 20 74 68 69 73 20 66 75 6e 63 74  ed by this funct
357e0 69 6f 6e 20 69 73 20 74 68 65 20 6f 75 74 70 75  ion is the outpu
357f0 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 46 75 6c  t of the.** xFul
35800 6c 50 61 74 68 6e 61 6d 65 20 6d 65 74 68 6f 64  lPathname method
35810 20 6f 66 20 74 68 65 20 5b 56 46 53 5d 2e 20 20   of the [VFS].  
35820 5e 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c  ^In other words,
35830 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a   the filename.**
35840 20 77 69 6c 6c 20 62 65 20 61 6e 20 61 62 73 6f   will be an abso
35850 6c 75 74 65 20 70 61 74 68 6e 61 6d 65 2c 20 65  lute pathname, e
35860 76 65 6e 20 69 66 20 74 68 65 20 66 69 6c 65 6e  ven if the filen
35870 61 6d 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20 6f  ame used.** to o
35880 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  pen the database
35890 20 6f 72 69 67 69 6e 61 6c 6c 79 20 77 61 73 20   originally was 
358a0 61 20 55 52 49 20 6f 72 20 72 65 6c 61 74 69 76  a URI or relativ
358b0 65 20 70 61 74 68 6e 61 6d 65 2e 0a 2a 2f 0a 63  e pathname..*/.c
358c0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
358d0 65 33 5f 64 62 5f 66 69 6c 65 6e 61 6d 65 28 73  e3_db_filename(s
358e0 71 6c 69 74 65 33 20 2a 64 62 2c 20 63 6f 6e 73  qlite3 *db, cons
358f0 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 29  t char *zDbName)
35900 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
35910 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 69 66 20  F: Determine if 
35920 61 20 64 61 74 61 62 61 73 65 20 69 73 20 72 65  a database is re
35930 61 64 2d 6f 6e 6c 79 0a 2a 2a 0a 2a 2a 20 5e 54  ad-only.**.** ^T
35940 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 72 65  he sqlite3_db_re
35950 61 64 6f 6e 6c 79 28 44 2c 4e 29 20 69 6e 74 65  adonly(D,N) inte
35960 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 31 20  rface returns 1 
35970 69 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  if the database 
35980 4e 0a 2a 2a 20 6f 66 20 63 6f 6e 6e 65 63 74 69  N.** of connecti
35990 6f 6e 20 44 20 69 73 20 72 65 61 64 2d 6f 6e 6c  on D is read-onl
359a0 79 2c 20 30 20 69 66 20 69 74 20 69 73 20 72 65  y, 0 if it is re
359b0 61 64 2f 77 72 69 74 65 2c 20 6f 72 20 2d 31 20  ad/write, or -1 
359c0 69 66 20 4e 20 69 73 20 6e 6f 74 0a 2a 2a 20 74  if N is not.** t
359d0 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 64 61 74  he name of a dat
359e0 61 62 61 73 65 20 6f 6e 20 63 6f 6e 6e 65 63 74  abase on connect
359f0 69 6f 6e 20 44 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ion D..*/.int sq
35a00 6c 69 74 65 33 5f 64 62 5f 72 65 61 64 6f 6e 6c  lite3_db_readonl
35a10 79 28 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 63  y(sqlite3 *db, c
35a20 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61  onst char *zDbNa
35a30 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  me);../*.** CAPI
35a40 33 52 45 46 3a 20 46 69 6e 64 20 74 68 65 20 6e  3REF: Find the n
35a50 65 78 74 20 70 72 65 70 61 72 65 64 20 73 74 61  ext prepared sta
35a60 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  tement.**.** ^Th
35a70 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  is interface ret
35a80 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
35a90 6f 20 74 68 65 20 6e 65 78 74 20 5b 70 72 65 70  o the next [prep
35aa0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
35ab0 61 66 74 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61  after.** pStmt a
35ac0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
35ad0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
35ae0 6e 65 63 74 69 6f 6e 5d 20 70 44 62 2e 20 20 5e  nection] pDb.  ^
35af0 49 66 20 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c  If pStmt is NULL
35b00 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 69 6e  .** then this in
35b10 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
35b20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
35b30 20 66 69 72 73 74 20 70 72 65 70 61 72 65 64 20   first prepared 
35b40 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73  statement.** ass
35b50 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
35b60 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
35b70 74 69 6f 6e 20 70 44 62 2e 20 20 5e 49 66 20 6e  tion pDb.  ^If n
35b80 6f 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  o prepared state
35b90 6d 65 6e 74 0a 2a 2a 20 73 61 74 69 73 66 69 65  ment.** satisfie
35ba0 73 20 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73  s the conditions
35bb0 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
35bc0 2c 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c  , it returns NUL
35bd0 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64 61  L..**.** The [da
35be0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
35bf0 6e 5d 20 70 6f 69 6e 74 65 72 20 44 20 69 6e 20  n] pointer D in 
35c00 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  a call to.** [sq
35c10 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
35c20 44 2c 53 29 5d 20 6d 75 73 74 20 72 65 66 65 72  D,S)] must refer
35c30 20 74 6f 20 61 6e 20 6f 70 65 6e 20 64 61 74 61   to an open data
35c40 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
35c50 6f 6e 20 61 6e 64 20 69 6e 20 70 61 72 74 69 63  on and in partic
35c60 75 6c 61 72 20 6d 75 73 74 20 6e 6f 74 20 62 65  ular must not be
35c70 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
35c80 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 73 74 6d 74  .*/.sqlite3_stmt
35c90 20 2a 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   *sqlite3_next_s
35ca0 74 6d 74 28 73 71 6c 69 74 65 33 20 2a 70 44 62  tmt(sqlite3 *pDb
35cb0 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  , sqlite3_stmt *
35cc0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
35cd0 41 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20  API3REF: Commit 
35ce0 41 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74  And Rollback Not
35cf0 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61  ification Callba
35d00 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  cks.**.** ^The s
35d10 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
35d20 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ok() interface r
35d30 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62  egisters a callb
35d40 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ack.** function 
35d50 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68  to be invoked wh
35d60 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61 63  enever a transac
35d70 74 69 6f 6e 20 69 73 20 5b 43 4f 4d 4d 49 54 20  tion is [COMMIT 
35d80 7c 20 63 6f 6d 6d 69 74 74 65 64 5d 2e 0a 2a 2a  | committed]..**
35d90 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73   ^Any callback s
35da0 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73  et by a previous
35db0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
35dc0 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a  _commit_hook().*
35dd0 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64  * for the same d
35de0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
35df0 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e  on is overridden
35e00 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
35e10 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28  3_rollback_hook(
35e20 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ) interface regi
35e30 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
35e40 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  .** function to 
35e50 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
35e60 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ver a transactio
35e70 6e 20 69 73 20 5b 52 4f 4c 4c 42 41 43 4b 20 7c  n is [ROLLBACK |
35e80 20 72 6f 6c 6c 65 64 20 62 61 63 6b 5d 2e 0a 2a   rolled back]..*
35e90 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20  * ^Any callback 
35ea0 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75  set by a previou
35eb0 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  s call to sqlite
35ec0 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28  3_rollback_hook(
35ed0 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d  ).** for the sam
35ee0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
35ef0 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64  ction is overrid
35f00 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20 70 41 72  den..** ^The pAr
35f10 67 20 61 72 67 75 6d 65 6e 74 20 69 73 20 70 61  g argument is pa
35f20 73 73 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20  ssed through to 
35f30 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  the callback..**
35f40 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
35f50 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f  k on a commit ho
35f60 6f 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  ok function retu
35f70 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a  rns non-zero,.**
35f80 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74   then the commit
35f90 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e   is converted in
35fa0 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a  to a rollback..*
35fb0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
35fc0 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c  3_commit_hook(D,
35fd0 43 2c 50 29 20 61 6e 64 20 73 71 6c 69 74 65 33  C,P) and sqlite3
35fe0 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44  _rollback_hook(D
35ff0 2c 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e 73 0a  ,C,P) functions.
36000 2a 2a 20 72 65 74 75 72 6e 20 74 68 65 20 50 20  ** return the P 
36010 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68  argument from th
36020 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  e previous call 
36030 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
36040 74 69 6f 6e 0a 2a 2a 20 6f 6e 20 74 68 65 20 73  tion.** on the s
36050 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
36060 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20  nnection] D, or 
36070 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 20  NULL for.** the 
36080 66 69 72 73 74 20 63 61 6c 6c 20 66 6f 72 20 65  first call for e
36090 61 63 68 20 66 75 6e 63 74 69 6f 6e 20 6f 6e 20  ach function on 
360a0 44 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6d  D..**.** The com
360b0 6d 69 74 20 61 6e 64 20 72 6f 6c 6c 62 61 63 6b  mit and rollback
360c0 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 73 20   hook callbacks 
360d0 61 72 65 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e  are not reentran
360e0 74 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61  t..** The callba
360f0 63 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ck implementatio
36100 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  n must not do an
36110 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
36120 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
36130 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
36140 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
36150 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41  the callback.  A
36160 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f  ny actions.** to
36170 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61   modify the data
36180 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
36190 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 65 64  must be deferred
361a0 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65   until after the
361b0 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f  .** completion o
361c0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  f the [sqlite3_s
361d0 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74  tep()] call that
361e0 20 74 72 69 67 67 65 72 65 64 20 74 68 65 20 63   triggered the c
361f0 6f 6d 6d 69 74 0a 2a 2a 20 6f 72 20 72 6f 6c 6c  ommit.** or roll
36200 62 61 63 6b 20 68 6f 6f 6b 20 69 6e 20 74 68 65  back hook in the
36210 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a   first place..**
36220 20 4e 6f 74 65 20 74 68 61 74 20 72 75 6e 6e 69   Note that runni
36230 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c  ng any other SQL
36240 20 73 74 61 74 65 6d 65 6e 74 73 2c 20 69 6e 63   statements, inc
36250 6c 75 64 69 6e 67 20 53 45 4c 45 43 54 20 73 74  luding SELECT st
36260 61 74 65 6d 65 6e 74 73 2c 0a 2a 2a 20 6f 72 20  atements,.** or 
36270 6d 65 72 65 6c 79 20 63 61 6c 6c 69 6e 67 20 5b  merely calling [
36280 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
36290 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
362a0 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
362b0 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
362c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
362d0 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69  ns for the meani
362e0 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69  ng of "modify" i
362f0 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68  n this paragraph
36300 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 69 73 74 65  ..**.** ^Registe
36310 72 69 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63  ring a NULL func
36320 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 74 68  tion disables th
36330 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  e callback..**.*
36340 2a 20 5e 57 68 65 6e 20 74 68 65 20 63 6f 6d 6d  * ^When the comm
36350 69 74 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b  it hook callback
36360 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
36370 20 7a 65 72 6f 2c 20 74 68 65 20 5b 43 4f 4d 4d   zero, the [COMM
36380 49 54 5d 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e  IT].** operation
36390 20 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 20 63   is allowed to c
363a0 6f 6e 74 69 6e 75 65 20 6e 6f 72 6d 61 6c 6c 79  ontinue normally
363b0 2e 20 20 5e 49 66 20 74 68 65 20 63 6f 6d 6d 69  .  ^If the commi
363c0 74 20 68 6f 6f 6b 0a 2a 2a 20 72 65 74 75 72 6e  t hook.** return
363d0 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  s non-zero, then
363e0 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 20 69 73   the [COMMIT] is
363f0 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20   converted into 
36400 61 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a  a [ROLLBACK]..**
36410 20 5e 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 68   ^The rollback h
36420 6f 6f 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  ook is invoked o
36430 6e 20 61 20 72 6f 6c 6c 62 61 63 6b 20 74 68 61  n a rollback tha
36440 74 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 61  t results from a
36450 20 63 6f 6d 6d 69 74 0a 2a 2a 20 68 6f 6f 6b 20   commit.** hook 
36460 72 65 74 75 72 6e 69 6e 67 20 6e 6f 6e 2d 7a 65  returning non-ze
36470 72 6f 2c 20 6a 75 73 74 20 61 73 20 69 74 20 77  ro, just as it w
36480 6f 75 6c 64 20 62 65 20 77 69 74 68 20 61 6e 79  ould be with any
36490 20 6f 74 68 65 72 20 72 6f 6c 6c 62 61 63 6b 2e   other rollback.
364a0 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20  .**.** ^For the 
364b0 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73  purposes of this
364c0 20 41 50 49 2c 20 61 20 74 72 61 6e 73 61 63 74   API, a transact
364d0 69 6f 6e 20 69 73 20 73 61 69 64 20 74 6f 20 68  ion is said to h
364e0 61 76 65 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c  ave been.** roll
364f0 65 64 20 62 61 63 6b 20 69 66 20 61 6e 20 65 78  ed back if an ex
36500 70 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b  plicit "ROLLBACK
36510 22 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 65  " statement is e
36520 78 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61  xecuted, or.** a
36530 6e 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74  n error or const
36540 72 61 69 6e 74 20 63 61 75 73 65 73 20 61 6e 20  raint causes an 
36550 69 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63  implicit rollbac
36560 6b 20 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 5e  k to occur..** ^
36570 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c  The rollback cal
36580 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76  lback is not inv
36590 6f 6b 65 64 20 69 66 20 61 20 74 72 61 6e 73 61  oked if a transa
365a0 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 74 6f  ction is.** auto
365b0 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64  matically rolled
365c0 20 62 61 63 6b 20 62 65 63 61 75 73 65 20 74 68   back because th
365d0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
365e0 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e  ction is closed.
365f0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
36600 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 70 64  the [sqlite3_upd
36610 61 74 65 5f 68 6f 6f 6b 28 29 5d 20 69 6e 74 65  ate_hook()] inte
36620 72 66 61 63 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  rface..*/.void *
36630 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68  sqlite3_commit_h
36640 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  ook(sqlite3*, in
36650 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69  t(*)(void*), voi
36660 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74  d*);.void *sqlit
36670 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
36680 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28  (sqlite3*, void(
36690 2a 29 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64  *)(void *), void
366a0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
366b0 52 45 46 3a 20 44 61 74 61 20 43 68 61 6e 67 65  REF: Data Change
366c0 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61   Notification Ca
366d0 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54  llbacks.**.** ^T
366e0 68 65 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74  he sqlite3_updat
366f0 65 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61  e_hook() interfa
36700 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ce registers a c
36710 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
36720 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61  .** with the [da
36730 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
36740 6e 5d 20 69 64 65 6e 74 69 66 69 65 64 20 62 79  n] identified by
36750 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
36760 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76  ent.** to be inv
36770 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20  oked whenever a 
36780 72 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c 20  row is updated, 
36790 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65  inserted or dele
367a0 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c  ted..** ^Any cal
367b0 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70  lback set by a p
367c0 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20  revious call to 
367d0 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  this function.**
367e0 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61   for the same da
367f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
36800 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e  n is overridden.
36810 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f  .**.** ^The seco
36820 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  nd argument is a
36830 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
36840 66 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f  function to invo
36850 6b 65 20 77 68 65 6e 20 61 0a 2a 2a 20 72 6f 77  ke when a.** row
36860 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73   is updated, ins
36870 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64  erted or deleted
36880 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  ..** ^The first 
36890 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
368a0 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f  callback is a co
368b0 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 20  py of the third 
368c0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73  argument.** to s
368d0 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f  qlite3_update_ho
368e0 6f 6b 28 29 2e 0a 2a 2a 20 5e 54 68 65 20 73 65  ok()..** ^The se
368f0 63 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20 61 72  cond callback ar
36900 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66  gument is one of
36910 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d   [SQLITE_INSERT]
36920 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45  , [SQLITE_DELETE
36930 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45  ],.** or [SQLITE
36940 5f 55 50 44 41 54 45 5d 2c 20 64 65 70 65 6e 64  _UPDATE], depend
36950 69 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61  ing on the opera
36960 74 69 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64  tion that caused
36970 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a   the callback.**
36980 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a   to be invoked..
36990 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 6e  ** ^The third an
369a0 64 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  d fourth argumen
369b0 74 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ts to the callba
369c0 63 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74  ck contain point
369d0 65 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61  ers to the.** da
369e0 74 61 62 61 73 65 20 61 6e 64 20 74 61 62 6c 65  tabase and table
369f0 20 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67   name containing
36a00 20 74 68 65 20 61 66 66 65 63 74 65 64 20 72 6f   the affected ro
36a10 77 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 6e 61 6c  w..** ^The final
36a20 20 63 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65   callback parame
36a30 74 65 72 20 69 73 20 74 68 65 20 5b 72 6f 77 69  ter is the [rowi
36a40 64 5d 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a 2a  d] of the row..*
36a50 2a 20 5e 49 6e 20 74 68 65 20 63 61 73 65 20 6f  * ^In the case o
36a60 66 20 61 6e 20 75 70 64 61 74 65 2c 20 74 68 69  f an update, thi
36a70 73 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d  s is the [rowid]
36a80 20 61 66 74 65 72 20 74 68 65 20 75 70 64 61 74   after the updat
36a90 65 20 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a  e takes place..*
36aa0 2a 0a 2a 2a 20 5e 28 54 68 65 20 75 70 64 61 74  *.** ^(The updat
36ab0 65 20 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e  e hook is not in
36ac0 76 6f 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72  voked when inter
36ad0 6e 61 6c 20 73 79 73 74 65 6d 20 74 61 62 6c 65  nal system table
36ae0 73 20 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65  s are.** modifie
36af0 64 20 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d  d (i.e. sqlite_m
36b00 61 73 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65  aster and sqlite
36b10 5f 73 65 71 75 65 6e 63 65 29 2e 29 5e 0a 2a 2a  _sequence).)^.**
36b20 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 63 75 72 72  .** ^In the curr
36b30 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ent implementati
36b40 6f 6e 2c 20 74 68 65 20 75 70 64 61 74 65 20 68  on, the update h
36b50 6f 6f 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 69 6e  ook.** is not in
36b60 76 6f 6b 65 64 20 77 68 65 6e 20 64 75 70 6c 69  voked when dupli
36b70 63 61 74 69 6f 6e 20 72 6f 77 73 20 61 72 65 20  cation rows are 
36b80 64 65 6c 65 74 65 64 20 62 65 63 61 75 73 65 20  deleted because 
36b90 6f 66 20 61 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e  of an.** [ON CON
36ba0 46 4c 49 43 54 20 7c 20 4f 4e 20 43 4f 4e 46 4c  FLICT | ON CONFL
36bb0 49 43 54 20 52 45 50 4c 41 43 45 5d 20 63 6c 61  ICT REPLACE] cla
36bc0 75 73 65 2e 20 20 5e 4e 6f 72 20 69 73 20 74 68  use.  ^Nor is th
36bd0 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a  e update hook.**
36be0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 72 6f   invoked when ro
36bf0 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 75  ws are deleted u
36c00 73 69 6e 67 20 74 68 65 20 5b 74 72 75 6e 63 61  sing the [trunca
36c10 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d  te optimization]
36c20 2e 0a 2a 2a 20 54 68 65 20 65 78 63 65 70 74 69  ..** The excepti
36c30 6f 6e 73 20 64 65 66 69 6e 65 64 20 69 6e 20 74  ons defined in t
36c40 68 69 73 20 70 61 72 61 67 72 61 70 68 20 6d 69  his paragraph mi
36c50 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20 61 20  ght change in a 
36c60 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73  future.** releas
36c70 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a  e of SQLite..**.
36c80 2a 2a 20 54 68 65 20 75 70 64 61 74 65 20 68 6f  ** The update ho
36c90 6f 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ok implementatio
36ca0 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  n must not do an
36cb0 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
36cc0 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
36cd0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
36ce0 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
36cf0 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e  the update hook.
36d00 20 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a    Any actions.**
36d10 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64   to modify the d
36d20 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
36d30 6f 6e 20 6d 75 73 74 20 62 65 20 64 65 66 65 72  on must be defer
36d40 72 65 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20  red until after 
36d50 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f  the.** completio
36d60 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  n of the [sqlite
36d70 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74  3_step()] call t
36d80 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68  hat triggered th
36d90 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 0a 2a  e update hook..*
36da0 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c  * Note that [sql
36db0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
36dc0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
36dd0 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64  step()] both mod
36de0 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74  ify their.** dat
36df0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
36e00 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e  s for the meanin
36e10 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e  g of "modify" in
36e20 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e   this paragraph.
36e30 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
36e40 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
36e50 44 2c 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e 0a  D,C,P) function.
36e60 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 50  ** returns the P
36e70 20 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74   argument from t
36e80 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  he previous call
36e90 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  .** on the same 
36ea0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
36eb0 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c  tion] D, or NULL
36ec0 20 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73   for.** the firs
36ed0 74 20 63 61 6c 6c 20 6f 6e 20 44 2e 0a 2a 2a 0a  t call on D..**.
36ee0 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20  ** See also the 
36ef0 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f  [sqlite3_commit_
36f00 68 6f 6f 6b 28 29 5d 20 61 6e 64 20 5b 73 71 6c  hook()] and [sql
36f10 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f  ite3_rollback_ho
36f20 6f 6b 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61  ok()].** interfa
36f30 63 65 73 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ces..*/.void *sq
36f40 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
36f50 6b 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  k(.  sqlite3*, .
36f60 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a    void(*)(void *
36f70 2c 69 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 74  ,int ,char const
36f80 20 2a 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c   *,char const *,
36f90 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a  sqlite3_int64),.
36fa0 20 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a    void*.);../*.*
36fb0 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62  * CAPI3REF: Enab
36fc0 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 53 68  le Or Disable Sh
36fd0 61 72 65 64 20 50 61 67 65 72 20 43 61 63 68 65  ared Pager Cache
36fe0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f  .**.** ^(This ro
36ff0 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72  utine enables or
37000 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 73 68   disables the sh
37010 61 72 69 6e 67 20 6f 66 20 74 68 65 20 64 61 74  aring of the dat
37020 61 62 61 73 65 20 63 61 63 68 65 0a 2a 2a 20 61  abase cache.** a
37030 6e 64 20 73 63 68 65 6d 61 20 64 61 74 61 20 73  nd schema data s
37040 74 72 75 63 74 75 72 65 73 20 62 65 74 77 65 65  tructures betwee
37050 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
37060 65 63 74 69 6f 6e 20 7c 20 63 6f 6e 6e 65 63 74  ection | connect
37070 69 6f 6e 73 5d 0a 2a 2a 20 74 6f 20 74 68 65 20  ions].** to the 
37080 73 61 6d 65 20 64 61 74 61 62 61 73 65 2e 20 53  same database. S
37090 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65  haring is enable
370a0 64 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e  d if the argumen
370b0 74 20 69 73 20 74 72 75 65 0a 2a 2a 20 61 6e 64  t is true.** and
370c0 20 64 69 73 61 62 6c 65 64 20 69 66 20 74 68 65   disabled if the
370d0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 66 61 6c   argument is fal
370e0 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 61 63  se.)^.**.** ^Cac
370f0 68 65 20 73 68 61 72 69 6e 67 20 69 73 20 65 6e  he sharing is en
37100 61 62 6c 65 64 20 61 6e 64 20 64 69 73 61 62 6c  abled and disabl
37110 65 64 20 66 6f 72 20 61 6e 20 65 6e 74 69 72 65  ed for an entire
37120 20 70 72 6f 63 65 73 73 2e 0a 2a 2a 20 54 68 69   process..** Thi
37130 73 20 69 73 20 61 20 63 68 61 6e 67 65 20 61 73  s is a change as
37140 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69   of SQLite versi
37150 6f 6e 20 33 2e 35 2e 30 2e 20 49 6e 20 70 72 69  on 3.5.0. In pri
37160 6f 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  or versions of S
37170 51 4c 69 74 65 2c 0a 2a 2a 20 73 68 61 72 69 6e  QLite,.** sharin
37180 67 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72  g was enabled or
37190 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20 65 61   disabled for ea
371a0 63 68 20 74 68 72 65 61 64 20 73 65 70 61 72 61  ch thread separa
371b0 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  tely..**.** ^(Th
371c0 65 20 63 61 63 68 65 20 73 68 61 72 69 6e 67 20  e cache sharing 
371d0 6d 6f 64 65 20 73 65 74 20 62 79 20 74 68 69 73  mode set by this
371e0 20 69 6e 74 65 72 66 61 63 65 20 65 66 66 65 63   interface effec
371f0 74 73 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e  ts all subsequen
37200 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 5b 73  t.** calls to [s
37210 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
37220 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
37230 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
37240 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20  3_open16()]..** 
37250 45 78 69 73 74 69 6e 67 20 64 61 74 61 62 61 73  Existing databas
37260 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 63 6f  e connections co
37270 6e 74 69 6e 75 65 20 75 73 65 20 74 68 65 20 73  ntinue use the s
37280 68 61 72 69 6e 67 20 6d 6f 64 65 0a 2a 2a 20 74  haring mode.** t
37290 68 61 74 20 77 61 73 20 69 6e 20 65 66 66 65 63  hat was in effec
372a0 74 20 61 74 20 74 68 65 20 74 69 6d 65 20 74 68  t at the time th
372b0 65 79 20 77 65 72 65 20 6f 70 65 6e 65 64 2e 29  ey were opened.)
372c0 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72  ^.**.** ^(This r
372d0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b  outine returns [
372e0 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68  SQLITE_OK] if sh
372f0 61 72 65 64 20 63 61 63 68 65 20 77 61 73 20 65  ared cache was e
37300 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c  nabled or disabl
37310 65 64 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c  ed.** successful
37320 6c 79 2e 20 20 41 6e 20 5b 65 72 72 6f 72 20 63  ly.  An [error c
37330 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
37340 20 6f 74 68 65 72 77 69 73 65 2e 29 5e 0a 2a 2a   otherwise.)^.**
37350 0a 2a 2a 20 5e 53 68 61 72 65 64 20 63 61 63 68  .** ^Shared cach
37360 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79  e is disabled by
37370 20 64 65 66 61 75 6c 74 2e 20 42 75 74 20 74 68   default. But th
37380 69 73 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20  is might change 
37390 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 72 65 6c  in.** future rel
373a0 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
373b0 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74    Applications t
373c0 68 61 74 20 63 61 72 65 20 61 62 6f 75 74 20 73  hat care about s
373d0 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 73  hared.** cache s
373e0 65 74 74 69 6e 67 20 73 68 6f 75 6c 64 20 73 65  etting should se
373f0 74 20 69 74 20 65 78 70 6c 69 63 69 74 6c 79 2e  t it explicitly.
37400 0a 2a 2a 0a 2a 2a 20 53 65 65 20 41 6c 73 6f 3a  .**.** See Also:
37410 20 20 5b 53 51 4c 69 74 65 20 53 68 61 72 65 64    [SQLite Shared
37420 2d 43 61 63 68 65 20 4d 6f 64 65 5d 0a 2a 2f 0a  -Cache Mode].*/.
37430 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61 62  int sqlite3_enab
37440 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28  le_shared_cache(
37450 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
37460 49 33 52 45 46 3a 20 41 74 74 65 6d 70 74 20 54  I3REF: Attempt T
37470 6f 20 46 72 65 65 20 48 65 61 70 20 4d 65 6d 6f  o Free Heap Memo
37480 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ry.**.** ^The sq
37490 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65  lite3_release_me
374a0 6d 6f 72 79 28 29 20 69 6e 74 65 72 66 61 63 65  mory() interface
374b0 20 61 74 74 65 6d 70 74 73 20 74 6f 20 66 72 65   attempts to fre
374c0 65 20 4e 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20  e N bytes.** of 
374d0 68 65 61 70 20 6d 65 6d 6f 72 79 20 62 79 20 64  heap memory by d
374e0 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d  eallocating non-
374f0 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79  essential memory
37500 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 0a 2a 2a 20   allocations.** 
37510 68 65 6c 64 20 62 79 20 74 68 65 20 64 61 74 61  held by the data
37520 62 61 73 65 20 6c 69 62 72 61 72 79 2e 20 20 20  base library.   
37530 4d 65 6d 6f 72 79 20 75 73 65 64 20 74 6f 20 63  Memory used to c
37540 61 63 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a  ache database.**
37550 20 70 61 67 65 73 20 74 6f 20 69 6d 70 72 6f 76   pages to improv
37560 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 69 73  e performance is
37570 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 6e   an example of n
37580 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d  on-essential mem
37590 6f 72 79 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33  ory..** ^sqlite3
375a0 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
375b0 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  ) returns the nu
375c0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 61 63  mber of bytes ac
375d0 74 75 61 6c 6c 79 20 66 72 65 65 64 2c 0a 2a 2a  tually freed,.**
375e0 20 77 68 69 63 68 20 6d 69 67 68 74 20 62 65 20   which might be 
375f0 6d 6f 72 65 20 6f 72 20 6c 65 73 73 20 74 68 61  more or less tha
37600 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 72 65 71  n the amount req
37610 75 65 73 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  uested..** ^The 
37620 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
37630 6d 65 6d 6f 72 79 28 29 20 72 6f 75 74 69 6e 65  memory() routine
37640 20 69 73 20 61 20 6e 6f 2d 6f 70 20 72 65 74 75   is a no-op retu
37650 72 6e 69 6e 67 20 7a 65 72 6f 0a 2a 2a 20 69 66  rning zero.** if
37660 20 53 51 4c 69 74 65 20 69 73 20 6e 6f 74 20 63   SQLite is not c
37670 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51  ompiled with [SQ
37680 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f  LITE_ENABLE_MEMO
37690 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2e 0a  RY_MANAGEMENT]..
376a0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
376b0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 72 65 6c 65  [sqlite3_db_rele
376c0 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 0a 2a 2f  ase_memory()].*/
376d0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6c  .int sqlite3_rel
376e0 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e 74 29  ease_memory(int)
376f0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
37700 46 3a 20 46 72 65 65 20 4d 65 6d 6f 72 79 20 55  F: Free Memory U
37710 73 65 64 20 42 79 20 41 20 44 61 74 61 62 61 73  sed By A Databas
37720 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a  e Connection.**.
37730 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
37740 64 62 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  db_release_memor
37750 79 28 44 29 20 69 6e 74 65 72 66 61 63 65 20 61  y(D) interface a
37760 74 74 65 6d 70 74 73 20 74 6f 20 66 72 65 65 20  ttempts to free 
37770 61 73 20 6d 75 63 68 20 68 65 61 70 0a 2a 2a 20  as much heap.** 
37780 6d 65 6d 6f 72 79 20 61 73 20 70 6f 73 73 69 62  memory as possib
37790 6c 65 20 66 72 6f 6d 20 64 61 74 61 62 61 73 65  le from database
377a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 55   connection D. U
377b0 6e 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 5b 73 71  nlike the.** [sq
377c0 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65  lite3_release_me
377d0 6d 6f 72 79 28 29 5d 20 69 6e 74 65 72 66 61 63  mory()] interfac
377e0 65 2c 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  e, this interfac
377f0 65 20 69 73 20 65 66 66 65 63 74 20 65 76 65 6e  e is effect even
37800 0a 2a 2a 20 77 68 65 6e 20 74 68 65 6e 20 5b 53  .** when then [S
37810 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
37820 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 20  ORY_MANAGEMENT] 
37830 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
37840 69 6f 6e 20 69 73 0a 2a 2a 20 6f 6d 69 74 74 65  ion is.** omitte
37850 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  d..**.** See als
37860 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65  o: [sqlite3_rele
37870 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 0a 2a 2f  ase_memory()].*/
37880 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f  .int sqlite3_db_
37890 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 73  release_memory(s
378a0 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
378b0 20 43 41 50 49 33 52 45 46 3a 20 49 6d 70 6f 73   CAPI3REF: Impos
378c0 65 20 41 20 4c 69 6d 69 74 20 4f 6e 20 48 65 61  e A Limit On Hea
378d0 70 20 53 69 7a 65 0a 2a 2a 0a 2a 2a 20 5e 54 68  p Size.**.** ^Th
378e0 65 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68  e sqlite3_soft_h
378f0 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 20 69 6e  eap_limit64() in
37900 74 65 72 66 61 63 65 20 73 65 74 73 20 61 6e 64  terface sets and
37910 2f 6f 72 20 71 75 65 72 69 65 73 20 74 68 65 0a  /or queries the.
37920 2a 2a 20 73 6f 66 74 20 6c 69 6d 69 74 20 6f 6e  ** soft limit on
37930 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68   the amount of h
37940 65 61 70 20 6d 65 6d 6f 72 79 20 74 68 61 74 20  eap memory that 
37950 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61 74 65 64  may be allocated
37960 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 5e   by SQLite..** ^
37970 53 51 4c 69 74 65 20 73 74 72 69 76 65 73 20 74  SQLite strives t
37980 6f 20 6b 65 65 70 20 68 65 61 70 20 6d 65 6d 6f  o keep heap memo
37990 72 79 20 75 74 69 6c 69 7a 61 74 69 6f 6e 20 62  ry utilization b
379a0 65 6c 6f 77 20 74 68 65 20 73 6f 66 74 20 68 65  elow the soft he
379b0 61 70 0a 2a 2a 20 6c 69 6d 69 74 20 62 79 20 72  ap.** limit by r
379c0 65 64 75 63 69 6e 67 20 74 68 65 20 6e 75 6d 62  educing the numb
379d0 65 72 20 6f 66 20 70 61 67 65 73 20 68 65 6c 64  er of pages held
379e0 20 69 6e 20 74 68 65 20 70 61 67 65 20 63 61 63   in the page cac
379f0 68 65 0a 2a 2a 20 61 73 20 68 65 61 70 20 6d 65  he.** as heap me
37a00 6d 6f 72 79 20 75 73 61 67 65 73 20 61 70 70 72  mory usages appr
37a10 6f 61 63 68 65 73 20 74 68 65 20 6c 69 6d 69 74  oaches the limit
37a20 2e 0a 2a 2a 20 5e 54 68 65 20 73 6f 66 74 20 68  ..** ^The soft h
37a30 65 61 70 20 6c 69 6d 69 74 20 69 73 20 22 73 6f  eap limit is "so
37a40 66 74 22 20 62 65 63 61 75 73 65 20 65 76 65 6e  ft" because even
37a50 20 74 68 6f 75 67 68 20 53 51 4c 69 74 65 20 73   though SQLite s
37a60 74 72 69 76 65 73 20 74 6f 20 73 74 61 79 0a 2a  trives to stay.*
37a70 2a 20 62 65 6c 6f 77 20 74 68 65 20 6c 69 6d 69  * below the limi
37a80 74 2c 20 69 74 20 77 69 6c 6c 20 65 78 63 65 65  t, it will excee
37a90 64 20 74 68 65 20 6c 69 6d 69 74 20 72 61 74 68  d the limit rath
37aa0 65 72 20 74 68 61 6e 20 67 65 6e 65 72 61 74 65  er than generate
37ab0 0a 2a 2a 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4e  .** an [SQLITE_N
37ac0 4f 4d 45 4d 5d 20 65 72 72 6f 72 2e 20 20 49 6e  OMEM] error.  In
37ad0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
37ae0 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
37af0 74 20 0a 2a 2a 20 69 73 20 61 64 76 69 73 6f 72  t .** is advisor
37b00 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54  y only..**.** ^T
37b10 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
37b20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 73 6f 66  from sqlite3_sof
37b30 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29  t_heap_limit64()
37b40 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 0a   is the size of.
37b50 2a 2a 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  ** the soft heap
37b60 20 6c 69 6d 69 74 20 70 72 69 6f 72 20 74 6f 20   limit prior to 
37b70 74 68 65 20 63 61 6c 6c 2c 20 6f 72 20 6e 65 67  the call, or neg
37b80 61 74 69 76 65 20 69 6e 20 74 68 65 20 63 61 73  ative in the cas
37b90 65 20 6f 66 20 61 6e 0a 2a 2a 20 65 72 72 6f 72  e of an.** error
37ba0 2e 20 20 5e 49 66 20 74 68 65 20 61 72 67 75 6d  .  ^If the argum
37bb0 65 6e 74 20 4e 20 69 73 20 6e 65 67 61 74 69 76  ent N is negativ
37bc0 65 0a 2a 2a 20 74 68 65 6e 20 6e 6f 20 63 68 61  e.** then no cha
37bd0 6e 67 65 20 69 73 20 6d 61 64 65 20 74 6f 20 74  nge is made to t
37be0 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
37bf0 69 74 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20  it.  Hence, the 
37c00 63 75 72 72 65 6e 74 0a 2a 2a 20 73 69 7a 65 20  current.** size 
37c10 6f 66 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  of the soft heap
37c20 20 6c 69 6d 69 74 20 63 61 6e 20 62 65 20 64 65   limit can be de
37c30 74 65 72 6d 69 6e 65 64 20 62 79 20 69 6e 76 6f  termined by invo
37c40 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  king.** sqlite3_
37c50 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36  soft_heap_limit6
37c60 34 28 29 20 77 69 74 68 20 61 20 6e 65 67 61 74  4() with a negat
37c70 69 76 65 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  ive argument..**
37c80 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 72 67 75  .** ^If the argu
37c90 6d 65 6e 74 20 4e 20 69 73 20 7a 65 72 6f 20 74  ment N is zero t
37ca0 68 65 6e 20 74 68 65 20 73 6f 66 74 20 68 65 61  hen the soft hea
37cb0 70 20 6c 69 6d 69 74 20 69 73 20 64 69 73 61 62  p limit is disab
37cc0 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  led..**.** ^(The
37cd0 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
37ce0 20 69 73 20 6e 6f 74 20 65 6e 66 6f 72 63 65 64   is not enforced
37cf0 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
37d00 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  implementation.*
37d10 2a 20 69 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  * if one or more
37d20 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f   of following co
37d30 6e 64 69 74 69 6f 6e 73 20 61 72 65 20 74 72 75  nditions are tru
37d40 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  e:.**.** <ul>.**
37d50 20 3c 6c 69 3e 20 54 68 65 20 73 6f 66 74 20 68   <li> The soft h
37d60 65 61 70 20 6c 69 6d 69 74 20 69 73 20 73 65 74  eap limit is set
37d70 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 20 3c 6c 69   to zero..** <li
37d80 3e 20 4d 65 6d 6f 72 79 20 61 63 63 6f 75 6e 74  > Memory account
37d90 69 6e 67 20 69 73 20 64 69 73 61 62 6c 65 64 20  ing is disabled 
37da0 75 73 69 6e 67 20 61 20 63 6f 6d 62 69 6e 61 74  using a combinat
37db0 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20  ion of the.**   
37dc0 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66     [sqlite3_conf
37dd0 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ig]([SQLITE_CONF
37de0 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 2c 2e 2e  IG_MEMSTATUS],..
37df0 2e 29 20 73 74 61 72 74 2d 74 69 6d 65 20 6f 70  .) start-time op
37e00 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20 20 20  tion and.**     
37e10 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 44 45 46   the [SQLITE_DEF
37e20 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 20  AULT_MEMSTATUS] 
37e30 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
37e40 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 41 6e 20  ion..** <li> An 
37e50 61 6c 74 65 72 6e 61 74 69 76 65 20 70 61 67 65  alternative page
37e60 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
37e70 61 74 69 6f 6e 20 69 73 20 73 70 65 63 69 66 69  ation is specifi
37e80 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20  ed using.**     
37e90 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
37ea0 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ]([SQLITE_CONFIG
37eb0 5f 50 43 41 43 48 45 32 5d 2c 2e 2e 2e 29 2e 0a  _PCACHE2],...)..
37ec0 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 70 61 67 65  ** <li> The page
37ed0 20 63 61 63 68 65 20 61 6c 6c 6f 63 61 74 65 73   cache allocates
37ee0 20 66 72 6f 6d 20 69 74 73 20 6f 77 6e 20 6d 65   from its own me
37ef0 6d 6f 72 79 20 70 6f 6f 6c 20 73 75 70 70 6c 69  mory pool suppli
37f00 65 64 0a 2a 2a 20 20 20 20 20 20 62 79 20 5b 73  ed.**      by [s
37f10 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b  qlite3_config]([
37f20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
37f30 47 45 43 41 43 48 45 5d 2c 2e 2e 2e 29 20 72 61  GECACHE],...) ra
37f40 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20  ther than.**    
37f50 20 20 66 72 6f 6d 20 74 68 65 20 68 65 61 70 2e    from the heap.
37f60 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  .** </ul>)^.**.*
37f70 2a 20 42 65 67 69 6e 6e 69 6e 67 20 77 69 74 68  * Beginning with
37f80 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
37f90 33 2e 37 2e 33 2c 20 74 68 65 20 73 6f 66 74 20  3.7.3, the soft 
37fa0 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 65 6e  heap limit is en
37fb0 66 6f 72 63 65 64 0a 2a 2a 20 72 65 67 61 72 64  forced.** regard
37fc0 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
37fd0 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49  or not the [SQLI
37fe0 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59  TE_ENABLE_MEMORY
37ff0 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 0a 2a 2a 20  _MANAGEMENT].** 
38000 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
38010 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20  ion is invoked. 
38020 20 57 69 74 68 20 5b 53 51 4c 49 54 45 5f 45 4e   With [SQLITE_EN
38030 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41  ABLE_MEMORY_MANA
38040 47 45 4d 45 4e 54 5d 2c 0a 2a 2a 20 74 68 65 20  GEMENT],.** the 
38050 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
38060 69 73 20 65 6e 66 6f 72 63 65 64 20 6f 6e 20 65  is enforced on e
38070 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  very memory allo
38080 63 61 74 69 6f 6e 2e 20 20 57 69 74 68 6f 75 74  cation.  Without
38090 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  .** [SQLITE_ENAB
380a0 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45  LE_MEMORY_MANAGE
380b0 4d 45 4e 54 5d 2c 20 74 68 65 20 73 6f 66 74 20  MENT], the soft 
380c0 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 6f 6e  heap limit is on
380d0 6c 79 20 65 6e 66 6f 72 63 65 64 0a 2a 2a 20 77  ly enforced.** w
380e0 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20 61 6c  hen memory is al
380f0 6c 6f 63 61 74 65 64 20 62 79 20 74 68 65 20 70  located by the p
38100 61 67 65 20 63 61 63 68 65 2e 20 20 54 65 73 74  age cache.  Test
38110 69 6e 67 20 73 75 67 67 65 73 74 73 20 74 68 61  ing suggests tha
38120 74 20 62 65 63 61 75 73 65 0a 2a 2a 20 74 68 65  t because.** the
38130 20 70 61 67 65 20 63 61 63 68 65 20 69 73 20 74   page cache is t
38140 68 65 20 70 72 65 64 6f 6d 69 6e 61 74 65 20 6d  he predominate m
38150 65 6d 6f 72 79 20 75 73 65 72 20 69 6e 20 53 51  emory user in SQ
38160 4c 69 74 65 2c 20 6d 6f 73 74 0a 2a 2a 20 61 70  Lite, most.** ap
38170 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20  plications will 
38180 61 63 68 69 65 76 65 20 61 64 65 71 75 61 74 65  achieve adequate
38190 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
381a0 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 77 69 74   enforcement wit
381b0 68 6f 75 74 0a 2a 2a 20 74 68 65 20 75 73 65 20  hout.** the use 
381c0 6f 66 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  of [SQLITE_ENABL
381d0 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d  E_MEMORY_MANAGEM
381e0 45 4e 54 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ENT]..**.** The 
381f0 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 75 6e  circumstances un
38200 64 65 72 20 77 68 69 63 68 20 53 51 4c 69 74 65  der which SQLite
38210 20 77 69 6c 6c 20 65 6e 66 6f 72 63 65 20 74 68   will enforce th
38220 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
38230 74 20 6d 61 79 0a 2a 2a 20 63 68 61 6e 67 65 73  t may.** changes
38240 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
38250 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
38260 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  /.sqlite3_int64 
38270 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
38280 70 5f 6c 69 6d 69 74 36 34 28 73 71 6c 69 74 65  p_limit64(sqlite
38290 33 5f 69 6e 74 36 34 20 4e 29 3b 0a 0a 2f 2a 0a  3_int64 N);../*.
382a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 70  ** CAPI3REF: Dep
382b0 72 65 63 61 74 65 64 20 53 6f 66 74 20 48 65 61  recated Soft Hea
382c0 70 20 4c 69 6d 69 74 20 49 6e 74 65 72 66 61 63  p Limit Interfac
382d0 65 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a  e.** DEPRECATED.
382e0 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20  **.** This is a 
382f0 64 65 70 72 65 63 61 74 65 64 20 76 65 72 73 69  deprecated versi
38300 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  on of the [sqlit
38310 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d  e3_soft_heap_lim
38320 69 74 36 34 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  it64()].** inter
38330 66 61 63 65 2e 20 20 54 68 69 73 20 72 6f 75 74  face.  This rout
38340 69 6e 65 20 69 73 20 70 72 6f 76 69 64 65 64 20  ine is provided 
38350 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63  for historical c
38360 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20  ompatibility.** 
38370 6f 6e 6c 79 2e 20 20 41 6c 6c 20 6e 65 77 20 61  only.  All new a
38380 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
38390 6c 64 20 75 73 65 20 74 68 65 0a 2a 2a 20 5b 73  ld use the.** [s
383a0 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
383b0 5f 6c 69 6d 69 74 36 34 28 29 5d 20 69 6e 74 65  _limit64()] inte
383c0 72 66 61 63 65 20 72 61 74 68 65 72 20 74 68 61  rface rather tha
383d0 6e 20 74 68 69 73 20 6f 6e 65 2e 0a 2a 2f 0a 53  n this one..*/.S
383e0 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
383f0 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 6f   void sqlite3_so
38400 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 69 6e  ft_heap_limit(in
38410 74 20 4e 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  t N);.../*.** CA
38420 50 49 33 52 45 46 3a 20 45 78 74 72 61 63 74 20  PI3REF: Extract 
38430 4d 65 74 61 64 61 74 61 20 41 62 6f 75 74 20 41  Metadata About A
38440 20 43 6f 6c 75 6d 6e 20 4f 66 20 41 20 54 61 62   Column Of A Tab
38450 6c 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  le.**.** ^This r
38460 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 6d  outine returns m
38470 65 74 61 64 61 74 61 20 61 62 6f 75 74 20 61 20  etadata about a 
38480 73 70 65 63 69 66 69 63 20 63 6f 6c 75 6d 6e 20  specific column 
38490 6f 66 20 61 20 73 70 65 63 69 66 69 63 0a 2a 2a  of a specific.**
384a0 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20   database table 
384b0 61 63 63 65 73 73 69 62 6c 65 20 75 73 69 6e 67  accessible using
384c0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
384d0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
384e0 65 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74  e.** passed as t
384f0 68 65 20 66 69 72 73 74 20 66 75 6e 63 74 69 6f  he first functio
38500 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  n argument..**.*
38510 2a 20 5e 54 68 65 20 63 6f 6c 75 6d 6e 20 69 73  * ^The column is
38520 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
38530 68 65 20 73 65 63 6f 6e 64 2c 20 74 68 69 72 64  he second, third
38540 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61   and fourth para
38550 6d 65 74 65 72 73 20 74 6f 0a 2a 2a 20 74 68 69  meters to.** thi
38560 73 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 54 68 65  s function. ^The
38570 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
38580 72 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20  r is either the 
38590 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
385a0 62 61 73 65 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d  base.** (i.e. "m
385b0 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20 6f 72  ain", "temp", or
385c0 20 61 6e 20 61 74 74 61 63 68 65 64 20 64 61 74   an attached dat
385d0 61 62 61 73 65 29 20 63 6f 6e 74 61 69 6e 69 6e  abase) containin
385e0 67 20 74 68 65 20 73 70 65 63 69 66 69 65 64 0a  g the specified.
385f0 2a 2a 20 74 61 62 6c 65 20 6f 72 20 4e 55 4c 4c  ** table or NULL
38600 2e 20 5e 49 66 20 69 74 20 69 73 20 4e 55 4c 4c  . ^If it is NULL
38610 2c 20 74 68 65 6e 20 61 6c 6c 20 61 74 74 61 63  , then all attac
38620 68 65 64 20 64 61 74 61 62 61 73 65 73 20 61 72  hed databases ar
38630 65 20 73 65 61 72 63 68 65 64 0a 2a 2a 20 66 6f  e searched.** fo
38640 72 20 74 68 65 20 74 61 62 6c 65 20 75 73 69 6e  r the table usin
38650 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72  g the same algor
38660 69 74 68 6d 20 75 73 65 64 20 62 79 20 74 68 65  ithm used by the
38670 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65   database engine
38680 20 74 6f 0a 2a 2a 20 72 65 73 6f 6c 76 65 20 75   to.** resolve u
38690 6e 71 75 61 6c 69 66 69 65 64 20 74 61 62 6c 65  nqualified table
386a0 20 72 65 66 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a   references..**.
386b0 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 6e  ** ^The third an
386c0 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  d fourth paramet
386d0 65 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63  ers to this func
386e0 74 69 6f 6e 20 61 72 65 20 74 68 65 20 74 61 62  tion are the tab
386f0 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 0a 2a 2a  le and column.**
38700 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 65 73   name of the des
38710 69 72 65 64 20 63 6f 6c 75 6d 6e 2c 20 72 65 73  ired column, res
38720 70 65 63 74 69 76 65 6c 79 2e 20 4e 65 69 74 68  pectively. Neith
38730 65 72 20 6f 66 20 74 68 65 73 65 20 70 61 72 61  er of these para
38740 6d 65 74 65 72 73 0a 2a 2a 20 6d 61 79 20 62 65  meters.** may be
38750 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4d 65   NULL..**.** ^Me
38760 74 61 64 61 74 61 20 69 73 20 72 65 74 75 72 6e  tadata is return
38770 65 64 20 62 79 20 77 72 69 74 69 6e 67 20 74 6f  ed by writing to
38780 20 74 68 65 20 6d 65 6d 6f 72 79 20 6c 6f 63 61   the memory loca
38790 74 69 6f 6e 73 20 70 61 73 73 65 64 20 61 73 20  tions passed as 
387a0 74 68 65 20 35 74 68 0a 2a 2a 20 61 6e 64 20 73  the 5th.** and s
387b0 75 62 73 65 71 75 65 6e 74 20 70 61 72 61 6d 65  ubsequent parame
387c0 74 65 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e  ters to this fun
387d0 63 74 69 6f 6e 2e 20 5e 41 6e 79 20 6f 66 20 74  ction. ^Any of t
387e0 68 65 73 65 20 61 72 67 75 6d 65 6e 74 73 20 6d  hese arguments m
387f0 61 79 20 62 65 0a 2a 2a 20 4e 55 4c 4c 2c 20 69  ay be.** NULL, i
38800 6e 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  n whi