/ Hex Artifact Content
Login

Artifact 42693f5fc57345ee4bfc9ab4b65a1637c8fd2034:


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 6d 75 74 65 78 69 6e 67 20 63 6f  iled mutexing co
1be0: 64 65 20 6f 6d 69 74 74 65 64 20 64 75 65 20 74  de omitted due t
1bf0: 6f 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  o the.** [SQLITE
1c00: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 63 6f 6d  _THREADSAFE] com
1c10: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
1c20: 20 62 65 69 6e 67 20 73 65 74 20 74 6f 20 30 2e   being set to 0.
1c30: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61  .**.** SQLite ca
1c40: 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69  n be compiled wi
1c50: 74 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75  th or without mu
1c60: 74 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20  texes.  When.** 
1c70: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
1c80: 41 44 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f  ADSAFE] C prepro
1c90: 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20  cessor macro is 
1ca0: 31 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 0a  1 or 2, mutexes.
1cb0: 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61  ** are enabled a
1cc0: 6e 64 20 53 51 4c 69 74 65 20 69 73 20 74 68 72  nd SQLite is thr
1cd0: 65 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74  eadsafe.  When t
1ce0: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48  he.** [SQLITE_TH
1cf0: 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 20  READSAFE] macro 
1d00: 69 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75  is 0, .** the mu
1d10: 74 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74 65  texes are omitte
1d20: 64 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65 20  d.  Without the 
1d30: 6d 75 74 65 78 65 73 2c 20 69 74 20 69 73 20 6e  mutexes, it is n
1d40: 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73  ot safe.** to us
1d50: 65 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 72  e SQLite concurr
1d60: 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20  ently from more 
1d70: 74 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e  than one thread.
1d80: 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20  .**.** Enabling 
1d90: 6d 75 74 65 78 65 73 20 69 6e 63 75 72 73 20 61  mutexes incurs a
1da0: 20 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72 66   measurable perf
1db0: 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e  ormance penalty.
1dc0: 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64 20  .** So if speed 
1dd0: 69 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70  is of utmost imp
1de0: 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65  ortance, it make
1df0: 73 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61 62  s sense to disab
1e00: 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65  le.** the mutexe
1e10: 73 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78 69  s.  But for maxi
1e20: 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 65  mum safety, mute
1e30: 78 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65 6e  xes should be en
1e40: 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64  abled..** ^The d
1e50: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
1e60: 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74  is for mutexes t
1e70: 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  o be enabled..**
1e80: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
1e90: 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62  ce can be used b
1ea0: 79 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  y an application
1eb0: 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
1ec0: 61 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f  at the.** versio
1ed0: 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74  n of SQLite that
1ee0: 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61   it is linking a
1ef0: 67 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69  gainst was compi
1f00: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
1f10: 64 65 73 69 72 65 64 20 73 65 74 74 69 6e 67 20  desired setting 
1f20: 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  of the [SQLITE_T
1f30: 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f  HREADSAFE] macro
1f40: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
1f50: 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f  erface only repo
1f60: 72 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69  rts on the compi
1f70: 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65  le-time mutex se
1f80: 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20  tting.** of the 
1f90: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1fa0: 46 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51  FE] flag.  If SQ
1fb0: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
1fc0: 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f   with.** SQLITE_
1fd0: 54 48 52 45 41 44 53 41 46 45 3d 31 20 6f 72 20  THREADSAFE=1 or 
1fe0: 3d 32 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20  =2 then mutexes 
1ff0: 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64  are enabled by d
2000: 65 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61  efault but.** ca
2010: 6e 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61  n be fully or pa
2020: 72 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  rtially disabled
2030: 20 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f   using a call to
2040: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
2050: 28 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ()].** with the 
2060: 76 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f  verbs [SQLITE_CO
2070: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
2080: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  D], [SQLITE_CONF
2090: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c  IG_MULTITHREAD],
20a0: 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  .** or [SQLITE_C
20b0: 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 2e 20 20 5e  ONFIG_MUTEX].  ^
20c0: 28 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75  (The return valu
20d0: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69  e of the.** sqli
20e0: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
20f0: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20   function shows 
2100: 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65  only the compile
2110: 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66  -time setting of
2120: 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 74  .** thread safet
2130: 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74  y, not any run-t
2140: 69 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74  ime changes to t
2150: 68 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65  hat setting made
2160: 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   by.** sqlite3_c
2170: 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65  onfig(). In othe
2180: 72 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74  r words, the ret
2190: 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
21a0: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
21b0: 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e  e().** is unchan
21c0: 67 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20  ged by calls to 
21d0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
21e0: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68  .)^.**.** See th
21f0: 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
2200: 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  e] documentation
2210: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
2220: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
2230: 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65  int sqlite3_thre
2240: 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f  adsafe(void);../
2250: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2260: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
2270: 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59  on Handle.** KEY
2280: 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65  WORDS: {database
2290: 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61   connection} {da
22a0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
22b0: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f  ns}.**.** Each o
22c0: 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62  pen SQLite datab
22d0: 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74  ase is represent
22e0: 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20  ed by a pointer 
22f0: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
2300: 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20  f.** the opaque 
2310: 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20  structure named 
2320: 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69  "sqlite3".  It i
2330: 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e  s useful to thin
2340: 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a  k of an sqlite3.
2350: 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e  ** pointer as an
2360: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73   object.  The [s
2370: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
2380: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
2390: 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
23a0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
23b0: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74  nterfaces are it
23c0: 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20  s constructors, 
23d0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  and [sqlite3_clo
23e0: 73 65 28 29 5d 0a 2a 2a 20 69 73 20 69 74 73 20  se()].** is its 
23f0: 64 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65  destructor.  The
2400: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
2410: 72 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75  r interfaces (su
2420: 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65  ch as.** [sqlite
2430: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
2440: 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2450: 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e  _function()], an
2460: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75  d.** [sqlite3_bu
2470: 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f  sy_timeout()] to
2480: 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29   name but three)
2490: 20 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64   that are method
24a0: 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  s on an.** sqlit
24b0: 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79  e3 object..*/.ty
24c0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
24d0: 69 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f  ite3 sqlite3;../
24e0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36  *.** CAPI3REF: 6
24f0: 34 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79  4-Bit Integer Ty
2500: 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  pes.** KEYWORDS:
2510: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71   sqlite_int64 sq
2520: 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a  lite_uint64.**.*
2530: 2a 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20  * Because there 
2540: 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74  is no cross-plat
2550: 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63  form way to spec
2560: 69 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67  ify 64-bit integ
2570: 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69  er types.** SQLi
2580: 74 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65  te includes type
2590: 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20  defs for 64-bit 
25a0: 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67  signed and unsig
25b0: 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a  ned integers..**
25c0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
25d0: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
25e0: 33 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65  3_uint64 are the
25f0: 20 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20   preferred type 
2600: 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20  definitions..** 
2610: 54 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  The sqlite_int64
2620: 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74   and sqlite_uint
2630: 36 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70  64 types are sup
2640: 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77  ported for backw
2650: 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62  ards.** compatib
2660: 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a  ility only..**.*
2670: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
2680: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f  nt64 and sqlite_
2690: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
26a0: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
26b0: 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  lues.** between 
26c0: 2d 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37  -922337203685477
26d0: 35 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37  5808 and +922337
26e0: 32 30 33 36 38 35 34 37 37 35 38 30 37 20 69 6e  2036854775807 in
26f0: 63 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a  clusive.  ^The.*
2700: 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  * sqlite3_uint64
2710: 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74   and sqlite_uint
2720: 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f  64 types can sto
2730: 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  re integer value
2740: 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20  s .** between 0 
2750: 61 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37 33  and +18446744073
2760: 37 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73  709551615 inclus
2770: 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53  ive..*/.#ifdef S
2780: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45  QLITE_INT64_TYPE
2790: 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54  .  typedef SQLIT
27a0: 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c  E_INT64_TYPE sql
27b0: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70  ite_int64;.  typ
27c0: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51  edef unsigned SQ
27d0: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
27e0: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
27f0: 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53  elif defined(_MS
2800: 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65  C_VER) || define
2810: 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a  d(__BORLANDC__).
2820: 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36    typedef __int6
2830: 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  4 sqlite_int64;.
2840: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
2850: 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74  ed __int64 sqlit
2860: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a  e_uint64;.#else.
2870: 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c    typedef long l
2880: 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69  ong int sqlite_i
2890: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20  nt64;.  typedef 
28a0: 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f  unsigned long lo
28b0: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69  ng int sqlite_ui
28c0: 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70  nt64;.#endif.typ
28d0: 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36  edef sqlite_int6
28e0: 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b  4 sqlite3_int64;
28f0: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f  .typedef sqlite_
2900: 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75  uint64 sqlite3_u
2910: 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66  int64;../*.** If
2920: 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61   compiling for a
2930: 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20   processor that 
2940: 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70  lacks floating p
2950: 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a  oint support,.**
2960: 20 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65   substitute inte
2970: 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67  ger for floating
2980: 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65  -point..*/.#ifde
2990: 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c  f SQLITE_OMIT_FL
29a0: 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64  OATING_POINT.# d
29b0: 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c  efine double sql
29c0: 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69  ite3_int64.#endi
29d0: 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
29e0: 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74  F: Closing A Dat
29f0: 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
2a00: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2a10: 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 6f 75 74  te3_close() rout
2a20: 69 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72  ine is the destr
2a30: 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73  uctor for the [s
2a40: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a  qlite3] object..
2a50: 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c  ** ^Calls to sql
2a60: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 65 74  ite3_close() ret
2a70: 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66  urn SQLITE_OK if
2a80: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
2a90: 62 6a 65 63 74 20 69 73 0a 2a 2a 20 73 75 63 63  bject is.** succ
2aa0: 65 73 73 66 75 6c 6c 79 20 64 65 73 74 72 6f 79  essfully destroy
2ab0: 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63  ed and all assoc
2ac0: 69 61 74 65 64 20 72 65 73 6f 75 72 63 65 73 20  iated resources 
2ad0: 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e  are deallocated.
2ae0: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
2af0: 6f 6e 73 20 6d 75 73 74 20 5b 73 71 6c 69 74 65  ons must [sqlite
2b00: 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
2b10: 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70  alize] all [prep
2b20: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
2b30: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
2b40: 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c  _blob_close | cl
2b50: 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68  ose] all [BLOB h
2b60: 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61 74  andles] associat
2b70: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
2b80: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
2b90: 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74  prior to attempt
2ba0: 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65  ing to close the
2bb0: 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a   object.  ^If.**
2bc0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2bd0: 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20   is called on a 
2be0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2bf0: 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c  tion] that still
2c00: 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64   has.** outstand
2c10: 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73 74  ing [prepared st
2c20: 61 74 65 6d 65 6e 74 73 5d 20 6f 72 20 5b 42 4c  atements] or [BL
2c30: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 74 68 65  OB handles], the
2c40: 6e 20 69 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20  n it returns.** 
2c50: 53 51 4c 49 54 45 5f 42 55 53 59 2e 0a 2a 2a 0a  SQLITE_BUSY..**.
2c60: 2a 2a 20 5e 49 66 20 5b 73 71 6c 69 74 65 33 5f  ** ^If [sqlite3_
2c70: 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 6e 76 6f  close()] is invo
2c80: 6b 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e  ked while a tran
2c90: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c  saction is open,
2ca0: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74  .** the transact
2cb0: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ion is automatic
2cc0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
2cd0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61  ..**.** The C pa
2ce0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
2cf0: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6d 75  te3_close(C)] mu
2d00: 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e  st be either a N
2d10: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f  ULL.** pointer o
2d20: 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f  r an [sqlite3] o
2d30: 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62  bject pointer ob
2d40: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
2d50: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
2d60: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
2d70: 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
2d80: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
2d90: 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73  and not previous
2da0: 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43  ly closed..** ^C
2db0: 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  alling sqlite3_c
2dc0: 6c 6f 73 65 28 29 20 77 69 74 68 20 61 20 4e 55  lose() with a NU
2dd0: 4c 4c 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  LL pointer argum
2de0: 65 6e 74 20 69 73 20 61 20 0a 2a 2a 20 68 61 72  ent is a .** har
2df0: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a  mless no-op..*/.
2e00: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  int sqlite3_clos
2e10: 65 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f  e(sqlite3 *);../
2e20: 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f  *.** The type fo
2e30: 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  r a callback fun
2e40: 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69  ction..** This i
2e50: 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70  s legacy and dep
2e60: 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20  recated.  It is 
2e70: 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73  included for his
2e80: 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61  torical.** compa
2e90: 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20  tibility and is 
2ea0: 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a  not documented..
2eb0: 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28  */.typedef int (
2ec0: 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63  *sqlite3_callbac
2ed0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
2ee0: 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f  r**, char**);../
2ef0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
2f00: 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78  ne-Step Query Ex
2f10: 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63  ecution Interfac
2f20: 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  e.**.** The sqli
2f30: 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72  te3_exec() inter
2f40: 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e  face is a conven
2f50: 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 61 72  ience wrapper ar
2f60: 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
2f70: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2f80: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2f90: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66  , and [sqlite3_f
2fa0: 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74  inalize()],.** t
2fb0: 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70  hat allows an ap
2fc0: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e  plication to run
2fd0: 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d   multiple statem
2fe0: 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77  ents of SQL.** w
2ff0: 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f  ithout having to
3000: 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20   use a lot of C 
3010: 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  code. .**.** ^Th
3020: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3030: 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20   interface runs 
3040: 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46  zero or more UTF
3050: 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73  -8 encoded,.** s
3060: 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
3070: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
3080: 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73   passed into its
3090: 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a   2nd argument,.*
30a0: 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74  * in the context
30b0: 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
30c0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61  e connection] pa
30d0: 73 73 65 64 20 69 6e 20 61 73 20 69 74 73 20 31  ssed in as its 1
30e0: 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20  st.** argument. 
30f0: 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
3100: 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68  k function of th
3110: 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74  e 3rd argument t
3120: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
3130: 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  c() is not NULL,
3140: 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f   then it is invo
3150: 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72 65 73  ked for each res
3160: 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e  ult row.** comin
3170: 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61  g out of the eva
3180: 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  luated SQL state
3190: 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68  ments.  ^The 4th
31a0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
31b0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
31c0: 73 20 72 65 6c 61 79 65 64 20 74 68 72 6f 75 67  s relayed throug
31d0: 68 20 74 6f 20 74 68 65 20 31 73 74 20 61 72 67  h to the 1st arg
31e0: 75 6d 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a 2a  ument of each.**
31f0: 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63 61   callback invoca
3200: 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20 63  tion.  ^If the c
3210: 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72 20  allback pointer 
3220: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
3230: 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74 68  ).** is NULL, th
3240: 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20 69  en no callback i
3250: 73 20 65 76 65 72 20 69 6e 76 6f 6b 65 64 20 61  s ever invoked a
3260: 6e 64 20 72 65 73 75 6c 74 20 72 6f 77 73 20 61  nd result rows a
3270: 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a  re.** ignored..*
3280: 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f  *.** ^If an erro
3290: 72 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20 65  r occurs while e
32a0: 76 61 6c 75 61 74 69 6e 67 20 74 68 65 20 53 51  valuating the SQ
32b0: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73  L statements pas
32c0: 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69  sed into.** sqli
32d0: 74 65 33 5f 65 78 65 63 28 29 2c 20 74 68 65 6e  te3_exec(), then
32e0: 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68   execution of th
32f0: 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 6d  e current statem
3300: 65 6e 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a 2a  ent stops and.**
3310: 20 73 75 62 73 65 71 75 65 6e 74 20 73 74 61 74   subsequent stat
3320: 65 6d 65 6e 74 73 20 61 72 65 20 73 6b 69 70 70  ements are skipp
3330: 65 64 2e 20 20 5e 49 66 20 74 68 65 20 35 74 68  ed.  ^If the 5th
3340: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3350: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
3360: 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e  is not NULL then
3370: 20 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61   any error messa
3380: 67 65 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e  ge is written in
3390: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
33a0: 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ed.** from [sqli
33b0: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e  te3_malloc()] an
33c0: 64 20 70 61 73 73 65 64 20 62 61 63 6b 20 74 68  d passed back th
33d0: 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61  rough the 5th pa
33e0: 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20 61  rameter..** To a
33f0: 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61 6b  void memory leak
3400: 73 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  s, the applicati
3410: 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b 65  on should invoke
3420: 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
3430: 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d 65  ].** on error me
3440: 73 73 61 67 65 20 73 74 72 69 6e 67 73 20 72 65  ssage strings re
3450: 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20 74  turned through t
3460: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
3470: 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65   of.** of sqlite
3480: 33 5f 65 78 65 63 28 29 20 61 66 74 65 72 20 74  3_exec() after t
3490: 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
34a0: 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c 6f   string is no lo
34b0: 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 20  nger needed..** 
34c0: 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 72 61  ^If the 5th para
34d0: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
34e0: 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e  _exec() is not N
34f0: 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f 72  ULL and no error
3500: 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65 6e  s.** occur, then
3510: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3520: 73 65 74 73 20 74 68 65 20 70 6f 69 6e 74 65 72  sets the pointer
3530: 20 69 6e 20 69 74 73 20 35 74 68 20 70 61 72 61   in its 5th para
3540: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c  meter to.** NULL
3550: 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e   before returnin
3560: 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20  g..**.** ^If an 
3570: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
3580: 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
3590: 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73 71  non-zero, the sq
35a0: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
35b0: 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
35c0: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 77 69 74  SQLITE_ABORT wit
35d0: 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68  hout invoking th
35e0: 65 20 63 61 6c 6c 62 61 63 6b 20 61 67 61 69 6e  e callback again
35f0: 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74 20   and.** without 
3600: 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62 73  running any subs
3610: 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65  equent SQL state
3620: 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
3630: 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  e 2nd argument t
3640: 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78  o the sqlite3_ex
3650: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 66 75  ec() callback fu
3660: 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a 2a  nction is the.**
3670: 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
3680: 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
3690: 2e 20 20 5e 54 68 65 20 33 72 64 20 61 72 67 75  .  ^The 3rd argu
36a0: 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69  ment to the sqli
36b0: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63 61  te3_exec().** ca
36c0: 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72  llback is an arr
36d0: 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
36e0: 6f 20 73 74 72 69 6e 67 73 20 6f 62 74 61 69 6e  o strings obtain
36f0: 65 64 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a 2a  ed as if from.**
3700: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
3710: 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66 6f  _text()], one fo
3720: 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20 20  r each column.  
3730: 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20 6f  ^If an element o
3740: 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f  f a.** result ro
3750: 77 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74  w is NULL then t
3760: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
3770: 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20   string pointer 
3780: 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74  for the.** sqlit
3790: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
37a0: 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  ck is a NULL poi
37b0: 6e 74 65 72 2e 20 20 5e 54 68 65 20 34 74 68 20  nter.  ^The 4th 
37c0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a  argument to the.
37d0: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
37e0: 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  ) callback is an
37f0: 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
3800: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 77 68  rs to strings wh
3810: 65 72 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74 72  ere each.** entr
3820: 79 20 72 65 70 72 65 73 65 6e 74 73 20 74 68 65  y represents the
3830: 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72 65 73 70   name of corresp
3840: 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74 20 63 6f  onding result co
3850: 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65 64  lumn as obtained
3860: 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
3870: 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d  3_column_name()]
3880: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
3890: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  2nd parameter to
38a0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
38b0: 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
38c0: 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  r, a pointer.** 
38d0: 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  to an empty stri
38e0: 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65 72  ng, or a pointer
38f0: 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 6f   that contains o
3900: 6e 6c 79 20 77 68 69 74 65 73 70 61 63 65 20 61  nly whitespace a
3910: 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63 6f  nd/or .** SQL co
3920: 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20  mments, then no 
3930: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
3940: 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e 64  re evaluated and
3950: 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
3960: 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e   is not changed.
3970: 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74 69  .**.** Restricti
3980: 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ons:.**.** <ul>.
3990: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
39a0: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 69 6e 73  ication must ins
39b0: 75 72 65 20 74 68 61 74 20 74 68 65 20 31 73 74  ure that the 1st
39c0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
39d0: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
39e0: 20 20 20 20 20 69 73 20 61 20 76 61 6c 69 64 20       is a valid 
39f0: 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74 61 62 61  and open [databa
3a00: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a  se connection]..
3a10: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
3a20: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
3a30: 20 63 6c 6f 73 65 20 5b 64 61 74 61 62 61 73 65   close [database
3a40: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65   connection] spe
3a50: 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20  cified by.**    
3a60: 20 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65    the 1st parame
3a70: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3a80: 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69  xec() while sqli
3a90: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75  te3_exec() is ru
3aa0: 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e 20 54  nning..** <li> T
3ab0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
3ac0: 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74  ust not modify t
3ad0: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
3ae0: 20 74 65 78 74 20 70 61 73 73 65 64 20 69 6e 74   text passed int
3af0: 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 32 6e  o.**      the 2n
3b00: 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73  d parameter of s
3b10: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68  qlite3_exec() wh
3b20: 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  ile sqlite3_exec
3b30: 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  () is running..*
3b40: 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e 74 20 73  * </ul>.*/.int s
3b50: 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20 20 73  qlite3_exec(.  s
3b60: 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20  qlite3*,        
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 2f 2a 20 41 6e 20            /* An 
3b90: 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f  open database */
3ba0: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  .  const char *s
3bb0: 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  ql,             
3bc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
3bd0: 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75   SQL to be evalu
3be0: 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  ated */.  int (*
3bf0: 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c  callback)(void*,
3c00: 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a  int,char**,char*
3c10: 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b  *),  /* Callback
3c20: 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76   function */.  v
3c30: 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20  oid *,          
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 2f 2a 20 31 73 74            /* 1st
3c60: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c   argument to cal
3c70: 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20  lback */.  char 
3c80: 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20 20  **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 2f 2a 20 45 72 72 6f 72 20 6d        /* Error m
3cb0: 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  sg written here 
3cc0: 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
3cd0: 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 43 6f  I3REF: Result Co
3ce0: 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  des.** KEYWORDS:
3cf0: 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65 72 72 6f   SQLITE_OK {erro
3d00: 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f 72 20 63  r code} {error c
3d10: 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  odes}.** KEYWORD
3d20: 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 7d  S: {result code}
3d30: 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a   {result codes}.
3d40: 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74  **.** Many SQLit
3d50: 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
3d60: 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65  rn an integer re
3d70: 73 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74  sult code from t
3d80: 68 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20  he set shown.** 
3d90: 68 65 72 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  here in order to
3da0: 20 69 6e 64 69 63 61 74 65 73 20 73 75 63 63 65   indicates succe
3db0: 73 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a  ss or failure..*
3dc0: 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72 20 63  *.** New error c
3dd0: 6f 64 65 73 20 6d 61 79 20 62 65 20 61 64 64 65  odes may be adde
3de0: 64 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73  d in future vers
3df0: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ions of SQLite..
3e00: 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
3e10: 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45  [SQLITE_IOERR_RE
3e20: 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65  AD | extended re
3e30: 73 75 6c 74 20 63 6f 64 65 73 5d 2c 0a 2a 2a 20  sult codes],.** 
3e40: 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e  [sqlite3_vtab_on
3e50: 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 5b 53 51  _conflict()] [SQ
3e60: 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20  LITE_ROLLBACK | 
3e70: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 0a 2a  result codes]..*
3e80: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3e90: 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20  _OK           0 
3ea0: 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20    /* Successful 
3eb0: 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67  result */./* beg
3ec0: 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d  inning-of-error-
3ed0: 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65  codes */.#define
3ee0: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20   SQLITE_ERROR   
3ef0: 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20       1   /* SQL 
3f00: 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67  error or missing
3f10: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65   database */.#de
3f20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
3f30: 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20  RNAL     2   /* 
3f40: 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65  Internal logic e
3f50: 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a  rror in SQLite *
3f60: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3f70: 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20  _PERM         3 
3f80: 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d    /* Access perm
3f90: 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  ission denied */
3fa0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3fb0: 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20  ABORT        4  
3fc0: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75   /* Callback rou
3fd0: 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61  tine requested a
3fe0: 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69  n abort */.#defi
3ff0: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20  ne SQLITE_BUSY  
4000: 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68         5   /* Th
4010: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
4020: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
4030: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
4040: 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20  ED       6   /* 
4050: 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64  A table in the d
4060: 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65  atabase is locke
4070: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4080: 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ITE_NOMEM       
4090: 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63   7   /* A malloc
40a0: 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65  () failed */.#de
40b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
40c0: 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20  ONLY     8   /* 
40d0: 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65  Attempt to write
40e0: 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61   a readonly data
40f0: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  base */.#define 
4100: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
4110: 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61      9   /* Opera
4120: 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20  tion terminated 
4130: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  by sqlite3_inter
4140: 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65  rupt()*/.#define
4150: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20   SQLITE_IOERR   
4160: 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65      10   /* Some
4170: 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f   kind of disk I/
4180: 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64  O error occurred
4190: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
41a0: 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31  TE_CORRUPT     1
41b0: 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  1   /* The datab
41c0: 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69  ase disk image i
41d0: 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23  s malformed */.#
41e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
41f0: 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f  TFOUND    12   /
4200: 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65  * Unknown opcode
4210: 20 69 6e 20 73 71 6c 69 74 65 33 5f 66 69 6c 65   in sqlite3_file
4220: 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64  _control() */.#d
4230: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c  efine SQLITE_FUL
4240: 4c 20 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a  L        13   /*
4250: 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65   Insertion faile
4260: 64 20 62 65 63 61 75 73 65 20 64 61 74 61 62 61  d because databa
4270: 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64  se is full */.#d
4280: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
4290: 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a  TOPEN    14   /*
42a0: 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20   Unable to open 
42b0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
42c0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
42d0: 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20  ITE_PROTOCOL    
42e0: 31 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  15   /* Database
42f0: 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65   lock protocol e
4300: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
4310: 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20  SQLITE_EMPTY    
4320: 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62     16   /* Datab
4330: 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a  ase is empty */.
4340: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
4350: 43 48 45 4d 41 20 20 20 20 20 20 31 37 20 20 20  CHEMA      17   
4360: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20  /* The database 
4370: 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a  schema changed *
4380: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4390: 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20  _TOOBIG      18 
43a0: 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42    /* String or B
43b0: 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a 65  LOB exceeds size
43c0: 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e   limit */.#defin
43d0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
43e0: 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f  INT  19   /* Abo
43f0: 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72  rt due to constr
4400: 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a  aint violation *
4410: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4420: 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20  _MISMATCH    20 
4430: 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d    /* Data type m
4440: 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69  ismatch */.#defi
4450: 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  ne SQLITE_MISUSE
4460: 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69        21   /* Li
4470: 62 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72  brary used incor
4480: 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  rectly */.#defin
4490: 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20  e SQLITE_NOLFS  
44a0: 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65       22   /* Use
44b0: 73 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f  s OS features no
44c0: 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68  t supported on h
44d0: 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ost */.#define S
44e0: 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20  QLITE_AUTH      
44f0: 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72    23   /* Author
4500: 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a  ization denied *
4510: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4520: 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20  _FORMAT      24 
4530: 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64    /* Auxiliary d
4540: 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65  atabase format e
4550: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
4560: 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20  SQLITE_RANGE    
4570: 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70     25   /* 2nd p
4580: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
4590: 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20  te3_bind out of 
45a0: 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65  range */.#define
45b0: 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20   SQLITE_NOTADB  
45c0: 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65      26   /* File
45d0: 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20   opened that is 
45e0: 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
45f0: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
4600: 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20  QLITE_ROW       
4610: 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65    100  /* sqlite
4620: 33 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f  3_step() has ano
4630: 74 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a  ther row ready *
4640: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4650: 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31  _DONE        101
4660: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
4670: 70 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64  p() has finished
4680: 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a   executing */./*
4690: 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f   end-of-error-co
46a0: 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  des */../*.** CA
46b0: 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64  PI3REF: Extended
46c0: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
46d0: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65   KEYWORDS: {exte
46e0: 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 7d  nded error code}
46f0: 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   {extended error
4700: 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f   codes}.** KEYWO
4710: 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72  RDS: {extended r
4720: 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78 74  esult code} {ext
4730: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
4740: 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73  es}.**.** In its
4750: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
4760: 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41  ration, SQLite A
4770: 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  PI routines retu
4780: 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74  rn one of 26 int
4790: 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  eger.** [SQLITE_
47a0: 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65  OK | result code
47b0: 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78  s].  However, ex
47c0: 70 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f  perience has sho
47d0: 77 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a  wn that many of.
47e0: 2a 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20  ** these result 
47f0: 63 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f  codes are too co
4800: 61 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54  arse-grained.  T
4810: 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69  hey do not provi
4820: 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e  de as.** much in
4830: 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
4840: 70 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67  problems as prog
4850: 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69  rammers might li
4860: 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72  ke.  In an effor
4870: 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20  t to.** address 
4880: 74 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73  this, newer vers
4890: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28  ions of SQLite (
48a0: 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e  version 3.3.8 an
48b0: 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65  d later) include
48c0: 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20  .** support for 
48d0: 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c  additional resul
48e0: 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f  t codes that pro
48f0: 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c  vide more detail
4900: 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ed information.*
4910: 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20  * about errors. 
4920: 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73  The extended res
4930: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e  ult codes are en
4940: 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
4950: 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61  d.** on a per da
4960: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
4970: 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68  n basis using th
4980: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  e.** [sqlite3_ex
4990: 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
49a0: 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a  des()] API..**.*
49b0: 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76  * Some of the av
49c0: 61 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64  ailable extended
49d0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
49e0: 65 20 6c 69 73 74 65 64 20 68 65 72 65 2e 0a 2a  e listed here..*
49f0: 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 63 74  * One may expect
4a00: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65   the number of e
4a10: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
4a20: 6f 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78 70  odes will be exp
4a30: 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65  and.** over time
4a40: 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74  .  Software that
4a50: 20 75 73 65 73 20 65 78 74 65 6e 64 65 64 20 72   uses extended r
4a60: 65 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f 75  esult codes shou
4a70: 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20  ld expect.** to 
4a80: 73 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20 63  see new result c
4a90: 6f 64 65 73 20 69 6e 20 66 75 74 75 72 65 20 72  odes in future r
4aa0: 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
4ab0: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  e..**.** The SQL
4ac0: 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f  ITE_OK result co
4ad0: 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65  de will never be
4ae0: 20 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77   extended.  It w
4af0: 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65  ill always.** be
4b00: 20 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a   exactly zero..*
4b10: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4b20: 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20  _IOERR_READ     
4b30: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4b40: 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29  _IOERR | (1<<8))
4b50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4b60: 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44  IOERR_SHORT_READ
4b70: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4b80: 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a  IOERR | (2<<8)).
4b90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4ba0: 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20 20 20  OERR_WRITE      
4bb0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4bc0: 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23  OERR | (3<<8)).#
4bd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4be0: 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20  ERR_FSYNC       
4bf0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4c00: 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64  ERR | (4<<8)).#d
4c10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4c20: 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20  RR_DIR_FSYNC    
4c30: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4c40: 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65  RR | (5<<8)).#de
4c50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4c60: 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20 20  R_TRUNCATE      
4c70: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4c80: 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66  R | (6<<8)).#def
4c90: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4ca0: 5f 46 53 54 41 54 20 20 20 20 20 20 20 20 20 20  _FSTAT          
4cb0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4cc0: 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69   | (7<<8)).#defi
4cd0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4ce0: 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20  UNLOCK          
4cf0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4d00: 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (8<<8)).#defin
4d10: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52  e SQLITE_IOERR_R
4d20: 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  DLOCK           
4d30: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4d40: 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (9<<8)).#define
4d50: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45   SQLITE_IOERR_DE
4d60: 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20  LETE            
4d70: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4d80: 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (10<<8)).#define
4d90: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c   SQLITE_IOERR_BL
4da0: 4f 43 4b 45 44 20 20 20 20 20 20 20 20 20 20 20  OCKED           
4db0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4dc0: 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (11<<8)).#define
4dd0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f   SQLITE_IOERR_NO
4de0: 4d 45 4d 20 20 20 20 20 20 20 20 20 20 20 20 20  MEM             
4df0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4e00: 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (12<<8)).#define
4e10: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43   SQLITE_IOERR_AC
4e20: 43 45 53 53 20 20 20 20 20 20 20 20 20 20 20 20  CESS            
4e30: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4e40: 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (13<<8)).#define
4e50: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48   SQLITE_IOERR_CH
4e60: 45 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b 20  ECKRESERVEDLOCK 
4e70: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4e80: 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (14<<8)).#define
4e90: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f   SQLITE_IOERR_LO
4ea0: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CK              
4eb0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4ec0: 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (15<<8)).#define
4ed0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c   SQLITE_IOERR_CL
4ee0: 4f 53 45 20 20 20 20 20 20 20 20 20 20 20 20 20  OSE             
4ef0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4f00: 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (16<<8)).#define
4f10: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49   SQLITE_IOERR_DI
4f20: 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20  R_CLOSE         
4f30: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4f40: 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (17<<8)).#define
4f50: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
4f60: 4d 4f 50 45 4e 20 20 20 20 20 20 20 20 20 20 20  MOPEN           
4f70: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4f80: 28 31 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (18<<8)).#define
4f90: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
4fa0: 4d 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20  MSIZE           
4fb0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4fc0: 28 31 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (19<<8)).#define
4fd0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
4fe0: 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  MLOCK           
4ff0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5000: 28 32 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (20<<8)).#define
5010: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
5020: 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20  MMAP            
5030: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5040: 28 32 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (21<<8)).#define
5050: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45   SQLITE_IOERR_SE
5060: 45 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  EK              
5070: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5080: 28 32 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (22<<8)).#define
5090: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53   SQLITE_LOCKED_S
50a0: 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20  HAREDCACHE      
50b0: 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c  (SQLITE_LOCKED |
50c0: 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e    (1<<8)).#defin
50d0: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 52 45  e SQLITE_BUSY_RE
50e0: 43 4f 56 45 52 59 20 20 20 20 20 20 20 20 20 20  COVERY          
50f0: 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20   (SQLITE_BUSY   
5100: 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69  |  (1<<8)).#defi
5110: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
5120: 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20  EN_NOTEMPDIR    
5130: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50    (SQLITE_CANTOP
5140: 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  EN | (1<<8)).#de
5150: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52  fine SQLITE_CORR
5160: 55 50 54 5f 56 54 41 42 20 20 20 20 20 20 20 20  UPT_VTAB        
5170: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 52 52      (SQLITE_CORR
5180: 55 50 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  UPT | (1<<8)).#d
5190: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
51a0: 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52 59 20 20  DONLY_RECOVERY  
51b0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
51c0: 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38 29 29 0a  DONLY | (1<<8)).
51d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
51e0: 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b  EADONLY_CANTLOCK
51f0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52         (SQLITE_R
5200: 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38 29  EADONLY | (2<<8)
5210: 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  )../*.** CAPI3RE
5220: 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c  F: Flags For Fil
5230: 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e  e Open Operation
5240: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69  s.**.** These bi
5250: 74 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74  t values are int
5260: 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
5270: 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61   the.** 3rd para
5280: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  meter to the [sq
5290: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
52a0: 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a   interface and.*
52b0: 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 72  * in the 4th par
52c0: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ameter to the [s
52d0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
52e0: 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65  ] method..*/.#de
52f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5300: 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20  _READONLY       
5310: 20 20 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a    0x00000001  /*
5320: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5330: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5340: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5350: 5f 52 45 41 44 57 52 49 54 45 20 20 20 20 20 20  _READWRITE      
5360: 20 20 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a    0x00000002  /*
5370: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5380: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5390: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
53a0: 5f 43 52 45 41 54 45 20 20 20 20 20 20 20 20 20  _CREATE         
53b0: 20 20 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a    0x00000004  /*
53c0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
53d0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
53e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
53f0: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20  _DELETEONCLOSE  
5400: 20 20 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a    0x00000008  /*
5410: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
5420: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5430: 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 20  _EXCLUSIVE      
5440: 20 20 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a    0x00000010  /*
5450: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
5460: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5470: 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20  _AUTOPROXY      
5480: 20 20 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a    0x00000020  /*
5490: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
54a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
54b0: 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 20 20  _URI            
54c0: 20 20 30 78 30 30 30 30 30 30 34 30 20 20 2f 2a    0x00000040  /*
54d0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
54e0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
54f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5500: 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20  _MAIN_DB        
5510: 20 20 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a    0x00000100  /*
5520: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
5530: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5540: 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20  _TEMP_DB        
5550: 20 20 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a    0x00000200  /*
5560: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
5570: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5580: 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20  _TRANSIENT_DB   
5590: 20 20 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a    0x00000400  /*
55a0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
55b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
55c0: 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20  _MAIN_JOURNAL   
55d0: 20 20 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a    0x00000800  /*
55e0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
55f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5600: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20  _TEMP_JOURNAL   
5610: 20 20 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a    0x00001000  /*
5620: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
5630: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5640: 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20  _SUBJOURNAL     
5650: 20 20 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a    0x00002000  /*
5660: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
5670: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5680: 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20  _MASTER_JOURNAL 
5690: 20 20 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a    0x00004000  /*
56a0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
56b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
56c0: 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20  _NOMUTEX        
56d0: 20 20 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a    0x00008000  /*
56e0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
56f0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5700: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5710: 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20  _FULLMUTEX      
5720: 20 20 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a    0x00010000  /*
5730: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5740: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5750: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5760: 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20  _SHAREDCACHE    
5770: 20 20 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a    0x00020000  /*
5780: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5790: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
57a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
57b0: 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 20 20  _PRIVATECACHE   
57c0: 20 20 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a    0x00040000  /*
57d0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
57e0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
57f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5800: 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20  _WAL            
5810: 20 20 30 78 30 30 30 38 30 30 30 30 20 20 2f 2a    0x00080000  /*
5820: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a   VFS only */../*
5830: 20 52 65 73 65 72 76 65 64 3a 20 20 20 20 20 20   Reserved:      
5840: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5850: 20 20 20 30 78 30 30 46 30 30 30 30 30 20 2a 2f     0x00F00000 */
5860: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
5870: 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74  : Device Charact
5880: 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54  eristics.**.** T
5890: 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63  he xDeviceCharac
58a0: 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64  teristics method
58b0: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
58c0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  _io_methods].** 
58d0: 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61  object returns a
58e0: 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
58f0: 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74  is a vector of t
5900: 68 65 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20  he these.** bit 
5910: 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e  values expressin
5920: 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69  g I/O characteri
5930: 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73  stics of the mas
5940: 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76  s storage.** dev
5950: 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74  ice that holds t
5960: 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65  he file that the
5970: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
5980: 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20  hods].** refers 
5990: 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  to..**.** The SQ
59a0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
59b0: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  C property means
59c0: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73   that all writes
59d0: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20   of.** any size 
59e0: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
59f0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5a00: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a  OMICnnn values.*
5a10: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74  * mean that writ
5a20: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61  es of blocks tha
5a30: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20  t are nnn bytes 
5a40: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61  in size and.** a
5a50: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  re aligned to an
5a60: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69   address which i
5a70: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c  s an integer mul
5a80: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20  tiple of.** nnn 
5a90: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
5aa0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
5ab0: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20  FE_APPEND value 
5ac0: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68  means.** that wh
5ad0: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  en data is appen
5ae0: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74  ded to a file, t
5af0: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  he data is appen
5b00: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65  ded.** first the
5b10: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  n the size of th
5b20: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64  e file is extend
5b30: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74  ed, never the ot
5b40: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e  her.** way aroun
5b50: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
5b60: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
5b70: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
5b80: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  hat.** informati
5b90: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f  on is written to
5ba0: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d   disk in the sam
5bb0: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73  e order as calls
5bc0: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e  .** to xWrite().
5bd0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
5be0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
5bf0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5c00: 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69  0x00000001.#defi
5c10: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5c20: 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20  ATOMIC512       
5c30: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
5c40: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
5c50: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20  _IOCAP_ATOMIC1K 
5c60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
5c70: 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65  00000004.#define
5c80: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5c90: 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20 20  OMIC2K          
5ca0: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a       0x00000008.
5cb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5cc0: 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20  OCAP_ATOMIC4K   
5cd0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
5ce0: 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53  000010.#define S
5cf0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5d00: 49 43 38 4b 20 20 20 20 20 20 20 20 20 20 20 20  IC8K            
5d10: 20 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64     0x00000020.#d
5d20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
5d30: 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20  AP_ATOMIC16K    
5d40: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5d50: 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0040.#define SQL
5d60: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5d70: 33 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  32K             
5d80: 20 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66   0x00000080.#def
5d90: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5da0: 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20  _ATOMIC64K      
5db0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31          0x000001
5dc0: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
5dd0: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
5de0: 45 4e 44 20 20 20 20 20 20 20 20 20 20 20 20 30  END            0
5df0: 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e  x00000200.#defin
5e00: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
5e10: 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20  EQUENTIAL       
5e20: 20 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30        0x00000400
5e30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5e40: 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c  IOCAP_UNDELETABL
5e50: 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30  E_WHEN_OPEN  0x0
5e60: 30 30 30 30 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43  0000800../*.** C
5e70: 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f  API3REF: File Lo
5e80: 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a  cking Levels.**.
5e90: 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f  ** SQLite uses o
5ea0: 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65  ne of these inte
5eb0: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
5ec0: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75  e second.** argu
5ed0: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74  ment to calls it
5ee0: 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c   makes to the xL
5ef0: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63  ock() and xUnloc
5f00: 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f  k() methods.** o
5f10: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f  f an [sqlite3_io
5f20: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
5f30: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
5f40: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20  ITE_LOCK_NONE   
5f50: 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
5f60: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41   SQLITE_LOCK_SHA
5f70: 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65  RED        1.#de
5f80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
5f90: 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32  _RESERVED      2
5fa0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5fb0: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20  LOCK_PENDING    
5fc0: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
5fd0: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
5fe0: 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20  VE     4../*.** 
5ff0: 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72  CAPI3REF: Synchr
6000: 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46  onization Type F
6010: 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  lags.**.** When 
6020: 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74  SQLite invokes t
6030: 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f  he xSync() metho
6040: 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  d of an.** [sqli
6050: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
6060: 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61  object it uses a
6070: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a   combination of.
6080: 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72  ** these integer
6090: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73   values as the s
60a0: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  econd argument..
60b0: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53  **.** When the S
60c0: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
60d0: 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64  NLY flag is used
60e0: 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20  , it means that 
60f0: 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72  the.** sync oper
6100: 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73  ation only needs
6110: 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74   to flush data t
6120: 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20  o mass storage. 
6130: 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d   Inode.** inform
6140: 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62  ation need not b
6150: 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68  e flushed. If th
6160: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74  e lower four bit
6170: 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a  s of the flag.**
6180: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
6190: 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20  NC_NORMAL, that 
61a0: 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72  means to use nor
61b0: 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61  mal fsync() sema
61c0: 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65  ntics..** If the
61d0: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73   lower four bits
61e0: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
61f0: 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65  NC_FULL, that me
6200: 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61  ans.** to use Ma
6210: 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c  c OS X style ful
6220: 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66  lsync instead of
6230: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20   fsync()..**.** 
6240: 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74  Do not confuse t
6250: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  he SQLITE_SYNC_N
6260: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45  ORMAL and SQLITE
6270: 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73  _SYNC_FULL flags
6280: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52  .** with the [PR
6290: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
62a0: 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52  ]=NORMAL and [PR
62b0: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
62c0: 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e  ]=FULL.** settin
62d0: 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72  gs.  The [synchr
62e0: 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65  onous pragma] de
62f0: 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61  termines when ca
6300: 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53  lls to the.** xS
6310: 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f  ync VFS method o
6320: 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73  ccur and applies
6330: 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73   uniformly acros
6340: 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e  s all platforms.
6350: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53  .** The SQLITE_S
6360: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
6370: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
6380: 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20  flags determine 
6390: 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63  how.** energetic
63a0: 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20   or rigorous or 
63b0: 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e  forceful the syn
63c0: 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65  c operations are
63d0: 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b   and.** only mak
63e0: 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f  e a difference o
63f0: 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68  n Mac OSX for th
6400: 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65  e default SQLite
6410: 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64   code..** (Third
6420: 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65  -party VFS imple
6430: 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74  mentations might
6440: 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64   also make the d
6450: 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65  istinction.** be
6460: 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e  tween SQLITE_SYN
6470: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c  C_NORMAL and SQL
6480: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62  ITE_SYNC_FULL, b
6490: 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20  ut among the.** 
64a0: 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
64b0: 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f  s natively suppo
64c0: 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20  rted by SQLite, 
64d0: 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20  only Mac OSX.** 
64e0: 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 20  cares about the 
64f0: 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a  difference.).*/.
6500: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
6510: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20  YNC_NORMAL      
6520: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e    0x00002.#defin
6530: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
6540: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30  LL          0x00
6550: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  003.#define SQLI
6560: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
6570: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f        0x00010../
6580: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
6590: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e  S Interface Open
65a0: 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a   File Handle.**.
65b0: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66  ** An [sqlite3_f
65c0: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72  ile] object repr
65d0: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66  esents an open f
65e0: 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b  ile in the .** [
65f0: 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53  sqlite3_vfs | OS
6600: 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
6610: 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f  ].  Individual O
6620: 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  S interface.** i
6630: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
6640: 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73  ill.** want to s
6650: 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a  ubclass this obj
6660: 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67  ect by appending
6670: 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
6680: 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20  ds.** for their 
6690: 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d  own use.  The pM
66a0: 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20  ethods entry is 
66b0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
66c0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
66d0: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74  ethods] object t
66e0: 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68  hat defines meth
66f0: 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69  ods for performi
6700: 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74  ng.** I/O operat
6710: 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e  ions on the open
6720: 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65   file..*/.typede
6730: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
6740: 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69  _file sqlite3_fi
6750: 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  le;.struct sqlit
6760: 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73  e3_file {.  cons
6770: 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  t struct sqlite3
6780: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65  _io_methods *pMe
6790: 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f  thods;  /* Metho
67a0: 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66  ds for an open f
67b0: 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ile */.};../*.**
67c0: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
67d0: 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72  terface File Vir
67e0: 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a  tual Methods Obj
67f0: 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  ect.**.** Every 
6800: 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74  file opened by t
6810: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
6820: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f  xOpen] method po
6830: 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73  pulates an.** [s
6840: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
6850: 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f  ect (or, more co
6860: 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61  mmonly, a subcla
6870: 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  ss of the.** [sq
6880: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
6890: 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  ct) with a point
68a0: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
68b0: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
68c0: 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
68d0: 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74   defines the met
68e0: 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72  hods used to per
68f0: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65  form various ope
6900: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e  rations.** again
6910: 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  st the open file
6920: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
6930: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
6940: 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  e] object..**.**
6950: 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   If the [sqlite3
6960: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
6970: 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69  od sets the sqli
6980: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
6990: 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f  s element .** to
69a0: 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
69b0: 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71  ter, then the sq
69c0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
69d0: 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a  .xClose method.*
69e0: 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64  * may be invoked
69f0: 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71   even if the [sq
6a00: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
6a10: 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69   reported that i
6a20: 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a  t failed.  The.*
6a30: 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72  * only way to pr
6a40: 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20  event a call to 
6a50: 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67  xClose following
6a60: 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74   a failed [sqlit
6a70: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a  e3_vfs.xOpen].**
6a80: 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c   is for the [sql
6a90: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
6aa0: 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 74  to set the sqlit
6ab0: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
6ac0: 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e   element.** to N
6ad0: 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ULL..**.** The f
6ae0: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
6af0: 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e   xSync may be on
6b00: 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e  e of [SQLITE_SYN
6b10: 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20  C_NORMAL] or.** 
6b20: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c  [SQLITE_SYNC_FUL
6b30: 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63  L].  The first c
6b40: 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72  hoice is the nor
6b50: 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20  mal fsync()..** 
6b60: 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63  The second choic
6b70: 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20  e is a Mac OS X 
6b80: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20  style fullsync. 
6b90: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e   The [SQLITE_SYN
6ba0: 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66  C_DATAONLY].** f
6bb0: 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20  lag may be ORed 
6bc0: 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  in to indicate t
6bd0: 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74  hat only the dat
6be0: 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a  a of the file.**
6bf0: 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f   and not its ino
6c00: 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73  de needs to be s
6c10: 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ynced..**.** The
6c20: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
6c30: 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78  to xLock() and x
6c40: 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65  Unlock() are one
6c50: 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c   of.** <ul>.** <
6c60: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
6c70: 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  _NONE],.** <li> 
6c80: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41  [SQLITE_LOCK_SHA
6c90: 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  RED],.** <li> [S
6ca0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
6cb0: 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  VED],.** <li> [S
6cc0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
6cd0: 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  NG], or.** <li> 
6ce0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
6cf0: 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c  LUSIVE]..** </ul
6d00: 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63  >.** xLock() inc
6d10: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e  reases the lock.
6d20: 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65   xUnlock() decre
6d30: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a  ases the lock..*
6d40: 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65  * The xCheckRese
6d50: 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f  rvedLock() metho
6d60: 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  d checks whether
6d70: 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f   any database co
6d80: 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74  nnection,.** eit
6d90: 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63  her in this proc
6da0: 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f  ess or in some o
6db0: 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73  ther process, is
6dc0: 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52   holding a RESER
6dd0: 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c  VED,.** PENDING,
6de0: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f   or EXCLUSIVE lo
6df0: 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20  ck on the file. 
6e00: 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65   It returns true
6e10: 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f  .** if such a lo
6e20: 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61  ck exists and fa
6e30: 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a  lse otherwise..*
6e40: 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f  *.** The xFileCo
6e50: 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69  ntrol() method i
6e60: 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65  s a generic inte
6e70: 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77  rface that allow
6e80: 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20  s custom.** VFS 
6e90: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
6ea0: 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74  to directly cont
6eb0: 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  rol an open file
6ec0: 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
6ed0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
6ee0: 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65  rol()] interface
6ef0: 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f  .  The second "o
6f00: 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  p" argument is a
6f10: 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63  n.** integer opc
6f20: 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20  ode.  The third 
6f30: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65  argument is a ge
6f40: 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e  neric pointer in
6f50: 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69  tended to.** poi
6f60: 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72  nt to a structur
6f70: 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61  e that may conta
6f80: 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  in arguments or 
6f90: 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74  space in which t
6fa0: 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72  o.** write retur
6fb0: 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e  n values.  Poten
6fc0: 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46  tial uses for xF
6fd0: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67  ileControl() mig
6fe0: 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  ht be.** functio
6ff0: 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f  ns to enable blo
7000: 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68  cking locks with
7010: 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68   timeouts, to ch
7020: 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b  ange the.** lock
7030: 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f  ing strategy (fo
7040: 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65  r example to use
7050: 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29   dot-file locks)
7060: 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20  , to inquire.** 
7070: 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73  about the status
7080: 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74   of a lock, or t
7090: 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f  o break stale lo
70a0: 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65  cks.  The SQLite
70b0: 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65  .** core reserve
70c0: 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65  s all opcodes le
70d0: 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20  ss than 100 for 
70e0: 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20  its own use..** 
70f0: 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  A [SQLITE_FCNTL_
7100: 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 74  LOCKSTATE | list
7110: 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73   of opcodes] les
7120: 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76  s than 100 is av
7130: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c  ailable..** Appl
7140: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65  ications that de
7150: 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46  fine a custom xF
7160: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
7170: 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63  d should use opc
7180: 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20  odes.** greater 
7190: 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69  than 100 to avoi
71a0: 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46  d conflicts.  VF
71b0: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
71c0: 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  s should.** retu
71d0: 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  rn [SQLITE_NOTFO
71e0: 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f  UND] for file co
71f0: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68  ntrol opcodes th
7200: 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a  at they do not.*
7210: 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a  * recognize..**.
7220: 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69  ** The xSectorSi
7230: 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75  ze() method retu
7240: 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73  rns the sector s
7250: 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65  ize of the.** de
7260: 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c  vice that underl
7270: 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54  ies the file.  T
7280: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69  he sector size i
7290: 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d  s the.** minimum
72a0: 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20   write that can 
72b0: 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74  be performed wit
72c0: 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a  hout disturbing.
72d0: 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69  ** other bytes i
72e0: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65  n the file.  The
72f0: 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65   xDeviceCharacte
7300: 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74  ristics().** met
7310: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69  hod returns a bi
7320: 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62  t vector describ
7330: 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66  ing behaviors of
7340: 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69   the.** underlyi
7350: 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a  ng device:.**.**
7360: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
7370: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7380: 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  IC].** <li> [SQL
7390: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
73a0: 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  512].** <li> [SQ
73b0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
73c0: 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C1K].** <li> [SQ
73d0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
73e0: 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C2K].** <li> [SQ
73f0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7400: 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C4K].** <li> [SQ
7410: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7420: 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C8K].** <li> [SQ
7430: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7440: 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C16K].** <li> [S
7450: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7460: 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC32K].** <li> [
7470: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7480: 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC64K].** <li> 
7490: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41  [SQLITE_IOCAP_SA
74a0: 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c  FE_APPEND].** <l
74b0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
74c0: 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20  _SEQUENTIAL].** 
74d0: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
74e0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
74f0: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
7500: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74  ns that all writ
7510: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a  es of.** any siz
7520: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  e are atomic.  T
7530: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
7540: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73  ATOMICnnn values
7550: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72  .** mean that wr
7560: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74  ites of blocks t
7570: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65  hat are nnn byte
7580: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a  s in size and.**
7590: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20   are aligned to 
75a0: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68  an address which
75b0: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d   is an integer m
75c0: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e  ultiple of.** nn
75d0: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  n are atomic.  T
75e0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
75f0: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75  SAFE_APPEND valu
7600: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  e means.** that 
7610: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70  when data is app
7620: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c  ended to a file,
7630: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70   the data is app
7640: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74  ended.** first t
7650: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  hen the size of 
7660: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65  the file is exte
7670: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20  nded, never the 
7680: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f  other.** way aro
7690: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  und.  The SQLITE
76a0: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
76b0: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  L property means
76c0: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61   that.** informa
76d0: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20  tion is written 
76e0: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73  to disk in the s
76f0: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c  ame order as cal
7700: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28  ls.** to xWrite(
7710: 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61  )..**.** If xRea
7720: 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49  d() returns SQLI
7730: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
7740: 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f  EAD it must also
7750: 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20   fill.** in the 
7760: 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20  unread portions 
7770: 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 77 69  of the buffer wi
7780: 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53  th zeros.  A VFS
7790: 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74   that.** fails t
77a0: 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72  o zero-fill shor
77b0: 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 73 65  t reads might se
77c0: 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77  em to work.  How
77d0: 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65  ever,.** failure
77e0: 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68   to zero-fill sh
77f0: 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65  ort reads will e
7800: 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74  ventually lead t
7810: 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  o.** database co
7820: 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70  rruption..*/.typ
7830: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
7840: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73  te3_io_methods s
7850: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7860: 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  s;.struct sqlite
7870: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20  3_io_methods {. 
7880: 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20   int iVersion;. 
7890: 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73   int (*xClose)(s
78a0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
78b0: 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71   int (*xRead)(sq
78c0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69  lite3_file*, voi
78d0: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
78e0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
78f0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69  t);.  int (*xWri
7900: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  te)(sqlite3_file
7910: 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
7920: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65  int iAmt, sqlite
7930: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a  3_int64 iOfst);.
7940: 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74    int (*xTruncat
7950: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
7960: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
7970: 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78  size);.  int (*x
7980: 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69  Sync)(sqlite3_fi
7990: 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b  le*, int flags);
79a0: 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69  .  int (*xFileSi
79b0: 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ze)(sqlite3_file
79c0: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
79d0: 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20   *pSize);.  int 
79e0: 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33  (*xLock)(sqlite3
79f0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20  _file*, int);.  
7a00: 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73  int (*xUnlock)(s
7a10: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
7a20: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65  t);.  int (*xChe
7a30: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28  ckReservedLock)(
7a40: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
7a50: 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20  nt *pResOut);.  
7a60: 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72  int (*xFileContr
7a70: 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ol)(sqlite3_file
7a80: 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20  *, int op, void 
7a90: 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a  *pArg);.  int (*
7aa0: 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c  xSectorSize)(sql
7ab0: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69  ite3_file*);.  i
7ac0: 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72  nt (*xDeviceChar
7ad0: 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c  acteristics)(sql
7ae0: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f  ite3_file*);.  /
7af0: 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  * Methods above 
7b00: 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65  are valid for ve
7b10: 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74  rsion 1 */.  int
7b20: 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c 69   (*xShmMap)(sqli
7b30: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69  te3_file*, int i
7b40: 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e  Pg, int pgsz, in
7b50: 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65  t, void volatile
7b60: 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68  **);.  int (*xSh
7b70: 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  mLock)(sqlite3_f
7b80: 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74  ile*, int offset
7b90: 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61  , int n, int fla
7ba0: 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53  gs);.  void (*xS
7bb0: 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69 74  hmBarrier)(sqlit
7bc0: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
7bd0: 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 71   (*xShmUnmap)(sq
7be0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
7bf0: 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20   deleteFlag);.  
7c00: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65  /* Methods above
7c10: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76   are valid for v
7c20: 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 2f 2a  ersion 2 */.  /*
7c30: 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68   Additional meth
7c40: 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ods may be added
7c50: 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
7c60: 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ses */.};../*.**
7c70: 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64   CAPI3REF: Stand
7c80: 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c  ard File Control
7c90: 20 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54   Opcodes.**.** T
7ca0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
7cb0: 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64  stants are opcod
7cc0: 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65  es for the xFile
7cd0: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a  Control method.*
7ce0: 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
7cf0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
7d00: 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65  ject and for the
7d10: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
7d20: 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74  ontrol()].** int
7d30: 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  erface..**.** Th
7d40: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
7d50: 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64  LOCKSTATE] opcod
7d60: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65  e is used for de
7d70: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a  bugging.  This.*
7d80: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  * opcode causes 
7d90: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
7da0: 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65   method to write
7db0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
7dc0: 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63  te of.** the loc
7dd0: 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  k (one of [SQLIT
7de0: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53  E_LOCK_NONE], [S
7df0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
7e00: 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c  D],.** [SQLITE_L
7e10: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b  OCK_RESERVED], [
7e20: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
7e30: 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ING], or [SQLITE
7e40: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d  _LOCK_EXCLUSIVE]
7e50: 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74  ).** into an int
7e60: 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41  eger that the pA
7e70: 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  rg argument poin
7e80: 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61  ts to. This capa
7e90: 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65  bility.** is use
7ea0: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
7eb0: 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20   and only needs 
7ec0: 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20  to be supported 
7ed0: 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54  when SQLITE_TEST
7ee0: 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a  .** is defined..
7ef0: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
7f00: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e  E_FCNTL_SIZE_HIN
7f10: 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  T] opcode is use
7f20: 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67  d by SQLite to g
7f30: 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c  ive the VFS.** l
7f40: 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68  ayer a hint of h
7f50: 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64 61 74  ow large the dat
7f60: 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20  abase file will 
7f70: 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e  grow to be durin
7f80: 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  g the.** current
7f90: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54   transaction.  T
7fa0: 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20  his hint is not 
7fb0: 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65  guaranteed to be
7fc0: 20 61 63 63 75 72 61 74 65 20 62 75 74 20 69 74   accurate but it
7fd0: 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f  .** is often clo
7fe0: 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79  se.  The underly
7ff0: 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63 68  ing VFS might ch
8000: 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63  oose to prealloc
8010: 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  ate database.** 
8020: 66 69 6c 65 20 73 70 61 63 65 20 62 61 73 65 64  file space based
8030: 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e   on this hint in
8040: 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77   order to help w
8050: 72 69 74 65 73 20 74 6f 20 74 68 65 20 64 61 74  rites to the dat
8060: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75  abase.** file ru
8070: 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  n faster..**.** 
8080: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
8090: 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70  L_CHUNK_SIZE] op
80a0: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
80b0: 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68 65  request that the
80c0: 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20   VFS.** extends 
80d0: 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74 68  and truncates th
80e0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
80f0: 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20 73  in chunks of a s
8100: 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  ize specified.**
8110: 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54 68   by the user. Th
8120: 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
8130: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69  t to [sqlite3_fi
8140: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68  le_control()] sh
8150: 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74  ould .** point t
8160: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74 79  o an integer (ty
8170: 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69  pe int) containi
8180: 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e 6b  ng the new chunk
8190: 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20  -size to use.** 
81a0: 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65  for the nominate
81b0: 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f  d database. Allo
81c0: 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  cating database 
81d0: 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c 61  file space in la
81e0: 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73  rge.** chunks (s
81f0: 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d 65  ay 1MB at a time
8200: 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66 69  ), may reduce fi
8210: 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d 65  le-system fragme
8220: 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69  ntation and.** i
8230: 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e  mprove performan
8240: 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65  ce on some syste
8250: 6d 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  ms..**.** The [S
8260: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45  QLITE_FCNTL_FILE
8270: 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65  _POINTER] opcode
8280: 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61   is used to obta
8290: 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  in a pointer.** 
82a0: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
82b0: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73  file] object ass
82c0: 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 70  ociated with a p
82d0: 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61  articular databa
82e0: 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
82f0: 2e 20 20 53 65 65 20 74 68 65 20 5b 73 71 6c 69  .  See the [sqli
8300: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
8310: 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  ()] documentatio
8320: 6e 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f  n for.** additio
8330: 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
8340: 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51  .**.** ^(The [SQ
8350: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f  LITE_FCNTL_SYNC_
8360: 4f 4d 49 54 54 45 44 5d 20 6f 70 63 6f 64 65 20  OMITTED] opcode 
8370: 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74  is generated int
8380: 65 72 6e 61 6c 6c 79 20 62 79 0a 2a 2a 20 53 51  ernally by.** SQ
8390: 4c 69 74 65 20 61 6e 64 20 73 65 6e 74 20 74 6f  Lite and sent to
83a0: 20 61 6c 6c 20 56 46 53 65 73 20 69 6e 20 70 6c   all VFSes in pl
83b0: 61 63 65 20 6f 66 20 61 20 63 61 6c 6c 20 74 6f  ace of a call to
83c0: 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f   the xSync metho
83d0: 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 64 61  d.** when the da
83e0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
83f0: 6e 20 68 61 73 20 5b 50 52 41 47 4d 41 20 73 79  n has [PRAGMA sy
8400: 6e 63 68 72 6f 6e 6f 75 73 5d 20 73 65 74 20 74  nchronous] set t
8410: 6f 20 4f 46 46 2e 29 5e 0a 2a 2a 20 53 6f 6d 65  o OFF.)^.** Some
8420: 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53   specialized VFS
8430: 65 73 20 6e 65 65 64 20 74 68 69 73 20 73 69 67  es need this sig
8440: 6e 61 6c 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  nal in order to 
8450: 6f 70 65 72 61 74 65 20 63 6f 72 72 65 63 74 6c  operate correctl
8460: 79 0a 2a 2a 20 77 68 65 6e 20 5b 50 52 41 47 4d  y.** when [PRAGM
8470: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20  A synchronous | 
8480: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
8490: 75 73 3d 4f 46 46 5d 20 69 73 20 73 65 74 2c 20  us=OFF] is set, 
84a0: 62 75 74 20 6d 6f 73 74 20 0a 2a 2a 20 56 46 53  but most .** VFS
84b0: 65 73 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74  es do not need t
84c0: 68 69 73 20 73 69 67 6e 61 6c 20 61 6e 64 20 73  his signal and s
84d0: 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69  hould silently i
84e0: 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64  gnore this opcod
84f0: 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  e..** Applicatio
8500: 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61  ns should not ca
8510: 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ll [sqlite3_file
8520: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68  _control()] with
8530: 20 74 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20   this.** opcode 
8540: 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20  as doing so may 
8550: 64 69 73 72 75 70 74 20 74 68 65 20 6f 70 65 72  disrupt the oper
8560: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65  ation of the spe
8570: 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 0a 2a  cialized VFSes.*
8580: 2a 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72  * that do requir
8590: 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54  e it.  .**.** ^T
85a0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
85b0: 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d  _WIN32_AV_RETRY]
85c0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
85d0: 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 61 75 74  to configure aut
85e0: 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74 72 79 20  omatic.** retry 
85f0: 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e 74 65 72  counts and inter
8600: 76 61 6c 73 20 66 6f 72 20 63 65 72 74 61 69 6e  vals for certain
8610: 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74   disk I/O operat
8620: 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20  ions for the.** 
8630: 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e  windows [VFS] in
8640: 20 6f 72 64 65 72 20 74 6f 20 77 6f 72 6b 20 74   order to work t
8650: 6f 20 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74  o provide robust
8660: 6e 65 73 73 20 61 67 61 69 6e 73 74 0a 2a 2a 20  ness against.** 
8670: 61 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72  anti-virus progr
8680: 61 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74  ams.  By default
8690: 2c 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46  , the windows VF
86a0: 53 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c  S will retry fil
86b0: 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20  e read,.** file 
86c0: 77 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20  write, and file 
86d0: 64 65 6c 65 74 65 20 6f 70 65 72 74 69 6f 6e 73  delete opertions
86e0: 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c   up to 10 times,
86f0: 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a   with a delay.**
8700: 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f   of 25 milliseco
8710: 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66  nds before the f
8720: 69 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77  irst retry and w
8730: 69 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e  ith the delay in
8740: 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61  creasing.** by a
8750: 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20  n additional 25 
8760: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74  milliseconds wit
8770: 68 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e  h each subsequen
8780: 74 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a  t retry.  This.*
8790: 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20  * opcode allows 
87a0: 74 68 6f 73 65 20 74 6f 20 76 61 6c 75 65 73 20  those to values 
87b0: 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 20  (10 retries and 
87c0: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  25 milliseconds 
87d0: 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20  of delay).** to 
87e0: 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68  be adjusted.  Th
87f0: 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 61  e values are cha
8800: 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74  nged for all dat
8810: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
8820: 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20  s.** within the 
8830: 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54  same process.  T
8840: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  he argument is a
8850: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61   pointer to an a
8860: 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69  rray of two.** i
8870: 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74 68  ntegers where th
8880: 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 20  e first integer 
8890: 69 20 74 68 65 20 6e 65 77 20 72 65 74 72 79 20  i the new retry 
88a0: 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65  count and the se
88b0: 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  cond.** integer 
88c0: 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49  is the delay.  I
88d0: 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65 72  f either integer
88e0: 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
88f0: 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a  en the setting.*
8900: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  * is not changed
8910: 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68 65   but instead the
8920: 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
8930: 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73 20  that setting is 
8940: 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20  written.** into 
8950: 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c  the array entry,
8960: 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75   allowing the cu
8970: 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74 74  rrent retry sett
8980: 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e  ings to be.** in
8990: 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65  terrogated.  The
89a0: 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74   zDbName paramet
89b0: 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a  er is ignored..*
89c0: 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  *.** ^The [SQLIT
89d0: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
89e0: 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  WAL] opcode is u
89f0: 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75  sed to set or qu
8a00: 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69  ery the.** persi
8a10: 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69  stent [WAL | Wri
8a20: 74 65 20 41 48 65 61 64 20 4c 6f 67 5d 20 73 65  te AHead Log] se
8a30: 74 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61 75  tting.  By defau
8a40: 6c 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61 72  lt, the auxiliar
8a50: 79 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61 64  y.** write ahead
8a60: 20 6c 6f 67 20 61 6e 64 20 73 68 61 72 65 64 20   log and shared 
8a70: 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 75 73 65  memory files use
8a80: 64 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69 6f  d for transactio
8a90: 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65  n control.** are
8aa0: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64   automatically d
8ab0: 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 20  eleted when the 
8ac0: 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f  latest connectio
8ad0: 6e 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  n to the databas
8ae0: 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65  e.** closes.  Se
8af0: 74 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e 74  tting persistent
8b00: 20 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 73   WAL mode causes
8b10: 20 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f 20   those files to 
8b20: 70 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a 2a  persist after.**
8b30: 20 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 74   close.  Persist
8b40: 69 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69 73  ing the files is
8b50: 20 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 68   useful when oth
8b60: 65 72 20 70 72 6f 63 65 73 73 65 73 20 74 68 61  er processes tha
8b70: 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65  t do not.** have
8b80: 20 77 72 69 74 65 20 70 65 72 6d 69 73 73 69 6f   write permissio
8b90: 6e 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74 6f  n on the directo
8ba0: 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ry containing th
8bb0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
8bc0: 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20  want.** to read 
8bd0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
8be0: 65 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61 6e  e, as the WAL an
8bf0: 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20  d shared memory 
8c00: 66 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73 74  files must exist
8c10: 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f 72  .** in order for
8c20: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74 6f   the database to
8c30: 20 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20 54   be readable.  T
8c40: 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
8c50: 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ter to.** [sqlit
8c60: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
8c70: 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f  )] for this opco
8c80: 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70  de should be a p
8c90: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
8ca0: 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e  eger..** That in
8cb0: 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69  teger is 0 to di
8cc0: 73 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74  sable persistent
8cd0: 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74   WAL mode or 1 t
8ce0: 6f 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73 74  o enable persist
8cf0: 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e  ent.** WAL mode.
8d00: 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72    If the integer
8d10: 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20   is -1, then it 
8d20: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77  is overwritten w
8d30: 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a  ith the current.
8d40: 2a 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65 6e  ** WAL persisten
8d50: 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a  ce setting..**.*
8d60: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
8d70: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20  CNTL_OVERWRITE] 
8d80: 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65  opcode is invoke
8d90: 64 20 62 79 20 53 51 4c 69 74 65 20 61 66 74 65  d by SQLite afte
8da0: 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77  r opening.** a w
8db0: 72 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  rite transaction
8dc0: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
8dd0: 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73 20  t, unless it is 
8de0: 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72 20  rolled back for 
8df0: 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20  some.** reason, 
8e00: 74 68 65 20 65 6e 74 69 72 65 20 64 61 74 61 62  the entire datab
8e10: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62 65  ase file will be
8e20: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79 20   overwritten by 
8e30: 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20  the current .** 
8e40: 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69  transaction. Thi
8e50: 73 20 69 73 20 75 73 65 64 20 62 79 20 56 41 43  s is used by VAC
8e60: 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a  UUM operations..
8e70: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
8e80: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
8e90: 45 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69  E        1.#defi
8ea0: 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f  ne SQLITE_GET_LO
8eb0: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20  CKPROXYFILE     
8ec0: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
8ed0: 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  E_SET_LOCKPROXYF
8ee0: 49 4c 45 20 20 20 20 20 20 33 0a 23 64 65 66 69  ILE      3.#defi
8ef0: 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45  ne SQLITE_LAST_E
8f00: 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20  RRNO            
8f10: 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
8f20: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e  E_FCNTL_SIZE_HIN
8f30: 54 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69  T        5.#defi
8f40: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
8f50: 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20  CHUNK_SIZE      
8f60: 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   6.#define SQLIT
8f70: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49  E_FCNTL_FILE_POI
8f80: 4e 54 45 52 20 20 20 20 20 37 0a 23 64 65 66 69  NTER     7.#defi
8f90: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
8fa0: 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20  SYNC_OMITTED    
8fb0: 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   8.#define SQLIT
8fc0: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56  E_FCNTL_WIN32_AV
8fd0: 5f 52 45 54 52 59 20 20 20 39 0a 23 64 65 66 69  _RETRY   9.#defi
8fe0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
8ff0: 50 45 52 53 49 53 54 5f 57 41 4c 20 20 20 20 20  PERSIST_WAL     
9000: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
9010: 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54  E_FCNTL_OVERWRIT
9020: 45 20 20 20 20 20 20 20 31 31 0a 0a 2f 2a 0a 2a  E       11../*.*
9030: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65  * CAPI3REF: Mute
9040: 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54  x Handle.**.** T
9050: 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20  he mutex module 
9060: 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65  within SQLite de
9070: 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d  fines [sqlite3_m
9080: 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a  utex] to be an.*
9090: 2a 20 61 62 73 74 72 61 63 74 20 74 79 70 65 20  * abstract type 
90a0: 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65  for a mutex obje
90b0: 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20  ct.  The SQLite 
90c0: 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73  core never looks
90d0: 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72  .** at the inter
90e0: 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69  nal representati
90f0: 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65  on of an [sqlite
9100: 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e  3_mutex].  It on
9110: 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68  ly.** deals with
9120: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65   pointers to the
9130: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d   [sqlite3_mutex]
9140: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d   object..**.** M
9150: 75 74 65 78 65 73 20 61 72 65 20 63 72 65 61 74  utexes are creat
9160: 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
9170: 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d  3_mutex_alloc()]
9180: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
9190: 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  uct sqlite3_mute
91a0: 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b  x sqlite3_mutex;
91b0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
91c0: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f  : OS Interface O
91d0: 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  bject.**.** An i
91e0: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73  nstance of the s
91f0: 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63  qlite3_vfs objec
9200: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e  t defines the in
9210: 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a  terface between.
9220: 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f  ** the SQLite co
9230: 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72  re and the under
9240: 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20  lying operating 
9250: 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66  system.  The "vf
9260: 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d  s".** in the nam
9270: 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20  e of the object 
9280: 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74  stands for "virt
9290: 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22  ual file system"
92a0: 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56  .  See.** the [V
92b0: 46 53 20 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e  FS | VFS documen
92c0: 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74  tation] for furt
92d0: 68 65 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  her information.
92e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65  .**.** The value
92f0: 20 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e   of the iVersion
9300: 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61   field is initia
9310: 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65  lly 1 but may be
9320: 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75   larger in.** fu
9330: 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
9340: 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69   SQLite.  Additi
9350: 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20  onal fields may 
9360: 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74  be appended to t
9370: 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68  his.** object wh
9380: 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  en the iVersion 
9390: 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73  value is increas
93a0: 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74  ed.  Note that t
93b0: 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20  he structure.** 
93c0: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  of the sqlite3_v
93d0: 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65  fs object change
93e0: 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63  s in the transac
93f0: 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20  tion between.** 
9400: 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
9410: 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61  .5.9 and 3.6.0 a
9420: 6e 64 20 79 65 74 20 74 68 65 20 69 56 65 72 73  nd yet the iVers
9430: 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f  ion field was no
9440: 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a  t.** modified..*
9450: 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c  *.** The szOsFil
9460: 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73  e field is the s
9470: 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c  ize of the subcl
9480: 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66  assed [sqlite3_f
9490: 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72  ile].** structur
94a0: 65 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56  e used by this V
94b0: 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20  FS.  mxPathname 
94c0: 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c  is the maximum l
94d0: 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61  ength of.** a pa
94e0: 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56  thname in this V
94f0: 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74  FS..**.** Regist
9500: 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73  ered sqlite3_vfs
9510: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70   objects are kep
9520: 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69  t on a linked li
9530: 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20  st formed by.** 
9540: 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65  the pNext pointe
9550: 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  r.  The [sqlite3
9560: 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d  _vfs_register()]
9570: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
9580: 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28  _vfs_unregister(
9590: 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61  )] interfaces ma
95a0: 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a  nage this list.*
95b0: 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61  * in a thread-sa
95c0: 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71  fe way.  The [sq
95d0: 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29  lite3_vfs_find()
95e0: 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73  ] interface.** s
95f0: 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74  earches the list
9600: 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61  .  Neither the a
9610: 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20  pplication code 
9620: 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69  nor the VFS.** i
9630: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68  mplementation sh
9640: 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65  ould use the pNe
9650: 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  xt pointer..**.*
9660: 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c  * The pNext fiel
9670: 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69  d is the only fi
9680: 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74  eld in the sqlit
9690: 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74  e3_vfs.** struct
96a0: 75 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20  ure that SQLite 
96b0: 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79  will ever modify
96c0: 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f  .  SQLite will o
96d0: 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72  nly access.** or
96e0: 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65   modify this fie
96f0: 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67  ld while holding
9700: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74   a particular st
9710: 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54  atic mutex..** T
9720: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
9730: 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69  hould never modi
9740: 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68  fy anything with
9750: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  in the sqlite3_v
9760: 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63  fs.** object onc
9770: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73  e the object has
9780: 20 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64   been registered
9790: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d  ..**.** The zNam
97a0: 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68  e field holds th
97b0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46  e name of the VF
97c0: 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e  S module.  The n
97d0: 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75  ame must.** be u
97e0: 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c  nique across all
97f0: 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a   VFS modules..**
9800: 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66  .** [[sqlite3_vf
9810: 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51  s.xOpen]].** ^SQ
9820: 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20  Lite guarantees 
9830: 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61  that the zFilena
9840: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  me parameter to 
9850: 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68  xOpen.** is eith
9860: 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  er a NULL pointe
9870: 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61  r or string obta
9880: 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75  ined.** from xFu
9890: 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74  llPathname() wit
98a0: 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75  h an optional su
98b0: 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e  ffix added..** ^
98c0: 49 66 20 61 20 73 75 66 66 69 78 20 69 73 20 61  If a suffix is a
98d0: 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c  dded to the zFil
98e0: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c  ename parameter,
98f0: 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73   it will.** cons
9900: 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20  ist of a single 
9910: 22 2d 22 20 63 68 61 72 61 63 74 65 72 20 66 6f  "-" character fo
9920: 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72  llowed by no mor
9930: 65 20 74 68 61 6e 0a 2a 2a 20 31 30 20 61 6c 70  e than.** 10 alp
9940: 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72  hanumeric and/or
9950: 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e   "-" characters.
9960: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74  .** ^SQLite furt
9970: 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20 74  her guarantees t
9980: 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  hat.** the strin
9990: 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20  g will be valid 
99a0: 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e  and unchanged un
99b0: 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a  til xClose() is.
99c0: 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75  ** called. Becau
99d0: 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f  se of the previo
99e0: 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20  us sentence,.** 
99f0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
9a00: 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74  e] can safely st
9a10: 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ore a pointer to
9a20: 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65   the.** filename
9a30: 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20   if it needs to 
9a40: 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c  remember the fil
9a50: 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72  ename for some r
9a60: 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65  eason..** If the
9a70: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   zFilename param
9a80: 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73  eter to xOpen is
9a90: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
9aa0: 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75  then xOpen.** mu
9ab0: 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77  st invent its ow
9ac0: 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65  n temporary name
9ad0: 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20   for the file.  
9ae0: 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a  ^Whenever the .*
9af0: 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  * xFilename para
9b00: 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74  meter is NULL it
9b10: 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68   will also be th
9b20: 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 0a  e case that the.
9b30: 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  ** flags paramet
9b40: 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20  er will include 
9b50: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
9b60: 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a  ETEONCLOSE]..**.
9b70: 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67  ** The flags arg
9b80: 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29  ument to xOpen()
9b90: 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69   includes all bi
9ba0: 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65  ts set in.** the
9bb0: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
9bc0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
9bd0: 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b  _v2()].  Or if [
9be0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a  sqlite3_open()].
9bf0: 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  ** or [sqlite3_o
9c00: 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64  pen16()] is used
9c10: 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63  , then flags inc
9c20: 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a  ludes at least.*
9c30: 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  * [SQLITE_OPEN_R
9c40: 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c  EADWRITE] | [SQL
9c50: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
9c60: 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29  . .** If xOpen()
9c70: 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65   opens a file re
9c80: 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20  ad-only then it 
9c90: 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20  sets *pOutFlags 
9ca0: 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53  to.** include [S
9cb0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
9cc0: 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74  NLY].  Other bit
9cd0: 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20  s in *pOutFlags 
9ce0: 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a  may be set..**.*
9cf0: 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20  * ^(SQLite will 
9d00: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20  also add one of 
9d10: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c  the following fl
9d20: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ags to the xOpen
9d30: 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65  ().** call, depe
9d40: 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a  nding on the obj
9d50: 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64  ect being opened
9d60: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
9d70: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
9d80: 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c  EN_MAIN_DB].** <
9d90: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
9da0: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_MAIN_JOURNAL].
9db0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
9dc0: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a  _OPEN_TEMP_DB].*
9dd0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
9de0: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
9df0: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
9e00: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45  ITE_OPEN_TRANSIE
9e10: 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  NT_DB].** <li>  
9e20: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42  [SQLITE_OPEN_SUB
9e30: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
9e40: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
9e50: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  ASTER_JOURNAL].*
9e60: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
9e70: 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75  OPEN_WAL].** </u
9e80: 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  l>)^.**.** The f
9e90: 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e  ile I/O implemen
9ea0: 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74  tation can use t
9eb0: 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66  he object type f
9ec0: 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67  lags to.** chang
9ed0: 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65 61  e the way it dea
9ee0: 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20  ls with files.  
9ef0: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20  For example, an 
9f00: 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74  application.** t
9f10: 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72  hat does not car
9f20: 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 65  e about crash re
9f30: 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61  covery or rollba
9f40: 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a  ck might make.**
9f50: 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a   the open of a j
9f60: 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f  ournal file a no
9f70: 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20  -op.  Writes to 
9f80: 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75  this journal wou
9f90: 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f  ld.** also be no
9fa0: 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74  -ops, and any at
9fb0: 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68  tempt to read th
9fc0: 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20  e journal would 
9fd0: 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45  return.** SQLITE
9fe0: 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20  _IOERR.  Or the 
9ff0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d  implementation m
a000: 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74  ight recognize t
a010: 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a  hat a database.*
a020: 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64  * file will be d
a030: 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65  oing page-aligne
a040: 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61  d sector reads a
a050: 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72  nd writes in a r
a060: 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61  andom.** order a
a070: 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f  nd set up its I/
a080: 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f  O subsystem acco
a090: 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53  rdingly..**.** S
a0a0: 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f  QLite might also
a0b0: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20   add one of the 
a0c0: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20  following flags 
a0d0: 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74  to the xOpen met
a0e0: 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  hod:.**.** <ul>.
a0f0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
a100: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
a110: 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  SE].** <li> [SQL
a120: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
a130: 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  VE].** </ul>.**.
a140: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ** The [SQLITE_O
a150: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
a160: 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68  E] flag means th
a170: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65  e file should be
a180: 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e  .** deleted when
a190: 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20   it is closed.  
a1a0: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ^The [SQLITE_OPE
a1b0: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
a1c0: 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20  .** will be set 
a1d0: 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61 73  for TEMP databas
a1e0: 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75  es and their jou
a1f0: 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74  rnals, transient
a200: 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61  .** databases, a
a210: 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a  nd subjournals..
a220: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  **.** ^The [SQLI
a230: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
a240: 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79  E] flag is alway
a250: 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e  s used in conjun
a260: 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68  ction.** with th
a270: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  e [SQLITE_OPEN_C
a280: 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69  REATE] flag, whi
a290: 63 68 20 61 72 65 20 62 6f 74 68 20 64 69 72 65  ch are both dire
a2a0: 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75  ctly.** analogou
a2b0: 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20  s to the O_EXCL 
a2c0: 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67  and O_CREAT flag
a2d0: 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f  s of the POSIX o
a2e0: 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54  pen().** API.  T
a2f0: 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  he SQLITE_OPEN_E
a300: 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77  XCLUSIVE flag, w
a310: 68 65 6e 20 70 61 69 72 65 64 20 77 69 74 68 20  hen paired with 
a320: 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f  the .** SQLITE_O
a330: 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75  PEN_CREATE, is u
a340: 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20  sed to indicate 
a350: 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64  that file should
a360: 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72   always.** be cr
a370: 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20  eated, and that 
a380: 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69  it is an error i
a390: 66 20 69 74 20 61 6c 72 65 61 64 79 20 65 78 69  f it already exi
a3a0: 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69  sts..** It is <i
a3b0: 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f  >not</i> used to
a3c0: 20 69 6e 64 69 63 61 74 65 20 74 68 65 20 66 69   indicate the fi
a3d0: 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65  le should be ope
a3e0: 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c  ned .** for excl
a3f0: 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a  usive access..**
a400: 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a  .** ^At least sz
a410: 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20  OsFile bytes of 
a420: 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63  memory are alloc
a430: 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a  ated by SQLite.*
a440: 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b  * to hold the  [
a450: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74  sqlite3_file] st
a460: 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20 61  ructure passed a
a470: 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61  s the third.** a
a480: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e  rgument to xOpen
a490: 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74  .  The xOpen met
a4a0: 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76  hod does not hav
a4b0: 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  e to.** allocate
a4c0: 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b 20   the structure; 
a4d0: 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66  it should just f
a4e0: 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65  ill it in.  Note
a4f0: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70   that.** the xOp
a500: 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73  en method must s
a510: 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  et the sqlite3_f
a520: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20  ile.pMethods to 
a530: 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69  either.** a vali
a540: 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  d [sqlite3_io_me
a550: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72  thods] object or
a560: 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e   to NULL.  xOpen
a570: 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73   must do.** this
a580: 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65   even if the ope
a590: 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65  n fails.  SQLite
a5a0: 20 65 78 70 65 63 74 73 20 74 68 61 74 20 74 68   expects that th
a5b0: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
a5c0: 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65  Methods.** eleme
a5d0: 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64  nt will be valid
a5e0: 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74   after xOpen ret
a5f0: 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20  urns regardless 
a600: 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a  of the success.*
a610: 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20  * or failure of 
a620: 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a  the xOpen call..
a630: 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f  **.** [[sqlite3_
a640: 76 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a  vfs.xAccess]].**
a650: 20 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67 75   ^The flags argu
a660: 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28  ment to xAccess(
a670: 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45  ) may be [SQLITE
a680: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a  _ACCESS_EXISTS].
a690: 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74  ** to test for t
a6a0: 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20  he existence of 
a6b0: 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49  a file, or [SQLI
a6c0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
a6d0: 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20  ITE] to.** test 
a6e0: 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69  whether a file i
a6f0: 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77  s readable and w
a700: 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c  ritable, or [SQL
a710: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d  ITE_ACCESS_READ]
a720: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74  .** to test whet
a730: 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61 74  her a file is at
a740: 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e   least readable.
a750: 20 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20     The file can 
a760: 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72  be a.** director
a770: 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  y..**.** ^SQLite
a780: 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c   will always all
a790: 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d  ocate at least m
a7a0: 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65  xPathname+1 byte
a7b0: 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74  s for the.** out
a7c0: 70 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c  put buffer xFull
a7d0: 50 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65  Pathname.  The e
a7e0: 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65  xact size of the
a7f0: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a   output buffer.*
a800: 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64  * is also passed
a810: 20 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20   as a parameter 
a820: 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73  to both  methods
a830: 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20  . If the output 
a840: 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74  buffer.** is not
a850: 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b   large enough, [
a860: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d  SQLITE_CANTOPEN]
a870: 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72   should be retur
a880: 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20  ned. Since this 
a890: 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73  is.** handled as
a8a0: 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62   a fatal error b
a8b0: 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d  y SQLite, vfs im
a8c0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68  plementations sh
a8d0: 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a  ould endeavor.**
a8e0: 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73   to prevent this
a8f0: 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61   by setting mxPa
a900: 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66  thname to a suff
a910: 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76  iciently large v
a920: 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alue..**.** The 
a930: 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78  xRandomness(), x
a940: 53 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e  Sleep(), xCurren
a950: 74 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75  tTime(), and xCu
a960: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
a970: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61  .** interfaces a
a980: 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  re not strictly 
a990: 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66 69  a part of the fi
a9a0: 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68  lesystem, but th
a9b0: 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64  ey are.** includ
a9c0: 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73 74  ed in the VFS st
a9d0: 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70  ructure for comp
a9e0: 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65  leteness..** The
a9f0: 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66   xRandomness() f
aa00: 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73  unction attempts
aa10: 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65   to return nByte
aa20: 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f  s bytes.** of go
aa30: 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f  od-quality rando
aa40: 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e  mness into zOut.
aa50: 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c    The return val
aa60: 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74  ue is.** the act
aa70: 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  ual number of by
aa80: 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73  tes of randomnes
aa90: 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54  s obtained..** T
aaa0: 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68  he xSleep() meth
aab0: 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63 61  od causes the ca
aac0: 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20  lling thread to 
aad0: 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20  sleep for at.** 
aae0: 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72  least the number
aaf0: 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73   of microseconds
ab00: 20 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43   given.  ^The xC
ab10: 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20  urrentTime().** 
ab20: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61  method returns a
ab30: 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62   Julian Day Numb
ab40: 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65  er for the curre
ab50: 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65  nt date and time
ab60: 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e   as.** a floatin
ab70: 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a  g point value..*
ab80: 2a 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54  * ^The xCurrentT
ab90: 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f  imeInt64() metho
aba0: 64 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e  d returns, as an
abb0: 20 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75   integer, the Ju
abc0: 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62  lian.** Day Numb
abd0: 65 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79  er multiplied by
abe0: 20 38 36 34 30 30 30 30 30 20 28 74 68 65 20 6e   86400000 (the n
abf0: 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65  umber of millise
ac00: 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32  conds in .** a 2
ac10: 34 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a  4-hour day).  .*
ac20: 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  * ^SQLite will u
ac30: 73 65 20 74 68 65 20 78 43 75 72 72 65 6e 74 54  se the xCurrentT
ac40: 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f  imeInt64() metho
ac50: 64 20 74 6f 20 67 65 74 20 74 68 65 20 63 75 72  d to get the cur
ac60: 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64  rent.** date and
ac70: 20 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65   time if that me
ac80: 74 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c  thod is availabl
ac90: 65 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69  e (if iVersion i
aca0: 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74  s 2 or .** great
acb0: 65 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74  er and the funct
acc0: 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e  ion pointer is n
acd0: 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c  ot NULL) and wil
ace0: 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74  l fall back.** t
acf0: 6f 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29  o xCurrentTime()
ad00: 20 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65   if xCurrentTime
ad10: 49 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76 61  Int64() is unava
ad20: 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ilable..**.** ^T
ad30: 68 65 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c  he xSetSystemCal
ad40: 6c 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43  l(), xGetSystemC
ad50: 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74  all(), and xNest
ad60: 53 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74  SystemCall() int
ad70: 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e  erfaces.** are n
ad80: 6f 74 20 75 73 65 64 20 62 79 20 74 68 65 20 53  ot used by the S
ad90: 51 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65  QLite core.  The
ada0: 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65  se optional inte
adb0: 72 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 69  rfaces are provi
adc0: 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56  ded.** by some V
add0: 46 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61  FSes to facilita
ade0: 74 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68  te testing of th
adf0: 65 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f  e VFS code. By o
ae00: 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79  verriding .** sy
ae10: 73 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20  stem calls with 
ae20: 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20  functions under 
ae30: 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74  its control, a t
ae40: 65 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a  est program can.
ae50: 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c  ** simulate faul
ae60: 74 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e  ts and error con
ae70: 64 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75  ditions that wou
ae80: 6c 64 20 6f 74 68 65 72 77 69 73 65 20 62 65 20  ld otherwise be 
ae90: 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20  difficult.** or 
aea0: 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e  impossible to in
aeb0: 64 75 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f  duce.  The set o
aec0: 66 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74  f system calls t
aed0: 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72  hat can be overr
aee0: 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20  idden.** varies 
aef0: 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20  from one VFS to 
af00: 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f  another, and fro
af10: 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66  m one version of
af20: 20 74 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f   the same VFS to
af30: 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41   the.** next.  A
af40: 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
af50: 20 75 73 65 20 74 68 65 73 65 20 69 6e 74 65 72   use these inter
af60: 66 61 63 65 73 20 6d 75 73 74 20 62 65 20 70 72  faces must be pr
af70: 65 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a  epared for any.*
af80: 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73  * or all of thes
af90: 65 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20  e interfaces to 
afa0: 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74  be NULL or for t
afb0: 68 65 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f  heir behavior to
afc0: 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20   change.** from 
afd0: 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74  one release to t
afe0: 68 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63  he next.  Applic
aff0: 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20  ations must not 
b000: 61 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73  attempt to acces
b010: 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73  s.** any of thes
b020: 65 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65  e methods if the
b030: 20 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65   iVersion of the
b040: 20 56 46 53 20 69 73 20 6c 65 73 73 20 74 68 61   VFS is less tha
b050: 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  n 3..*/.typedef 
b060: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
b070: 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a  fs sqlite3_vfs;.
b080: 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73  typedef void (*s
b090: 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70  qlite3_syscall_p
b0a0: 74 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63  tr)(void);.struc
b0b0: 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a  t sqlite3_vfs {.
b0c0: 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20    int iVersion; 
b0d0: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74             /* St
b0e0: 72 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20  ructure version 
b0f0: 6e 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c  number (currentl
b100: 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a  y 3) */.  int sz
b110: 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20  OsFile;         
b120: 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75     /* Size of su
b130: 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33  bclassed sqlite3
b140: 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d  _file */.  int m
b150: 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20  xPathname;      
b160: 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66      /* Maximum f
b170: 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e  ile pathname len
b180: 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  gth */.  sqlite3
b190: 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20  _vfs *pNext;    
b1a0: 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74    /* Next regist
b1b0: 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f  ered VFS */.  co
b1c0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b  nst char *zName;
b1d0: 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
b1e0: 66 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 66  f this virtual f
b1f0: 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20  ile system */.  
b200: 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20  void *pAppData; 
b210: 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e           /* Poin
b220: 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69  ter to applicati
b230: 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74 61  on-specific data
b240: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65   */.  int (*xOpe
b250: 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  n)(sqlite3_vfs*,
b260: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
b270: 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  me, sqlite3_file
b280: 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  *,.             
b290: 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74    int flags, int
b2a0: 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20   *pOutFlags);.  
b2b0: 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73  int (*xDelete)(s
b2c0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
b2d0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
b2e0: 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20  int syncDir);.  
b2f0: 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28 73  int (*xAccess)(s
b300: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
b310: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
b320: 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a  int flags, int *
b330: 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20  pResOut);.  int 
b340: 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29  (*xFullPathname)
b350: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
b360: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
b370: 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72  , int nOut, char
b380: 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20   *zOut);.  void 
b390: 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69  *(*xDlOpen)(sqli
b3a0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
b3b0: 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29  char *zFilename)
b3c0: 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72  ;.  void (*xDlEr
b3d0: 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ror)(sqlite3_vfs
b3e0: 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68  *, int nByte, ch
b3f0: 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20  ar *zErrMsg);.  
b400: 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29  void (*(*xDlSym)
b410: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f  (sqlite3_vfs*,vo
b420: 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  id*, const char 
b430: 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29  *zSymbol))(void)
b440: 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c  ;.  void (*xDlCl
b450: 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ose)(sqlite3_vfs
b460: 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74  *, void*);.  int
b470: 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28   (*xRandomness)(
b480: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
b490: 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a  t nByte, char *z
b4a0: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  Out);.  int (*xS
b4b0: 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66  leep)(sqlite3_vf
b4c0: 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63  s*, int microsec
b4d0: 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78  onds);.  int (*x
b4e0: 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c  CurrentTime)(sql
b4f0: 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c  ite3_vfs*, doubl
b500: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65  e*);.  int (*xGe
b510: 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69  tLastError)(sqli
b520: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63  te3_vfs*, int, c
b530: 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a  har *);.  /*.  *
b540: 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62  * The methods ab
b550: 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69  ove are in versi
b560: 6f 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69  on 1 of the sqli
b570: 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20  te_vfs object.  
b580: 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20  ** definition.  
b590: 54 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f  Those that follo
b5a0: 77 20 61 72 65 20 61 64 64 65 64 20 69 6e 20 76  w are added in v
b5b0: 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65  ersion 2 or late
b5c0: 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  r.  */.  int (*x
b5d0: 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34  CurrentTimeInt64
b5e0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
b5f0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b  sqlite3_int64*);
b600: 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d  .  /*.  ** The m
b610: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
b620: 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61   in versions 1 a
b630: 6e 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69  nd 2 of the sqli
b640: 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20  te_vfs object.. 
b650: 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20   ** Those below 
b660: 61 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20  are for version 
b670: 33 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20  3 and greater.. 
b680: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74   */.  int (*xSet
b690: 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
b6a0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
b6b0: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c  char *zName, sql
b6c0: 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72  ite3_syscall_ptr
b6d0: 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73  );.  sqlite3_sys
b6e0: 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53  call_ptr (*xGetS
b6f0: 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74  ystemCall)(sqlit
b700: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
b710: 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63  har *zName);.  c
b720: 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65  onst char *(*xNe
b730: 78 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71  xtSystemCall)(sq
b740: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
b750: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
b760: 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65    /*.  ** The me
b770: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
b780: 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68  in versions 1 th
b790: 72 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20 73  rough 3 of the s
b7a0: 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74  qlite_vfs object
b7b0: 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64  ..  ** New field
b7c0: 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65  s may be appende
b7d0: 64 20 69 6e 20 66 69 67 75 72 65 20 76 65 72 73  d in figure vers
b7e0: 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73  ions.  The iVers
b7f0: 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77  ion.  ** value w
b800: 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68  ill increment wh
b810: 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70 70  enever this happ
b820: 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f  ens. .  */.};../
b830: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
b840: 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 63  lags for the xAc
b850: 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a  cess VFS method.
b860: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
b870: 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61  ger constants ca
b880: 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65  n be used as the
b890: 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
b8a0: 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65   to.** the xAcce
b8b0: 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20  ss method of an 
b8c0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
b8d0: 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65 74 65  ject.  They dete
b8e0: 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69  rmine.** what ki
b8f0: 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e  nd of permission
b900: 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  s the xAccess me
b910: 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20  thod is looking 
b920: 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c  for..** With SQL
b930: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
b940: 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  S, the xAccess m
b950: 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20  ethod.** simply 
b960: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74  checks whether t
b970: 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a  he file exists..
b980: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
b990: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c  CCESS_READWRITE,
b9a0: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
b9b0: 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68  hod.** checks wh
b9c0: 65 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20  ether the named 
b9d0: 64 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74  directory is bot
b9e0: 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77  h readable and w
b9f0: 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f  ritable.** (in o
ba00: 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66  ther words, if f
ba10: 69 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64 65  iles can be adde
ba20: 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20  d, removed, and 
ba30: 72 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a  renamed within.*
ba40: 2a 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 29  * the directory)
ba50: 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  ..** The SQLITE_
ba60: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
ba70: 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72   constant is cur
ba80: 72 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79  rently used only
ba90: 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70   by the.** [temp
baa0: 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
bab0: 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68   pragma], though
bac0: 20 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e   this could chan
bad0: 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a  ge in a future.*
bae0: 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  * release of SQL
baf0: 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c  ite..** With SQL
bb00: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c  ITE_ACCESS_READ,
bb10: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
bb20: 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68  hod.** checks wh
bb30: 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 69  ether the file i
bb40: 73 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65  s readable.  The
bb50: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
bb60: 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a  EAD constant is.
bb70: 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75  ** currently unu
bb80: 73 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d  sed, though it m
bb90: 69 67 68 74 20 62 65 20 75 73 65 64 20 69 6e 20  ight be used in 
bba0: 61 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  a future release
bbb0: 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a   of.** SQLite..*
bbc0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
bbd0: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20 20  _ACCESS_EXISTS  
bbe0: 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
bbf0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
bc00: 49 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20  ITE 1   /* Used 
bc10: 62 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73  by PRAGMA temp_s
bc20: 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a  tore_directory *
bc30: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
bc40: 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20 20 20  _ACCESS_READ    
bc50: 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20    2   /* Unused 
bc60: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
bc70: 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68  EF: Flags for th
bc80: 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d  e xShmLock VFS m
bc90: 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ethod.**.** Thes
bca0: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
bcb0: 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65 20 76  nts define the v
bcc0: 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f  arious locking o
bcd0: 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c  perations.** all
bce0: 6f 77 65 64 20 62 79 20 74 68 65 20 78 53 68 6d  owed by the xShm
bcf0: 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b  Lock method of [
bd00: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
bd10: 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c  ds].  The.** fol
bd20: 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f  lowing are the o
bd30: 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e  nly legal combin
bd40: 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20  ations of flags 
bd50: 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f  to the.** xShmLo
bd60: 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a  ck method:.**.**
bd70: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53   <ul>.** <li>  S
bd80: 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c  QLITE_SHM_LOCK |
bd90: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
bda0: 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  ED.** <li>  SQLI
bdb0: 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51  TE_SHM_LOCK | SQ
bdc0: 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49  LITE_SHM_EXCLUSI
bdd0: 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  VE.** <li>  SQLI
bde0: 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20  TE_SHM_UNLOCK | 
bdf0: 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45  SQLITE_SHM_SHARE
be00: 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  D.** <li>  SQLIT
be10: 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53  E_SHM_UNLOCK | S
be20: 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53  QLITE_SHM_EXCLUS
be30: 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  IVE.** </ul>.**.
be40: 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e  ** When unlockin
be50: 67 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41 52  g, the same SHAR
be60: 45 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20  ED or EXCLUSIVE 
be70: 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75 70  flag must be sup
be80: 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20  plied as.** was 
be90: 67 69 76 65 6e 20 6e 6f 20 74 68 65 20 63 6f 72  given no the cor
bea0: 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e  responding lock.
beb0: 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68    .**.** The xSh
bec0: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e  mLock method can
bed0: 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77   transition betw
bee0: 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64  een unlocked and
bef0: 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65   SHARED or.** be
bf00: 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61  tween unlocked a
bf10: 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49  nd EXCLUSIVE.  I
bf20: 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74  t cannot transit
bf30: 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52  ion between SHAR
bf40: 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53  ED.** and EXCLUS
bf50: 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  IVE..*/.#define 
bf60: 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43  SQLITE_SHM_UNLOC
bf70: 4b 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e  K       1.#defin
bf80: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43  e SQLITE_SHM_LOC
bf90: 4b 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66  K         2.#def
bfa0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53  ine SQLITE_SHM_S
bfb0: 48 41 52 45 44 20 20 20 20 20 20 20 34 0a 23 64  HARED       4.#d
bfc0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
bfd0: 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a  _EXCLUSIVE    8.
bfe0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
bff0: 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63   Maximum xShmLoc
c000: 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68  k index.**.** Th
c010: 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  e xShmLock metho
c020: 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f  d on [sqlite3_io
c030: 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73  _methods] may us
c040: 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77  e values.** betw
c050: 65 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75  een 0 and this u
c060: 70 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74  pper bound as it
c070: 73 20 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d  s "offset" argum
c080: 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69  ent..** The SQLi
c090: 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76  te core will nev
c0a0: 65 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63  er attempt to ac
c0b0: 71 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65  quire or release
c0c0: 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69   a.** lock outsi
c0d0: 64 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65  de of this range
c0e0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
c0f0: 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20  TE_SHM_NLOCK    
c100: 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41      8.../*.** CA
c110: 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69  PI3REF: Initiali
c120: 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69  ze The SQLite Li
c130: 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  brary.**.** ^The
c140: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
c150: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e  ize() routine in
c160: 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a  itializes the.**
c170: 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e   SQLite library.
c180: 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73    ^The sqlite3_s
c190: 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e  hutdown() routin
c1a0: 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73  e.** deallocates
c1b0: 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74   any resources t
c1c0: 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74  hat were allocat
c1d0: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ed by sqlite3_in
c1e0: 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54  itialize()..** T
c1f0: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
c200: 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69  e designed to ai
c210: 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69  d in process ini
c220: 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a  tialization and.
c230: 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65  ** shutdown on e
c240: 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e  mbedded systems.
c250: 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70    Workstation ap
c260: 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67  plications using
c270: 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61  .** SQLite norma
c280: 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20  lly do not need 
c290: 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72  to invoke either
c2a0: 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
c2b0: 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c  es..**.** A call
c2c0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   to sqlite3_init
c2d0: 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22  ialize() is an "
c2e0: 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20  effective" call 
c2f0: 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20  if it is.** the 
c300: 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74  first time sqlit
c310: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
c320: 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e  is invoked durin
c330: 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f  g the lifetime o
c340: 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73  f.** the process
c350: 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 74 68  , or if it is th
c360: 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c  e first time sql
c370: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
c380: 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
c390: 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c  following a call
c3a0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
c3b0: 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20  down().  ^(Only 
c3c0: 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c  an effective cal
c3d0: 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  l.** of sqlite3_
c3e0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65  initialize() doe
c3f0: 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61  s any initializa
c400: 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72  tion.  All other
c410: 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61   calls.** are ha
c420: 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e  rmless no-ops.)^
c430: 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f  .**.** A call to
c440: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
c450: 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63  n() is an "effec
c460: 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74  tive" call if it
c470: 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a   is the first.**
c480: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
c490: 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63  _shutdown() sinc
c4a0: 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74  e the last sqlit
c4b0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e  e3_initialize().
c4c0: 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65    ^(Only.** an e
c4d0: 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f  ffective call to
c4e0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
c4f0: 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69  n() does any dei
c500: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a  nitialization..*
c510: 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69  * All other vali
c520: 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  d calls to sqlit
c530: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72  e3_shutdown() ar
c540: 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  e harmless no-op
c550: 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  s.)^.**.** The s
c560: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
c570: 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  e() interface is
c580: 20 74 68 72 65 61 64 73 61 66 65 2c 20 62 75 74   threadsafe, but
c590: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
c5a0: 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20  n().** is not.  
c5b0: 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74  The sqlite3_shut
c5c0: 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65  down() interface
c5d0: 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61   must only be ca
c5e0: 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73  lled from a.** s
c5f0: 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41  ingle thread.  A
c600: 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73  ll open [databas
c610: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d  e connections] m
c620: 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e  ust be closed an
c630: 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53  d all.** other S
c640: 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73 20  QLite resources 
c650: 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61  must be dealloca
c660: 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76  ted prior to inv
c670: 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  oking.** sqlite3
c680: 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a  _shutdown()..**.
c690: 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74  ** Among other t
c6a0: 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f  hings, ^sqlite3_
c6b0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c  initialize() wil
c6c0: 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69  l invoke.** sqli
c6d0: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20  te3_os_init().  
c6e0: 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69  Similarly, ^sqli
c6f0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a  te3_shutdown().*
c700: 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71  * will invoke sq
c710: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a  lite3_os_end()..
c720: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
c730: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
c740: 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
c750: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
c760: 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66  uccess..** ^If f
c770: 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20  or some reason, 
c780: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
c790: 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74  ze() is unable t
c7a0: 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20  o initialize.** 
c7b0: 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 65 72  the library (per
c7c0: 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c  haps it is unabl
c7d0: 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20  e to allocate a 
c7e0: 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 65 20  needed resource 
c7f0: 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74  such.** as a mut
c800: 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 20 61  ex) it returns a
c810: 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f  n [error code] o
c820: 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
c830: 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  E_OK]..**.** ^Th
c840: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
c850: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69  lize() routine i
c860: 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61  s called interna
c870: 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65  lly by many othe
c880: 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65  r.** SQLite inte
c890: 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 20 61  rfaces so that a
c8a0: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73  n application us
c8b0: 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e  ually does not n
c8c0: 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65  eed to.** invoke
c8d0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
c8e0: 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20  ize() directly. 
c8f0: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73   For example, [s
c900: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a  qlite3_open()].*
c910: 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f  * calls sqlite3_
c920: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20  initialize() so 
c930: 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
c940: 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d  ry will be autom
c950: 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74  atically.** init
c960: 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71  ialized when [sq
c970: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73  lite3_open()] is
c980: 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61   called if it ha
c990: 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c  s not be initial
c9a0: 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e  ized.** already.
c9b0: 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53    ^However, if S
c9c0: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
c9d0: 64 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49  d with the [SQLI
c9e0: 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54  TE_OMIT_AUTOINIT
c9f0: 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  ].** compile-tim
ca00: 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74  e option, then t
ca10: 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c  he automatic cal
ca20: 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ls to sqlite3_in
ca30: 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72  itialize().** ar
ca40: 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68  e omitted and th
ca50: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
ca60: 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f  st call sqlite3_
ca70: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72  initialize() dir
ca80: 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74  ectly.** prior t
ca90: 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65  o using any othe
caa0: 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
cab0: 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d  ce.  For maximum
cac0: 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a   portability,.**
cad0: 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   it is recommend
cae0: 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74  ed that applicat
caf0: 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f  ions always invo
cb00: 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ke sqlite3_initi
cb10: 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63  alize().** direc
cb20: 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69  tly prior to usi
cb30: 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c  ng any other SQL
cb40: 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ite interface.  
cb50: 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a  Future releases.
cb60: 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79  ** of SQLite may
cb70: 20 72 65 71 75 69 72 65 20 74 68 69 73 2e 20 20   require this.  
cb80: 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
cb90: 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 78 68  the behavior exh
cba0: 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53  ibited.** when S
cbb0: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
cbc0: 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f  d with [SQLITE_O
cbd0: 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69  MIT_AUTOINIT] mi
cbe0: 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a  ght become the.*
cbf0: 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69  * default behavi
cc00: 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72  or in some futur
cc10: 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  e release of SQL
cc20: 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ite..**.** The s
cc30: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
cc40: 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70   routine does op
cc50: 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73  erating-system s
cc60: 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69  pecific.** initi
cc70: 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65  alization of the
cc80: 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e   SQLite library.
cc90: 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73    The sqlite3_os
cca0: 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  _end().** routin
ccb0: 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66  e undoes the eff
ccc0: 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f  ect of sqlite3_o
ccd0: 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63  s_init().  Typic
cce0: 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66  al tasks.** perf
ccf0: 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65 20 72  ormed by these r
cd00: 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20  outines include 
cd10: 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65  allocation or de
cd20: 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66  allocation.** of
cd30: 20 73 74 61 74 69 63 20 72 65 73 6f 75 72 63 65   static resource
cd40: 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  s, initializatio
cd50: 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69  n of global vari
cd60: 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e  ables,.** settin
cd70: 67 20 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b  g up a default [
cd80: 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64  sqlite3_vfs] mod
cd90: 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20  ule, or setting 
cda0: 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20  up.** a default 
cdb0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73  configuration us
cdc0: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  ing [sqlite3_con
cdd0: 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  fig()]..**.** Th
cde0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
cdf0: 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b  ould never invok
ce00: 65 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 33  e either sqlite3
ce10: 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72  _os_init().** or
ce20: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
ce30: 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65  ) directly.  The
ce40: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
ce50: 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a  uld only invoke.
ce60: 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ** sqlite3_initi
ce70: 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69  alize() and sqli
ce80: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20  te3_shutdown(). 
ce90: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
cea0: 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66  init().** interf
ceb0: 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75  ace is called au
cec0: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73  tomatically by s
ced0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
cee0: 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74  e() and.** sqlit
cef0: 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63  e3_os_end() is c
cf00: 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33  alled by sqlite3
cf10: 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70  _shutdown().  Ap
cf20: 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70  propriate.** imp
cf30: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72  lementations for
cf40: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
cf50: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
cf60: 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62  s_end().** are b
cf70: 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65  uilt into SQLite
cf80: 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70   when it is comp
cf90: 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57  iled for Unix, W
cfa0: 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e  indows, or OS/2.
cfb0: 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d  .** When [custom
cfc0: 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20   builds | built 
cfd0: 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f  for other platfo
cfe0: 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74  rms].** (using t
cff0: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54  he [SQLITE_OS_OT
d000: 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74  HER=1] compile-t
d010: 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74  ime.** option) t
d020: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
d030: 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 75 69  ust supply a sui
d040: 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  table implementa
d050: 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  tion for.** sqli
d060: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e  te3_os_init() an
d070: 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  d sqlite3_os_end
d080: 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74  ().  An applicat
d090: 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20  ion-supplied.** 
d0a0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
d0b0: 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  f sqlite3_os_ini
d0c0: 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  t() or sqlite3_o
d0d0: 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20  s_end().** must 
d0e0: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
d0f0: 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e  K] on success an
d100: 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72  d some other [er
d110: 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a  ror code] upon.*
d120: 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e  * failure..*/.in
d130: 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  t sqlite3_initia
d140: 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20  lize(void);.int 
d150: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
d160: 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69  (void);.int sqli
d170: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64  te3_os_init(void
d180: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
d190: 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a  s_end(void);../*
d1a0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
d1b0: 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 51  nfiguring The SQ
d1c0: 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a  Lite Library.**.
d1d0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
d1e0: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
d1f0: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b  e is used to mak
d200: 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75  e global configu
d210: 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65  ration.** change
d220: 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f  s to SQLite in o
d230: 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c  rder to tune SQL
d240: 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63 69  ite to the speci
d250: 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20  fic needs of.** 
d260: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e  the application.
d270: 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f    The default co
d280: 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72  nfiguration is r
d290: 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d  ecommended for m
d2a0: 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  ost.** applicati
d2b0: 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20  ons and so this 
d2c0: 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c  routine is usual
d2d0: 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79  ly not necessary
d2e0: 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76  .  It is.** prov
d2f0: 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20  ided to support 
d300: 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e  rare application
d310: 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e  s with unusual n
d320: 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  eeds..**.** The 
d330: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
d340: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f   interface is no
d350: 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54  t threadsafe.  T
d360: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  he application.*
d370: 2a 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68  * must insure th
d380: 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69  at no other SQLi
d390: 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  te interfaces ar
d3a0: 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68  e invoked by oth
d3b0: 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68  er.** threads wh
d3c0: 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ile sqlite3_conf
d3d0: 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e  ig() is running.
d3e0: 20 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73    Furthermore, s
d3f0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a  qlite3_config().
d400: 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69  ** may only be i
d410: 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20  nvoked prior to 
d420: 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69  library initiali
d430: 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20  zation using.** 
d440: 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
d450: 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20  ize()] or after 
d460: 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c  shutdown by [sql
d470: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
d480: 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
d490: 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c  _config() is cal
d4a0: 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74  led after [sqlit
d4b0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
d4c0: 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b   and before.** [
d4d0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
d4e0: 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c  ()] then it will
d4f0: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d   return SQLITE_M
d500: 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20  ISUSE..** Note, 
d510: 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73  however, that ^s
d520: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
d530: 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73  can be called as
d540: 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20   part of the.** 
d550: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
d560: 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
d570: 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65  -defined [sqlite
d580: 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a  3_os_init()]..**
d590: 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
d5a0: 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
d5b0: 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e  3_config() is an
d5c0: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e   integer.** [con
d5d0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
d5e0: 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  n] that determin
d5f0: 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65  es.** what prope
d600: 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73  rty of SQLite is
d610: 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65   to be configure
d620: 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 61  d.  Subsequent a
d630: 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79  rguments.** vary
d640: 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
d650: 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  e [configuration
d660: 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74   option].** in t
d670: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
d680: 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61  t..**.** ^When a
d690: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
d6a0: 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71  ption is set, sq
d6b0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72  lite3_config() r
d6c0: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
d6d0: 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f  K]..** ^If the o
d6e0: 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e  ption is unknown
d6f0: 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e   or SQLite is un
d700: 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20  able to set the 
d710: 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74  option.** then t
d720: 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
d730: 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b  rns a non-zero [
d740: 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a  error code]..*/.
d750: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  int sqlite3_conf
d760: 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f  ig(int, ...);../
d770: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
d780: 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 61 73  onfigure databas
d790: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a  e connections.**
d7a0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
d7b0: 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  db_config() inte
d7c0: 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f  rface is used to
d7d0: 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74   make configurat
d7e0: 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ion.** changes t
d7f0: 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  o a [database co
d800: 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20  nnection].  The 
d810: 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d  interface is sim
d820: 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  ilar to.** [sqli
d830: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78  te3_config()] ex
d840: 63 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68  cept that the ch
d850: 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61  anges apply to a
d860: 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61   single.** [data
d870: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
d880: 20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74   (specified in t
d890: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
d8a0: 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  t)..**.** The se
d8b0: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
d8c0: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
d8d0: 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20  ig(D,V,...)  is 
d8e0: 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  the.** [SQLITE_D
d8f0: 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
d900: 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  E | configuratio
d910: 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74  n verb] - an int
d920: 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68  eger code .** th
d930: 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61  at indicates wha
d940: 74 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20  t aspect of the 
d950: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
d960: 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63  tion] is being c
d970: 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75  onfigured..** Su
d980: 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e  bsequent argumen
d990: 74 73 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e  ts vary dependin
d9a0: 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75  g on the configu
d9b0: 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a  ration verb..**.
d9c0: 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c  ** ^Calls to sql
d9d0: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
d9e0: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f   return SQLITE_O
d9f0: 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  K if and only if
da00: 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20  .** the call is 
da10: 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65  considered succe
da20: 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ssful..*/.int sq
da30: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
da40: 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70  sqlite3*, int op
da50: 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , ...);../*.** C
da60: 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
da70: 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69  Allocation Routi
da80: 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  nes.**.** An ins
da90: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
daa0: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
dab0: 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65   interface betwe
dac0: 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64  en SQLite.** and
dad0: 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72   low-level memor
dae0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
daf0: 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  tines..**.** Thi
db00: 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  s object is used
db10: 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61   in only one pla
db20: 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65  ce in the SQLite
db30: 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41   interface..** A
db40: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
db50: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
db60: 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72  object is the ar
db70: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71  gument to.** [sq
db80: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
db90: 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75  when the configu
dba0: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
dbb0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
dbc0: 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53  IG_MALLOC] or [S
dbd0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
dbe0: 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79  MALLOC].  .** By
dbf0: 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73   creating an ins
dc00: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
dc10: 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73  ject.** and pass
dc20: 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74  ing it to [sqlit
dc30: 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49  e3_config]([SQLI
dc40: 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
dc50: 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e  ]).** during con
dc60: 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61  figuration, an a
dc70: 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73  pplication can s
dc80: 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e  pecify an altern
dc90: 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ative.** memory 
dca0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79  allocation subsy
dcb0: 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20  stem for SQLite 
dcc0: 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f  to use for all o
dcd0: 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63  f its.** dynamic
dce0: 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a   memory needs..*
dcf0: 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53  *.** Note that S
dd00: 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68  QLite comes with
dd10: 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d   several [built-
dd20: 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
dd30: 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72  tors].** that ar
dd40: 65 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71  e perfectly adeq
dd50: 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65  uate for the ove
dd60: 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69  rwhelming majori
dd70: 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f  ty of applicatio
dd80: 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74  ns.** and that t
dd90: 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e  his object is on
dda0: 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74  ly useful to a t
ddb0: 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20  iny minority of 
ddc0: 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
ddd0: 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64  with specialized
dde0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
ddf0: 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e  on requirements.
de00: 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73    This object is
de10: 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75  .** also used du
de20: 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20  ring testing of 
de30: 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20  SQLite in order 
de40: 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c  to specify an al
de50: 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d  ternative.** mem
de60: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68  ory allocator th
de70: 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d  at simulates mem
de80: 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72  ory out-of-memor
de90: 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a  y conditions in.
dea0: 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69  ** order to veri
deb0: 66 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72  fy that SQLite r
dec0: 65 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c  ecovers graceful
ded0: 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20  ly from such.** 
dee0: 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  conditions..**.*
def0: 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78  * The xMalloc, x
df00: 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72  Realloc, and xFr
df10: 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20  ee methods must 
df20: 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a  work like the.**
df30: 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c   malloc(), reall
df40: 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
df50: 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74  functions from t
df60: 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
df70: 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  brary..** ^SQLit
df80: 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  e guarantees tha
df90: 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  t the second arg
dfa0: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61  ument to.** xRea
dfb0: 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61  lloc is always a
dfc0: 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
dfd0: 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20  by a prior call 
dfe0: 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a  to xRoundup..**.
dff0: 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20  ** xSize should 
e000: 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63  return the alloc
e010: 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d  ated size of a m
e020: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
e030: 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f  .** previously o
e040: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61  btained from xMa
e050: 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63  lloc or xRealloc
e060: 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64  .  The allocated
e070: 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61   size.** is alwa
e080: 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62  ys at least as b
e090: 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73  ig as the reques
e0a0: 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79  ted size but may
e0b0: 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a   be larger..**.*
e0c0: 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d  * The xRoundup m
e0d0: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68  ethod returns wh
e0e0: 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20  at would be the 
e0f0: 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
e100: 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c  f.** a memory al
e110: 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61  location given a
e120: 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75   particular requ
e130: 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73  ested size.  Mos
e140: 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  t memory.** allo
e150: 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
e160: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
e170: 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74  ns at least to t
e180: 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65  he next multiple
e190: 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20  .** of 8.  Some 
e1a0: 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64  allocators round
e1b0: 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20   up to a larger 
e1c0: 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61  multiple or to a
e1d0: 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20   power of 2..** 
e1e0: 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c  Every memory all
e1f0: 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20  ocation request 
e200: 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67  coming in throug
e210: 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  h [sqlite3_mallo
e220: 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  c()].** or [sqli
e230: 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66  te3_realloc()] f
e240: 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e  irst calls xRoun
e250: 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75  dup.  If xRoundu
e260: 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a  p returns 0, .**
e270: 20 74 68 61 74 20 63 61 75 73 65 73 20 74 68 65   that causes the
e280: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d   corresponding m
e290: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
e2a0: 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20   to fail..**.** 
e2b0: 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  The xInit method
e2c0: 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65   initializes the
e2d0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
e2e0: 72 2e 20 20 28 46 6f 72 20 65 78 61 6d 70 6c 65  r.  (For example
e2f0: 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c  ,.** it might al
e300: 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75 69  locate any requi
e310: 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e  re mutexes or in
e320: 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61  itialize interna
e330: 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74  l data.** struct
e340: 75 72 65 73 2e 20 20 54 68 65 20 78 53 68 75 74  ures.  The xShut
e350: 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69  down method is i
e360: 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74  nvoked (indirect
e370: 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ly) by.** [sqlit
e380: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61  e3_shutdown()] a
e390: 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f  nd should deallo
e3a0: 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63  cate any resourc
e3b0: 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62  es acquired.** b
e3c0: 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41  y xInit.  The pA
e3d0: 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69  ppData pointer i
e3e0: 73 20 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e  s used as the on
e3f0: 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  ly parameter to.
e400: 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68  ** xInit and xSh
e410: 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51  utdown..**.** SQ
e420: 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b  Lite holds the [
e430: 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
e440: 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65  TIC_MASTER] mute
e450: 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65  x when it invoke
e460: 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d  s.** the xInit m
e470: 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49  ethod, so the xI
e480: 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20  nit method need 
e490: 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73 61 66  not be threadsaf
e4a0: 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74  e.  The.** xShut
e4b0: 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f  down method is o
e4c0: 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  nly called from 
e4d0: 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
e4e0: 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a  n()] so it does.
e4f0: 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  ** not need to b
e500: 65 20 74 68 72 65 61 64 73 61 66 65 20 65 69 74  e threadsafe eit
e510: 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74  her.  For all ot
e520: 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c  her methods, SQL
e530: 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65  ite.** holds the
e540: 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53   [SQLITE_MUTEX_S
e550: 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78  TATIC_MEM] mutex
e560: 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a   as long as the.
e570: 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
e580: 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e  G_MEMSTATUS] con
e590: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
e5a0: 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28  n is turned on (
e5b0: 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62  which.** it is b
e5c0: 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73  y default) and s
e5d0: 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72  o the methods ar
e5e0: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
e5f0: 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48  serialized..** H
e600: 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49  owever, if [SQLI
e610: 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
e620: 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64  TUS] is disabled
e630: 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72  , then the other
e640: 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74  .** methods must
e650: 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20 6f   be threadsafe o
e660: 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69  r else make thei
e670: 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e  r own arrangemen
e680: 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c  ts for.** serial
e690: 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53  ization..**.** S
e6a0: 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72  QLite will never
e6b0: 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20   invoke xInit() 
e6c0: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77  more than once w
e6d0: 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76  ithout an interv
e6e0: 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f  ening.** call to
e6f0: 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f   xShutdown()..*/
e700: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
e710: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
e720: 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  ods sqlite3_mem_
e730: 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20  methods;.struct 
e740: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
e750: 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a  ods {.  void *(*
e760: 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20  xMalloc)(int);  
e770: 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79         /* Memory
e780: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63   allocation func
e790: 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28  tion */.  void (
e7a0: 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20  *xFree)(void*); 
e7b0: 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65           /* Free
e7c0: 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74   a prior allocat
e7d0: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28  ion */.  void *(
e7e0: 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a  *xRealloc)(void*
e7f0: 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a  ,int);  /* Resiz
e800: 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  e an allocation 
e810: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65  */.  int (*xSize
e820: 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20  )(void*);       
e830: 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68      /* Return th
e840: 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c  e size of an all
e850: 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74  ocation */.  int
e860: 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74   (*xRoundup)(int
e870: 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52  );          /* R
e880: 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73 74 20  ound up request 
e890: 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69  size to allocati
e8a0: 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74  on size */.  int
e8b0: 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29   (*xInit)(void*)
e8c0: 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49  ;           /* I
e8d0: 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65  nitialize the me
e8e0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a  mory allocator *
e8f0: 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74  /.  void (*xShut
e900: 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20  down)(void*);   
e910: 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69     /* Deinitiali
e920: 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  ze the memory al
e930: 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69  locator */.  voi
e940: 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20  d *pAppData;    
e950: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41              /* A
e960: 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74  rgument to xInit
e970: 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e  () and xShutdown
e980: 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  () */.};../*.** 
e990: 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
e9a0: 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a  uration Options.
e9b0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f  ** KEYWORDS: {co
e9c0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
e9d0: 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  on}.**.** These 
e9e0: 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68  constants are th
e9f0: 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65  e available inte
ea00: 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ger configuratio
ea10: 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a  n options that.*
ea20: 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20  * can be passed 
ea30: 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
ea40: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71  ument to the [sq
ea50: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
ea60: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
ea70: 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69   New configurati
ea80: 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62  on options may b
ea90: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
eaa0: 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
eab0: 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e  Lite..** Existin
eac0: 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  g configuration 
ead0: 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65  options might be
eae0: 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20   discontinued.  
eaf0: 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  Applications.** 
eb00: 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65  should check the
eb10: 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f   return code fro
eb20: 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  m [sqlite3_confi
eb30: 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72  g()] to make sur
eb40: 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61  e that.** the ca
eb50: 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20  ll worked.  The 
eb60: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
eb70: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c  )] interface wil
eb80: 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f  l return a.** no
eb90: 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f  n-zero [error co
eba0: 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74  de] if a discont
ebb0: 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f  inued or unsuppo
ebc0: 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69  rted configurati
ebd0: 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20  on option.** is 
ebe0: 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  invoked..**.** <
ebf0: 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  dl>.** [[SQLITE_
ec00: 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
ec10: 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  EAD]] <dt>SQLITE
ec20: 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
ec30: 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  READ</dt>.** <dd
ec40: 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
ec50: 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
ec60: 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f  option.  ^This o
ec70: 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
ec80: 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  * [threading mod
ec90: 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72  e] to Single-thr
eca0: 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  ead.  In other w
ecb0: 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65  ords, it disable
ecc0: 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e  s.** all mutexin
ecd0: 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74  g and puts SQLit
ece0: 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68  e into a mode wh
ecf0: 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20  ere it can only 
ed00: 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20  be used.** by a 
ed10: 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20  single thread.  
ed20: 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
ed30: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
ed40: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
ed50: 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
ed60: 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
ed70: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
ed80: 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20  n then.** it is 
ed90: 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
eda0: 63 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65  change the [thre
edb0: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d  ading mode] from
edc0: 20 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20   its default.** 
edd0: 76 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d  value of Single-
ede0: 74 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73  thread and so [s
edf0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
ee00: 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a   will return .**
ee10: 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
ee20: 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
ee30: 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
ee40: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a  _SINGLETHREAD.**
ee50: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
ee60: 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
ee70: 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
ee80: 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20  G_MULTITHREAD]] 
ee90: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
eea0: 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64  G_MULTITHREAD</d
eeb0: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20  t>.** <dd>There 
eec0: 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73  are no arguments
eed0: 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e   to this option.
eee0: 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73    ^This option s
eef0: 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65  ets the.** [thre
ef00: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d  ading mode] to M
ef10: 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e  ulti-thread.  In
ef20: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74   other words, it
ef30: 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74   disables.** mut
ef40: 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61  exing on [databa
ef50: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
ef60: 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
ef70: 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e  tement] objects.
ef80: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
ef90: 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ion is responsib
efa0: 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69  le for serializi
efb0: 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20  ng access to.** 
efc0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
efd0: 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70  tions] and [prep
efe0: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
eff0: 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74  .  But other mut
f000: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
f010: 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69  led so that SQLi
f020: 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20  te will be safe 
f030: 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74  to use in a mult
f040: 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e  i-threaded.** en
f050: 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e  vironment as lon
f060: 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65  g as no two thre
f070: 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75  ads attempt to u
f080: 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b  se the same.** [
f090: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
f0a0: 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65  ion] at the same
f0b0: 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69   time.  ^If SQLi
f0c0: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
f0d0: 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
f0e0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
f0f0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
f100: 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
f110: 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
f120: 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69   it is not possi
f130: 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d  ble to set the M
f140: 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72  ulti-thread [thr
f150: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64  eading mode] and
f160: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
f170: 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  fig()] will retu
f180: 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
f190: 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68  ] if called with
f1a0: 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43   the.** SQLITE_C
f1b0: 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
f1c0: 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  D configuration 
f1d0: 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  option.</dd>.**.
f1e0: 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
f1f0: 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20  IG_SERIALIZED]] 
f200: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
f210: 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74  G_SERIALIZED</dt
f220: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61  >.** <dd>There a
f230: 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20  re no arguments 
f240: 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20  to this option. 
f250: 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65   ^This option se
f260: 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61  ts the.** [threa
f270: 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65  ding mode] to Se
f280: 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68  rialized. In oth
f290: 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f  er words, this o
f2a0: 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a  ption enables.**
f2b0: 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63   all mutexes inc
f2c0: 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63 75 72  luding the recur
f2d0: 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20  sive.** mutexes 
f2e0: 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
f2f0: 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72  nection] and [pr
f300: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
f310: 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e  ] objects..** In
f320: 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63   this mode (whic
f330: 68 20 69 73 20 74 68 65 20 64 65 66 61 75 6c 74  h is the default
f340: 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
f350: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
f360: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
f370: 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69  AFE=1]) the SQLi
f380: 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20  te library will 
f390: 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65  itself serialize
f3a0: 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64   access.** to [d
f3b0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
f3c0: 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ons] and [prepar
f3d0: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73  ed statements] s
f3e0: 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70  o that the.** ap
f3f0: 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65  plication is fre
f400: 65 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d  e to use the sam
f410: 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
f420: 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a  ection] or the.*
f430: 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64  * same [prepared
f440: 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64   statement] in d
f450: 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 73  ifferent threads
f460: 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
f470: 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65  e..** ^If SQLite
f480: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
f490: 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
f4a0: 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
f4b0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
f4c0: 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
f4d0: 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
f4e0: 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
f4f0: 65 20 74 6f 20 73 65 74 20 74 68 65 20 53 65 72  e to set the Ser
f500: 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69  ialized [threadi
f510: 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20  ng mode] and.** 
f520: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
f530: 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  )] will return [
f540: 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
f550: 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65   called with the
f560: 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  .** SQLITE_CONFI
f570: 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e  G_SERIALIZED con
f580: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
f590: 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  n.</dd>.**.** [[
f5a0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
f5b0: 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  LLOC]] <dt>SQLIT
f5c0: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c  E_CONFIG_MALLOC<
f5d0: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
f5e0: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
f5f0: 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
f600: 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
f610: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69  inter to an.** i
f620: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
f630: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
f640: 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20  ods] structure. 
f650: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70   The argument sp
f660: 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72  ecifies.** alter
f670: 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c  native low-level
f680: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
f690: 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62  on routines to b
f6a0: 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20  e used in place 
f6b0: 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79  of.** the memory
f6c0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
f6d0: 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20  ines built into 
f6e0: 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74  SQLite.)^ ^SQLit
f6f0: 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f  e makes.** its o
f700: 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
f710: 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  of the content o
f720: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
f730: 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
f740: 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20  cture.** before 
f750: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  the [sqlite3_con
f760: 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75  fig()] call retu
f770: 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  rns.</dd>.**.** 
f780: 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
f790: 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e  GETMALLOC]] <dt>
f7a0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
f7b0: 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20  TMALLOC</dt>.** 
f7c0: 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
f7d0: 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
f7e0: 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
f7f0: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
f800: 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20   an.** instance 
f810: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
f820: 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
f830: 75 63 74 75 72 65 2e 20 20 54 68 65 20 5b 73 71  ucture.  The [sq
f840: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
f850: 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  s].** structure 
f860: 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74  is filled with t
f870: 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  he currently def
f880: 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ined memory allo
f890: 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e  cation routines.
f8a0: 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f  )^.** This optio
f8b0: 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
f8c0: 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65   overload the de
f8d0: 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c  fault memory all
f8e0: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69  ocation.** routi
f8f0: 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70  nes with a wrapp
f900: 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69  er that simulati
f910: 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ons memory alloc
f920: 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72  ation failure or
f930: 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72  .** tracks memor
f940: 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61  y usage, for exa
f950: 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  mple. </dd>.**.*
f960: 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
f970: 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64  G_MEMSTATUS]] <d
f980: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
f990: 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a  MEMSTATUS</dt>.*
f9a0: 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
f9b0: 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65  ion takes single
f9c0: 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70   argument of typ
f9d0: 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74  e int, interpret
f9e0: 65 64 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c  ed as a .** bool
f9f0: 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c  ean, which enabl
fa00: 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74  es or disables t
fa10: 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66  he collection of
fa20: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
fa30: 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 63  on .** statistic
fa40: 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79  s. ^(When memory
fa50: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74   allocation stat
fa60: 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62  istics are disab
fa70: 6c 65 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f 6c  led, the .** fol
fa80: 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e  lowing SQLite in
fa90: 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20  terfaces become 
faa0: 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a  non-operational:
fab0: 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20  .**   <ul>.**   
fac0: 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65  <li> [sqlite3_me
fad0: 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20  mory_used()].** 
fae0: 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
faf0: 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
fb00: 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
fb10: 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
fb20: 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20  _limit64()].**  
fb30: 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73   <li> [sqlite3_s
fb40: 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f  tatus()].**   </
fb50: 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79  ul>)^.** ^Memory
fb60: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74   allocation stat
fb70: 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c  istics are enabl
fb80: 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e  ed by default un
fb90: 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a  less SQLite is.*
fba0: 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  * compiled with 
fbb0: 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f  [SQLITE_DEFAULT_
fbc0: 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20  MEMSTATUS]=0 in 
fbd0: 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72  which case memor
fbe0: 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  y.** allocation 
fbf0: 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64  statistics are d
fc00: 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
fc10: 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a  lt..** </dd>.**.
fc20: 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
fc30: 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74  IG_SCRATCH]] <dt
fc40: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
fc50: 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  CRATCH</dt>.** <
fc60: 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
fc70: 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
fc80: 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
fc90: 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61  r that SQLite ca
fca0: 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72  n use for.** scr
fcb0: 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68  atch memory.  Th
fcc0: 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
fcd0: 67 75 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e  guments:  A poin
fce0: 74 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a  ter an 8-byte.**
fcf0: 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20   aligned memory 
fd00: 62 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63  buffer from whic
fd10: 68 20 74 68 65 20 73 63 72 61 74 63 68 20 61 6c  h the scratch al
fd20: 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62  locations will b
fd30: 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20  e.** drawn, the 
fd40: 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72  size of each scr
fd50: 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  atch allocation 
fd60: 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65  (sz),.** and the
fd70: 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
fd80: 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63  of scratch alloc
fd90: 61 74 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68 65  ations (N).  The
fda0: 20 73 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20   sz.** argument 
fdb0: 6d 75 73 74 20 62 65 20 61 20 6d 75 6c 74 69 70  must be a multip
fdc0: 6c 65 20 6f 66 20 31 36 2e 0a 2a 2a 20 54 68 65  le of 16..** The
fdd0: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
fde0: 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65  must be a pointe
fdf0: 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61  r to an 8-byte a
fe00: 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a  ligned buffer.**
fe10: 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a   of at least sz*
fe20: 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72  N bytes of memor
fe30: 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  y..** ^SQLite wi
fe40: 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74  ll use no more t
fe50: 68 61 6e 20 74 77 6f 20 73 63 72 61 74 63 68 20  han two scratch 
fe60: 62 75 66 66 65 72 73 20 70 65 72 20 74 68 72 65  buffers per thre
fe70: 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f  ad.  So.** N sho
fe80: 75 6c 64 20 62 65 20 73 65 74 20 74 6f 20 74 77  uld be set to tw
fe90: 69 63 65 20 74 68 65 20 65 78 70 65 63 74 65 64  ice the expected
fea0: 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
feb0: 6f 66 20 74 68 72 65 61 64 73 2e 0a 2a 2a 20 5e  of threads..** ^
fec0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65  SQLite will neve
fed0: 72 20 72 65 71 75 69 72 65 20 61 20 73 63 72 61  r require a scra
fee0: 74 63 68 20 62 75 66 66 65 72 20 74 68 61 74 20  tch buffer that 
fef0: 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a  is more than 6.*
ff00: 2a 20 74 69 6d 65 73 20 74 68 65 20 64 61 74 61  * times the data
ff10: 62 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e 20  base page size. 
ff20: 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73  ^If SQLite needs
ff30: 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61   needs additiona
ff40: 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d  l.** scratch mem
ff50: 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20  ory beyond what 
ff60: 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  is provided by t
ff70: 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  his configuratio
ff80: 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a  n option, then .
ff90: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
ffa0: 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73  oc()] will be us
ffb0: 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65  ed to obtain the
ffc0: 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c   memory needed.<
ffd0: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
ffe0: 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
fff0: 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  ACHE]] <dt>SQLIT
10000 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
10010 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  HE</dt>.** <dd> 
10020 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65  ^This option spe
10030 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
10040 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68  memory buffer th
10050 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73  at SQLite can us
10060 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74  e for.** the dat
10070 61 62 61 73 65 20 70 61 67 65 20 63 61 63 68 65  abase page cache
10080 20 77 69 74 68 20 74 68 65 20 64 65 66 61 75 6c   with the defaul
10090 74 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70  t page cache imp
100a0 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a  lementation.  .*
100b0 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61  * This configura
100c0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20  tion should not 
100d0 62 65 20 75 73 65 64 20 69 66 20 61 6e 20 61 70  be used if an ap
100e0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
100f0 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69   page.** cache i
10100 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
10110 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68   loaded using th
10120 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
10130 50 43 41 43 48 45 20 6f 70 74 69 6f 6e 2e 0a 2a  PCACHE option..*
10140 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65  * There are thre
10150 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  e arguments to t
10160 68 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20 70 6f  his option: A po
10170 69 6e 74 65 72 20 74 6f 20 38 2d 62 79 74 65 20  inter to 8-byte 
10180 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72  aligned.** memor
10190 79 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65  y, the size of e
101a0 61 63 68 20 70 61 67 65 20 62 75 66 66 65 72 20  ach page buffer 
101b0 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e 75  (sz), and the nu
101c0 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 28 4e  mber of pages (N
101d0 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67  )..** The sz arg
101e0 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20  ument should be 
101f0 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
10200 6c 61 72 67 65 73 74 20 64 61 74 61 62 61 73 65  largest database
10210 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65   page.** (a powe
10220 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e  r of two between
10230 20 35 31 32 20 61 6e 64 20 33 32 37 36 38 29 20   512 and 32768) 
10240 70 6c 75 73 20 61 20 6c 69 74 74 6c 65 20 65 78  plus a little ex
10250 74 72 61 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  tra for each.** 
10260 70 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54  page header.  ^T
10270 68 65 20 70 61 67 65 20 68 65 61 64 65 72 20 73  he page header s
10280 69 7a 65 20 69 73 20 32 30 20 74 6f 20 34 30 20  ize is 20 to 40 
10290 62 79 74 65 73 20 64 65 70 65 6e 64 69 6e 67 20  bytes depending 
102a0 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f 73 74 20 61  on.** the host a
102b0 72 63 68 69 74 65 63 74 75 72 65 2e 20 20 5e 49  rchitecture.  ^I
102c0 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61  t is harmless, a
102d0 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61  part from the wa
102e0 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20  sted memory,.** 
102f0 74 6f 20 6d 61 6b 65 20 73 7a 20 61 20 6c 69 74  to make sz a lit
10300 74 6c 65 20 74 6f 6f 20 6c 61 72 67 65 2e 20 20  tle too large.  
10310 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67  The first.** arg
10320 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69  ument should poi
10330 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74  nt to an allocat
10340 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20  ion of at least 
10350 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65  sz*N bytes of me
10360 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  mory..** ^SQLite
10370 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65   will use the me
10380 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62 79  mory provided by
10390 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
103a0 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20 69  ent to satisfy i
103b0 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65  ts.** memory nee
103c0 64 73 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  ds for the first
103d0 20 4e 20 70 61 67 65 73 20 74 68 61 74 20 69 74   N pages that it
103e0 20 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20   adds to cache. 
103f0 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a   ^If additional.
10400 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d 65  ** page cache me
10410 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20 62  mory is needed b
10420 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72  eyond what is pr
10430 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20 6f  ovided by this o
10440 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53  ption, then.** S
10450 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73  QLite goes to [s
10460 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
10470 20 66 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f   for the additio
10480 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63  nal storage spac
10490 65 2e 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65  e..** The pointe
104a0 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  r in the first a
104b0 72 67 75 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a 20  rgument must.** 
104c0 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  be aligned to an
104d0 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8-byte boundary
104e0 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62   or subsequent b
104f0 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74  ehavior of SQLit
10500 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 75 6e 64  e.** will be und
10510 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a  efined.</dd>.**.
10520 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
10530 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51  IG_HEAP]] <dt>SQ
10540 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
10550 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
10560 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  his option speci
10570 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
10580 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74  mory buffer that
10590 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65   SQLite will use
105a0 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  .** for all of i
105b0 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72  ts dynamic memor
105c0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
105d0 64 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20  ds beyond those 
105e0 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20  provided.** for 
105f0 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  by [SQLITE_CONFI
10600 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20 5b  G_SCRATCH] and [
10610 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
10620 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65  GECACHE]..** The
10630 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
10640 75 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74  uments: An 8-byt
10650 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65  e aligned pointe
10660 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c  r to the memory,
10670 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
10680 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d  f bytes in the m
10690 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e  emory buffer, an
106a0 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  d the minimum al
106b0 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a  location size..*
106c0 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20  * ^If the first 
106d0 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d  pointer (the mem
106e0 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20  ory pointer) is 
106f0 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74  NULL, then SQLit
10700 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20  e reverts.** to 
10710 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c  using its defaul
10720 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
10730 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d  or (the system m
10740 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e  alloc() implemen
10750 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f  tation),.** undo
10760 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e  ing any prior in
10770 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c  vocation of [SQL
10780 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
10790 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  C].  ^If the.** 
107a0 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69  memory pointer i
107b0 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65  s not NULL and e
107c0 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e  ither [SQLITE_EN
107d0 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72  ABLE_MEMSYS3] or
107e0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  .** [SQLITE_ENAB
107f0 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65 20  LE_MEMSYS5] are 
10800 64 65 66 69 6e 65 64 2c 20 74 68 65 6e 20 74 68  defined, then th
10810 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65  e alternative me
10820 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
10830 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20  r is engaged to 
10840 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51  handle all of SQ
10850 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c  Lites memory all
10860 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a  ocation needs..*
10870 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e  * The first poin
10880 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20  ter (the memory 
10890 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65  pointer) must be
108a0 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38   aligned to an 8
108b0 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72  -byte.** boundar
108c0 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20  y or subsequent 
108d0 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69  behavior of SQLi
108e0 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66  te will be undef
108f0 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e  ined..** The min
10900 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  imum allocation 
10910 73 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 61  size is capped a
10920 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61  t 2**12. Reasona
10930 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f  ble values.** fo
10940 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  r the minimum al
10950 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72  location size ar
10960 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32  e 2**5 through 2
10970 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  **8.</dd>.**.** 
10980 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
10990 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49  MUTEX]] <dt>SQLI
109a0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c  TE_CONFIG_MUTEX<
109b0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
109c0 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
109d0 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
109e0 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
109f0 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69  inter to an.** i
10a00 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
10a10 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
10a20 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
10a30 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  .  The argument 
10a40 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74  specifies.** alt
10a50 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76  ernative low-lev
10a60 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  el mutex routine
10a70 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20  s to be used in 
10a80 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74  place.** the mut
10a90 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c  ex routines buil
10aa0 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e  t into SQLite.)^
10ab0 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20    ^SQLite makes 
10ac0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
10ad0 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
10ae0 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
10af0 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
10b00 65 20 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c  e before the cal
10b10 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
10b20 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72  _config()] retur
10b30 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69  ns. ^If SQLite i
10b40 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
10b50 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
10b60 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
10b70 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
10b80 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
10b90 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65  tion then.** the
10ba0 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67   entire mutexing
10bb0 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d   subsystem is om
10bc0 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62  itted from the b
10bd0 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63  uild and hence c
10be0 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  alls to.** [sqli
10bf0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
10c00 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
10c10 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69  NFIG_MUTEX confi
10c20 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
10c30 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  will.** return [
10c40 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f  SQLITE_ERROR].</
10c50 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
10c60 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
10c70 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  EX]] <dt>SQLITE_
10c80 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c  CONFIG_GETMUTEX<
10c90 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
10ca0 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
10cb0 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
10cc0 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
10cd0 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69  inter to an.** i
10ce0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
10cf0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
10d00 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
10d10 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  The.** [sqlit
10d20 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
10d30 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69  ].** structure i
10d40 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  s filled with th
10d50 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  e currently defi
10d60 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  ned mutex routin
10d70 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70  es.)^.** This op
10d80 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64  tion can be used
10d90 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65   to overload the
10da0 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61   default mutex a
10db0 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75  llocation.** rou
10dc0 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61  tines with a wra
10dd0 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61  pper used to tra
10de0 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66  ck mutex usage f
10df0 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a  or performance.*
10e00 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74  * profiling or t
10e10 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d  esting, for exam
10e20 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74  ple.   ^If SQLit
10e30 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
10e40 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
10e50 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
10e60 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
10e70 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
10e80 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
10e90 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78  the entire mutex
10ea0 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73  ing subsystem is
10eb0 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
10ec0 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63  e build and henc
10ed0 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73  e calls to.** [s
10ee0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
10ef0 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
10f00 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
10f10 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
10f20 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65  ption will.** re
10f30 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
10f40 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  OR].</dd>.**.** 
10f50 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
10f60 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e  LOOKASIDE]] <dt>
10f70 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
10f80 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20  OKASIDE</dt>.** 
10f90 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
10fa0 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67  on takes two arg
10fb0 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65  uments that dete
10fc0 72 6d 69 6e 65 20 74 68 65 20 64 65 66 61 75 6c  rmine the defaul
10fd0 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t.** memory allo
10fe0 63 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 6c  cation for the l
10ff0 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
11000 61 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20 65 61 63  allocator on eac
11010 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  h.** [database c
11020 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65  onnection].  The
11030 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
11040 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f  is the.** size o
11050 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65  f each lookaside
11060 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64   buffer slot and
11070 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74   the second is t
11080 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
11090 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20  slots allocated 
110a0 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65  to each database
110b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20   connection.)^  
110c0 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65  ^(This option se
110d0 74 73 20 74 68 65 0a 2a 2a 20 3c 69 3e 64 65 66  ts the.** <i>def
110e0 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69  ault</i> lookasi
110f0 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51  de size. The [SQ
11100 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
11110 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 65 72 62  OKASIDE].** verb
11120 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f   to [sqlite3_db_
11130 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65  config()] can be
11140 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20   used to change 
11150 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a  the lookaside.**
11160 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
11170 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e  n individual con
11180 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64  nections.)^ </dd
11190 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
111a0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d  _CONFIG_PCACHE]]
111b0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
111c0 49 47 5f 50 43 41 43 48 45 3c 2f 64 74 3e 0a 2a  IG_PCACHE</dt>.*
111d0 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70  * <dd> ^(This op
111e0 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
111f0 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
11200 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ch is a pointer 
11210 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69 74 65  to.** an [sqlite
11220 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
11230 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20  ] object.  This 
11240 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 73  object specifies
11250 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a   the interface.*
11260 2a 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61  * to a custom pa
11270 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ge cache impleme
11280 6e 74 61 74 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c  ntation.)^  ^SQL
11290 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ite makes a copy
112a0 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63   of the.** objec
112b0 74 20 61 6e 64 20 75 73 65 73 20 69 74 20 66 6f  t and uses it fo
112c0 72 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d  r page cache mem
112d0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e  ory allocations.
112e0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
112f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
11300 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49  CACHE]] <dt>SQLI
11310 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
11320 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  CHE</dt>.** <dd>
11330 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
11340 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
11350 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
11360 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
11370 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  ** [sqlite3_pcac
11380 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  he_methods] obje
11390 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69  ct.  SQLite copi
113a0 65 73 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  es of the curren
113b0 74 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20  t.** page cache 
113c0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
113d0 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e  nto that object.
113e0 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  )^ </dd>.**.** [
113f0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  [SQLITE_CONFIG_L
11400 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OG]] <dt>SQLITE_
11410 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a  CONFIG_LOG</dt>.
11420 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c  ** <dd> ^The SQL
11430 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f  ITE_CONFIG_LOG o
11440 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20  ption takes two 
11450 61 72 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69  arguments: a poi
11460 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e  nter to a.** fun
11470 63 74 69 6f 6e 20 77 69 74 68 20 61 20 63 61 6c  ction with a cal
11480 6c 20 73 69 67 6e 61 74 75 72 65 20 6f 66 20 76  l signature of v
11490 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74  oid(*)(void*,int
114a0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a  ,const char*), .
114b0 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74 65 72  ** and a pointer
114c0 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74 68   to void. ^If th
114d0 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74  e function point
114e0 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  er is not NULL, 
114f0 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64  it is.** invoked
11500 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67   by [sqlite3_log
11510 28 29 5d 20 74 6f 20 70 72 6f 63 65 73 73 20 65  ()] to process e
11520 61 63 68 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e  ach logging even
11530 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66  t.  ^If the.** f
11540 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20  unction pointer 
11550 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71  is NULL, the [sq
11560 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74  lite3_log()] int
11570 65 72 66 61 63 65 20 62 65 63 6f 6d 65 73 20 61  erface becomes a
11580 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20   no-op..** ^The 
11590 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 74 68 61  void pointer tha
115a0 74 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  t is the second 
115b0 61 72 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49  argument to SQLI
115c0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73  TE_CONFIG_LOG is
115d0 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 72 6f 75  .** passed throu
115e0 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20  gh as the first 
115f0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
11600 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
11610 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66  ined logger.** f
11620 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76 65 72  unction whenever
11630 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 69   that function i
11640 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65  s invoked.  ^The
11650 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
11660 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67  r to.** the logg
11670 65 72 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61  er function is a
11680 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 69 72   copy of the fir
11690 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
116a0 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
116b0 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f  g.** [sqlite3_lo
116c0 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73  g()] call and is
116d0 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 62 65 20   intended to be 
116e0 61 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  a [result code] 
116f0 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64  or an.** [extend
11700 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e  ed result code].
11710 20 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72    ^The third par
11720 61 6d 65 74 65 72 20 70 61 73 73 65 64 20 74 6f  ameter passed to
11730 20 74 68 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a   the logger is.*
11740 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65 20 61 66  * log message af
11750 74 65 72 20 66 6f 72 6d 61 74 74 69 6e 67 20 76  ter formatting v
11760 69 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ia [sqlite3_snpr
11770 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  intf()]..** The 
11780 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20 69  SQLite logging i
11790 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20  nterface is not 
117a0 72 65 65 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c  reentrant; the l
117b0 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a  ogger function.*
117c0 2a 20 73 75 70 70 6c 69 65 64 20 62 79 20 74 68  * supplied by th
117d0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
117e0 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e  st not invoke an
117f0 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  y SQLite interfa
11800 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74  ce..** In a mult
11810 69 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c 69  i-threaded appli
11820 63 61 74 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c  cation, the appl
11830 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
11840 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69  logger.** functi
11850 6f 6e 20 6d 75 73 74 20 62 65 20 74 68 72 65 61  on must be threa
11860 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a  dsafe. </dd>.**.
11870 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
11880 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c  IG_URI]] <dt>SQL
11890 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a  ITE_CONFIG_URI.*
118a0 2a 20 3c 64 64 3e 20 54 68 69 73 20 6f 70 74 69  * <dd> This opti
118b0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
118c0 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79  e argument of ty
118d0 70 65 20 69 6e 74 2e 20 49 66 20 6e 6f 6e 2d 7a  pe int. If non-z
118e0 65 72 6f 2c 20 74 68 65 6e 0a 2a 2a 20 55 52 49  ero, then.** URI
118f0 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f   handling is glo
11900 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49  bally enabled. I
11910 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
11920 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52  is zero, then UR
11930 49 20 68 61 6e 64 6c 69 6e 67 0a 2a 2a 20 69 73  I handling.** is
11940 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c   globally disabl
11950 65 64 2e 20 49 66 20 55 52 49 20 68 61 6e 64 6c  ed. If URI handl
11960 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20  ing is globally 
11970 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c  enabled, all fil
11980 65 6e 61 6d 65 73 0a 2a 2a 20 70 61 73 73 65 64  enames.** passed
11990 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
119a0 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
119b0 70 65 6e 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69  pen_v2()], [sqli
119c0 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72  te3_open16()] or
119d0 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61 73  .** specified as
119e0 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48   part of [ATTACH
119f0 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69  ] commands are i
11a00 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52  nterpreted as UR
11a10 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a  Is, regardless.*
11a20 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  * of whether or 
11a30 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  not the [SQLITE_
11a40 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69  OPEN_URI] flag i
11a50 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 64  s set when the d
11a60 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
11a70 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e  ction is opened.
11a80 20 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c   If it is global
11a90 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c  ly disabled, fil
11aa0 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e  enames are.** on
11ab0 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  ly interpreted a
11ac0 73 20 55 52 49 73 20 69 66 20 74 68 65 20 53 51  s URIs if the SQ
11ad0 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c  LITE_OPEN_URI fl
11ae0 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74  ag is set when t
11af0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  he.** database c
11b00 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65  onnection is ope
11b10 6e 65 64 2e 20 42 79 20 64 65 66 61 75 6c 74 2c  ned. By default,
11b20 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73   URI handling is
11b30 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73   globally.** dis
11b40 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66 61 75  abled. The defau
11b50 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62 65 20  lt value may be 
11b60 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d 70 69  changed by compi
11b70 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a 2a 2a  ling with the.**
11b80 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49   [SQLITE_USE_URI
11b90 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64  ] symbol defined
11ba0 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  ..** </dl>.*/.#d
11bb0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
11bc0 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
11bd0 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    1  /* nil */.#
11be0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
11bf0 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
11c00 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a     2  /* nil */.
11c10 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
11c20 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
11c30 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f      3  /* nil */
11c40 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
11c50 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20  CONFIG_MALLOC   
11c60 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74       4  /* sqlit
11c70 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20  e3_mem_methods* 
11c80 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
11c90 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
11ca0 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c  OC     5  /* sql
11cb0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
11cc0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
11cd0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
11ce0 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76  CH       6  /* v
11cf0 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e  oid*, int sz, in
11d00 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  t N */.#define S
11d10 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
11d20 45 43 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a  ECACHE     7  /*
11d30 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20   void*, int sz, 
11d40 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65  int N */.#define
11d50 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48   SQLITE_CONFIG_H
11d60 45 41 50 20 20 20 20 20 20 20 20 20 20 38 20 20  EAP          8  
11d70 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42  /* void*, int nB
11d80 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a  yte, int min */.
11d90 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
11da0 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20  ONFIG_MEMSTATUS 
11db0 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61      9  /* boolea
11dc0 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
11dd0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
11de0 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73          10  /* s
11df0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
11e00 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
11e10 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
11e20 45 54 4d 55 54 45 58 20 20 20 20 20 31 31 20 20  ETMUTEX     11  
11e30 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  /* sqlite3_mutex
11e40 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20  _methods* */./* 
11e50 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54  previously SQLIT
11e60 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c  E_CONFIG_CHUNKAL
11e70 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69 73 20  LOC 12 which is 
11e80 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a  now unused. */ .
11e90 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
11ea0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
11eb0 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e     13  /* int in
11ec0 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
11ed0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
11ee0 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20 73  E       14  /* s
11ef0 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
11f00 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
11f10 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
11f20 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20  GETPCACHE    15 
11f30 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63   /* sqlite3_pcac
11f40 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  he_methods* */.#
11f50 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
11f60 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20  NFIG_LOG        
11f70 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20    16  /* xFunc, 
11f80 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  void* */.#define
11f90 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55   SQLITE_CONFIG_U
11fa0 52 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20  RI          17  
11fb0 2f 2a 20 69 6e 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  /* int */../*.**
11fc0 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62   CAPI3REF: Datab
11fd0 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43  ase Connection C
11fe0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74  onfiguration Opt
11ff0 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
12000 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74   constants are t
12010 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74  he available int
12020 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69  eger configurati
12030 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a  on options that.
12040 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64  ** can be passed
12050 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   as the second a
12060 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
12070 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
12080 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  g()] interface..
12090 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67  **.** New config
120a0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
120b0 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
120c0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
120d0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78  of SQLite..** Ex
120e0 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  isting configura
120f0 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67  tion options mig
12100 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75  ht be discontinu
12110 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ed.  Application
12120 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63  s.** should chec
12130 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64  k the return cod
12140 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  e from [sqlite3_
12150 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20  db_config()] to 
12160 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a  make sure that.*
12170 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65  * the call worke
12180 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  d.  ^The [sqlite
12190 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
121a0 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65  nterface will re
121b0 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65  turn a.** non-ze
121c0 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ro [error code] 
121d0 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65  if a discontinue
121e0 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64  d or unsupported
121f0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
12200 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f  ption.** is invo
12210 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ked..**.** <dl>.
12220 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
12230 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
12240 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
12250 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
12260 20 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61   three additiona
12270 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  l arguments that
12280 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a   determine the .
12290 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  ** [lookaside me
122a0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20  mory allocator] 
122b0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f  configuration fo
122c0 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  r the [database 
122d0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20  connection]..** 
122e0 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
122f0 65 6e 74 20 28 74 68 65 20 74 68 69 72 64 20 70  ent (the third p
12300 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
12310 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
12320 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65  ] is a.** pointe
12330 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75  r to a memory bu
12340 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20  ffer to use for 
12350 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
12360 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  ..** ^The first 
12370 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74  argument after t
12380 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  he SQLITE_DBCONF
12390 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72  IG_LOOKASIDE ver
123a0 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c  b.** may be NULL
123b0 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 53   in which case S
123c0 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63  QLite will alloc
123d0 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61  ate the.** looka
123e0 73 69 64 65 20 62 75 66 66 65 72 20 69 74 73 65  side buffer itse
123f0 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  lf using [sqlite
12400 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68  3_malloc()]. ^Th
12410 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
12420 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65  t is the.** size
12430 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69   of each lookasi
12440 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20  de buffer slot. 
12450 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75   ^The third argu
12460 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62  ment is the numb
12470 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20  er of.** slots. 
12480 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   The size of the
12490 20 62 75 66 66 65 72 20 69 6e 20 74 68 65 20 66   buffer in the f
124a0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
124b0 73 74 20 62 65 20 67 72 65 61 74 65 72 20 74 68  st be greater th
124c0 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74  an.** or equal t
124d0 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66  o the product of
124e0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20   the second and 
124f0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e  third arguments.
12500 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20    The buffer.** 
12510 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20  must be aligned 
12520 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75  to an 8-byte bou
12530 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20  ndary.  ^If the 
12540 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
12550 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43  to.** SQLITE_DBC
12560 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
12570 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c  is not a multipl
12580 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e  e of 8, it is in
12590 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e  ternally.** roun
125a0 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20  ded down to the 
125b0 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c  next smaller mul
125c0 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54  tiple of 8.  ^(T
125d0 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  he lookaside mem
125e0 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  ory.** configura
125f0 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61 62  tion for a datab
12600 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  ase connection c
12610 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67  an only be chang
12620 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20  ed when that.** 
12630 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f  connection is no
12640 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e  t currently usin
12650 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  g lookaside memo
12660 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72 20  ry, or in other 
12670 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68  words.** when th
12680 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75 65  e "current value
12690 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  " returned by.**
126a0 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61   [sqlite3_db_sta
126b0 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43  tus](D,[SQLITE_C
126c0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
126d0 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a  ,...) is zero..*
126e0 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f  * Any attempt to
126f0 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b   change the look
12700 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e  aside memory con
12710 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e 20  figuration when 
12720 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d  lookaside.** mem
12730 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c 65  ory is in use le
12740 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67 75  aves the configu
12750 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64  ration unchanged
12760 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a   and returns .**
12770 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29   [SQLITE_BUSY].)
12780 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  ^</dd>.**.** <dt
12790 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
127a0 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74  _ENABLE_FKEY</dt
127b0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
127c0 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
127d0 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
127e0 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 63 65 6d  ble the enforcem
127f0 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69  ent of.** [forei
12800 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e  gn key constrain
12810 74 73 5d 2e 20 20 54 68 65 72 65 20 73 68 6f 75  ts].  There shou
12820 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69  ld be two additi
12830 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a  onal arguments..
12840 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
12850 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65  ument is an inte
12860 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74  ger which is 0 t
12870 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 65 6e 66  o disable FK enf
12880 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73  orcement,.** pos
12890 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20  itive to enable 
128a0 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f  FK enforcement o
128b0 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65  r negative to le
128c0 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  ave FK enforceme
128d0 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e  nt.** unchanged.
128e0 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
128f0 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
12900 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
12910 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20  r into which.** 
12920 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
12930 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
12940 65 74 68 65 72 20 46 4b 20 65 6e 66 6f 72 63 65  ether FK enforce
12950 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f 72 20 6f  ment is off or o
12960 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  n.** following t
12970 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73  his call.  The s
12980 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
12990 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f  may be a NULL po
129a0 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69  inter, in.** whi
129b0 63 68 20 63 61 73 65 20 74 68 65 20 46 4b 20 65  ch case the FK e
129c0 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 74 74 69  nforcement setti
129d0 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74  ng is not report
129e0 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a  ed back. </dd>.*
129f0 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
12a00 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
12a10 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20  TRIGGER</dt>.** 
12a20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
12a30 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61  n is used to ena
12a40 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 5b  ble or disable [
12a50 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c  CREATE TRIGGER |
12a60 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54   triggers]..** T
12a70 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74  here should be t
12a80 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72  wo additional ar
12a90 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20  guments..** The 
12aa0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
12ab0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
12ac0 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  ch is 0 to disab
12ad0 6c 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20  le triggers,.** 
12ae0 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62  positive to enab
12af0 6c 65 20 74 72 69 67 67 65 72 73 20 6f 72 20 6e  le triggers or n
12b00 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65  egative to leave
12b10 20 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63   the setting unc
12b20 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73  hanged..** The s
12b30 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
12b40 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
12b50 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20  an integer into 
12b60 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74  which.** is writ
12b70 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e  ten 0 or 1 to in
12b80 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 74  dicate whether t
12b90 72 69 67 67 65 72 73 20 61 72 65 20 64 69 73 61  riggers are disa
12ba0 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a  bled or enabled.
12bb0 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69  ** following thi
12bc0 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63  s call.  The sec
12bd0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61  ond parameter ma
12be0 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  y be a NULL poin
12bf0 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68  ter, in.** which
12c00 20 63 61 73 65 20 74 68 65 20 74 72 69 67 67 65   case the trigge
12c10 72 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74  r setting is not
12c20 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20   reported back. 
12c30 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c  </dd>.**.** </dl
12c40 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
12c50 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
12c60 4b 41 53 49 44 45 20 20 20 20 20 20 20 31 30 30  KASIDE       100
12c70 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20  1  /* void* int 
12c80 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
12c90 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
12ca0 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 31  NABLE_FKEY     1
12cb0 30 30 32 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  002  /* int int*
12cc0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
12cd0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
12ce0 4c 45 5f 54 52 49 47 47 45 52 20 20 31 30 30 33  LE_TRIGGER  1003
12cf0 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f    /* int int* */
12d00 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
12d10 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73  F: Enable Or Dis
12d20 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65  able Extended Re
12d30 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  sult Codes.**.**
12d40 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
12d50 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
12d60 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e  des() routine en
12d70 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
12d80 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64  s the.** [extend
12d90 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
12da0 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69   feature of SQLi
12db0 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65  te. ^The extende
12dc0 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65  d result.** code
12dd0 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62  s are disabled b
12de0 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69  y default for hi
12df0 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69  storical compati
12e00 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73  bility..*/.int s
12e10 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
12e20 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c  result_codes(sql
12e30 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66  ite3*, int onoff
12e40 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
12e50 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20  EF: Last Insert 
12e60 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61 63  Rowid.**.** ^Eac
12e70 68 20 65 6e 74 72 79 20 69 6e 20 61 6e 20 53 51  h entry in an SQ
12e80 4c 69 74 65 20 74 61 62 6c 65 20 68 61 73 20 61  Lite table has a
12e90 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73   unique 64-bit s
12ea0 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72  igned.** integer
12eb0 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20   key called the 
12ec0 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22  [ROWID | "rowid"
12ed0 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73  ]. ^The rowid is
12ee0 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c   always availabl
12ef0 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63  e.** as an undec
12f00 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d  lared column nam
12f10 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f  ed ROWID, OID, o
12f20 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e  r _ROWID_ as lon
12f30 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61  g as those.** na
12f40 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f  mes are not also
12f50 20 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 69   used by explici
12f60 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c  tly declared col
12f70 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65  umns. ^If.** the
12f80 20 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c   table has a col
12f90 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54  umn of type [INT
12fa0 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59  EGER PRIMARY KEY
12fb0 5d 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75  ] then that colu
12fc0 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72  mn.** is another
12fd0 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72   alias for the r
12fe0 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  owid..**.** ^Thi
12ff0 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
13000 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66  s the [rowid] of
13010 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
13020 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b  .** successful [
13030 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 74 68 65  INSERT] into the
13040 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20 74   database from t
13050 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
13060 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74  nection].** in t
13070 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
13080 74 2e 20 20 5e 41 73 20 6f 66 20 53 51 4c 69 74  t.  ^As of SQLit
13090 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c  e version 3.7.7,
130a0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 73 0a 2a   this routines.*
130b0 2a 20 72 65 63 6f 72 64 73 20 74 68 65 20 6c 61  * records the la
130c0 73 74 20 69 6e 73 65 72 74 20 72 6f 77 69 64 20  st insert rowid 
130d0 6f 66 20 62 6f 74 68 20 6f 72 64 69 6e 61 72 79  of both ordinary
130e0 20 74 61 62 6c 65 73 20 61 6e 64 20 5b 76 69 72   tables and [vir
130f0 74 75 61 6c 20 74 61 62 6c 65 73 5d 2e 0a 2a 2a  tual tables]..**
13100 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66   ^If no successf
13110 75 6c 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a 20  ul [INSERT]s.** 
13120 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72  have ever occurr
13130 65 64 20 6f 6e 20 74 68 61 74 20 64 61 74 61 62  ed on that datab
13140 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20  ase connection, 
13150 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64  zero is returned
13160 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20  ..**.** ^(If an 
13170 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20  [INSERT] occurs 
13180 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72  within a trigger
13190 20 6f 72 20 77 69 74 68 69 6e 20 61 20 5b 76 69   or within a [vi
131a0 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20  rtual table].** 
131b0 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 69  method, then thi
131c0 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72  s routine will r
131d0 65 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64  eturn the [rowid
131e0 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65  ] of the inserte
131f0 64 0a 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67  d.** row as long
13200 20 61 73 20 74 68 65 20 74 72 69 67 67 65 72 20   as the trigger 
13210 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  or virtual table
13220 20 6d 65 74 68 6f 64 20 69 73 20 72 75 6e 6e 69   method is runni
13230 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20  ng..** But once 
13240 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76  the trigger or v
13250 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74  irtual table met
13260 68 6f 64 20 65 6e 64 73 2c 20 74 68 65 20 76 61  hod ends, the va
13270 6c 75 65 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a  lue returned .**
13280 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65   by this routine
13290 20 72 65 76 65 72 74 73 20 74 6f 20 77 68 61 74   reverts to what
132a0 20 69 74 20 77 61 73 20 62 65 66 6f 72 65 20 74   it was before t
132b0 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  he trigger or vi
132c0 72 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d  rtual.** table m
132d0 65 74 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a  ethod began.)^.*
132e0 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54  *.** ^An [INSERT
132f0 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65  ] that fails due
13300 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74   to a constraint
13310 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f   violation is no
13320 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  t a.** successfu
13330 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64  l [INSERT] and d
13340 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
13350 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
13360 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75  d by this.** rou
13370 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53  tine.  ^Thus INS
13380 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53  ERT OR FAIL, INS
13390 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49  ERT OR IGNORE, I
133a0 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43  NSERT OR ROLLBAC
133b0 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54  K,.** and INSERT
133c0 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e   OR ABORT make n
133d0 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  o changes to the
133e0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
133f0 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
13400 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65   when their inse
13410 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28  rtion fails.  ^(
13420 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52  When INSERT OR R
13430 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e  EPLACE.** encoun
13440 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e  ters a constrain
13450 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20  t violation, it 
13460 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20  does not fail.  
13470 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f  The.** INSERT co
13480 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c  ntinues to compl
13490 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65  etion after dele
134a0 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63  ting rows that c
134b0 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e  aused.** the con
134c0 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20  straint problem 
134d0 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50  so INSERT OR REP
134e0 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73  LACE will always
134f0 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72   change.** the r
13500 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
13510 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e  his interface.)^
13520 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20  .**.** ^For the 
13530 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73  purposes of this
13540 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e   routine, an [IN
13550 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65  SERT] is conside
13560 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63  red to.** be suc
13570 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20  cessful even if 
13580 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74  it is subsequent
13590 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a  ly rolled back..
135a0 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
135b0 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c  ion is accessibl
135c0 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  e to SQL stateme
135d0 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b  nts via the.** [
135e0 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
135f0 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  d() SQL function
13600 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65  ]..**.** If a se
13610 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70 65  parate thread pe
13620 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e  rforms a new [IN
13630 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d  SERT] on the sam
13640 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
13650 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74  nnection while t
13660 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  he [sqlite3_last
13670 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
13680 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
13690 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73  running and thus
136a0 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73   changes the las
136b0 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d  t insert [rowid]
136c0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61  ,.** then the va
136d0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
136e0 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
136f0 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73  sert_rowid()] is
13700 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c  .** unpredictabl
13710 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20  e and might not 
13720 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65  equal either the
13730 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a   old or the new.
13740 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b  ** last insert [
13750 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74  rowid]..*/.sqlit
13760 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
13770 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
13780 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  id(sqlite3*);../
13790 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
137a0 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20  ount The Number 
137b0 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64  Of Rows Modified
137c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
137d0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
137e0 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61  e number of data
137f0 62 61 73 65 20 72 6f 77 73 20 74 68 61 74 20 77  base rows that w
13800 65 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f  ere changed.** o
13810 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65  r inserted or de
13820 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73  leted by the mos
13830 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c  t recently compl
13840 65 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  eted SQL stateme
13850 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61  nt.** on the [da
13860 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
13870 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 20  n] specified by 
13880 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
13890 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63  ter..** ^(Only c
138a0 68 61 6e 67 65 73 20 74 68 61 74 20 61 72 65 20  hanges that are 
138b0 64 69 72 65 63 74 6c 79 20 73 70 65 63 69 66 69  directly specifi
138c0 65 64 20 62 79 20 74 68 65 20 5b 49 4e 53 45 52  ed by the [INSER
138d0 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a  T], [UPDATE],.**
138e0 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61   or [DELETE] sta
138f0 74 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74  tement are count
13900 65 64 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63  ed.  Auxiliary c
13910 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79  hanges caused by
13920 0a 2a 2a 20 74 72 69 67 67 65 72 73 20 6f 72 20  .** triggers or 
13930 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74  [foreign key act
13940 69 6f 6e 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f  ions] are not co
13950 75 6e 74 65 64 2e 29 5e 20 55 73 65 20 74 68 65  unted.)^ Use the
13960 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  .** [sqlite3_tot
13970 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75  al_changes()] fu
13980 6e 63 74 69 6f 6e 20 74 6f 20 66 69 6e 64 20 74  nction to find t
13990 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20  he total number 
139a0 6f 66 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69 6e  of changes.** in
139b0 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73 20  cluding changes 
139c0 63 61 75 73 65 64 20 62 79 20 74 72 69 67 67 65  caused by trigge
139d0 72 73 20 61 6e 64 20 66 6f 72 65 69 67 6e 20 6b  rs and foreign k
139e0 65 79 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  ey actions..**.*
139f0 2a 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20  * ^Changes to a 
13a00 76 69 65 77 20 74 68 61 74 20 61 72 65 20 73 69  view that are si
13a10 6d 75 6c 61 74 65 64 20 62 79 20 61 6e 20 5b 49  mulated by an [I
13a20 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
13a30 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f  r].** are not co
13a40 75 6e 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61  unted.  Only rea
13a50 6c 20 74 61 62 6c 65 20 63 68 61 6e 67 65 73 20  l table changes 
13a60 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a  are counted..**.
13a70 2a 2a 20 5e 28 41 20 22 72 6f 77 20 63 68 61 6e  ** ^(A "row chan
13a80 67 65 22 20 69 73 20 61 20 63 68 61 6e 67 65 20  ge" is a change 
13a90 74 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20  to a single row 
13aa0 6f 66 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c  of a single tabl
13ab0 65 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 61  e.** caused by a
13ac0 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45  n INSERT, DELETE
13ad0 2c 20 6f 72 20 55 50 44 41 54 45 20 73 74 61 74  , or UPDATE stat
13ae0 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 61  ement.  Rows tha
13af0 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 64  t.** are changed
13b00 20 61 73 20 73 69 64 65 20 65 66 66 65 63 74 73   as side effects
13b10 20 6f 66 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f   of [REPLACE] co
13b20 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74  nstraint resolut
13b30 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b  ion,.** rollback
13b40 2c 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69  , ABORT processi
13b50 6e 67 2c 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d  ng, [DROP TABLE]
13b60 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f 74 68 65  , or by any othe
13b70 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20  r.** mechanisms 
13b80 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20  do not count as 
13b90 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67  direct row chang
13ba0 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74  es.)^.**.** A "t
13bb0 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 22 20  rigger context" 
13bc0 69 73 20 61 20 73 63 6f 70 65 20 6f 66 20 65 78  is a scope of ex
13bd0 65 63 75 74 69 6f 6e 20 74 68 61 74 20 62 65 67  ecution that beg
13be0 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20  ins and.** ends 
13bf0 77 69 74 68 20 74 68 65 20 73 63 72 69 70 74 20  with the script 
13c00 6f 66 20 61 20 5b 43 52 45 41 54 45 20 54 52 49  of a [CREATE TRI
13c10 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d 2e  GGER | trigger].
13c20 20 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c 20 73 74   .** Most SQL st
13c30 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20  atements are.** 
13c40 65 76 61 6c 75 61 74 65 64 20 6f 75 74 73 69 64  evaluated outsid
13c50 65 20 6f 66 20 61 6e 79 20 74 72 69 67 67 65 72  e of any trigger
13c60 2e 20 20 54 68 69 73 20 69 73 20 74 68 65 20 22  .  This is the "
13c70 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72  top level".** tr
13c80 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 20  igger context.  
13c90 49 66 20 61 20 74 72 69 67 67 65 72 20 66 69 72  If a trigger fir
13ca0 65 73 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20  es from the top 
13cb0 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20  level, a.** new 
13cc0 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 20  trigger context 
13cd0 69 73 20 65 6e 74 65 72 65 64 20 66 6f 72 20 74  is entered for t
13ce0 68 65 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74  he duration of t
13cf0 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67  hat one.** trigg
13d00 65 72 2e 20 20 53 75 62 74 72 69 67 67 65 72 73  er.  Subtriggers
13d10 20 63 72 65 61 74 65 20 73 75 62 63 6f 6e 74 65   create subconte
13d20 78 74 73 20 66 6f 72 20 74 68 65 69 72 20 64 75  xts for their du
13d30 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43  ration..**.** ^C
13d40 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
13d50 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69  exec()] or [sqli
13d60 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75  te3_step()] recu
13d70 72 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20  rsively does.** 
13d80 6e 6f 74 20 63 72 65 61 74 65 20 61 20 6e 65 77  not create a new
13d90 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
13da0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  ..**.** ^This fu
13db0 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
13dc0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 69 72  he number of dir
13dd0 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20  ect row changes 
13de0 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72  in the.** most r
13df0 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50  ecent INSERT, UP
13e00 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20  DATE, or DELETE 
13e10 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
13e20 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69   the same.** tri
13e30 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a  gger context..**
13e40 0a 2a 2a 20 5e 54 68 75 73 2c 20 77 68 65 6e 20  .** ^Thus, when 
13e50 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
13e60 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20  top level, this 
13e70 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
13e80 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
13e90 66 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65  f changes in the
13ea0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53   most recent INS
13eb0 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
13ec0 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61  DELETE.** that a
13ed0 6c 73 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20  lso occurred at 
13ee0 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20  the top level.  
13ef0 5e 28 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64  ^(Within the bod
13f00 79 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c 0a  y of a trigger,.
13f10 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  ** the sqlite3_c
13f20 68 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61  hanges() interfa
13f30 63 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64  ce can be called
13f40 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d   to find the num
13f50 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65  ber of.** change
13f60 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65  s in the most re
13f70 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64  cently completed
13f80 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
13f90 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74   or DELETE.** st
13fa0 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74  atement within t
13fb0 68 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73  he body of the s
13fc0 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20  ame trigger..** 
13fd0 48 6f 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d  However, the num
13fe0 62 65 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65  ber returned doe
13ff0 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68  s not include ch
14000 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65 64 20  anges.** caused 
14010 62 79 20 73 75 62 74 72 69 67 67 65 72 73 20 73  by subtriggers s
14020 69 6e 63 65 20 74 68 6f 73 65 20 68 61 76 65 20  ince those have 
14030 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78  their own contex
14040 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  t.)^.**.** See a
14050 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33  lso the [sqlite3
14060 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
14070 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  ] interface, the
14080 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67  .** [count_chang
14090 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20  es pragma], and 
140a0 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53  the [changes() S
140b0 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
140c0 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
140d0 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
140e0 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
140f0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
14100 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20  ection.** while 
14110 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73  [sqlite3_changes
14120 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ()] is running t
14130 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65  hen the value re
14140 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70  turned.** is unp
14150 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e  redictable and n
14160 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a  ot meaningful..*
14170 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68  /.int sqlite3_ch
14180 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b  anges(sqlite3*);
14190 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
141a0 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f  : Total Number O
141b0 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a  f Rows Modified.
141c0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
141d0 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
141e0 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63   number of row c
141f0 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79  hanges caused by
14200 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55   [INSERT],.** [U
14210 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54  PDATE] or [DELET
14220 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69  E] statements si
14230 6e 63 65 20 74 68 65 20 5b 64 61 74 61 62 61 73  nce the [databas
14240 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61  e connection] wa
14250 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54  s opened..** ^(T
14260 68 65 20 63 6f 75 6e 74 20 72 65 74 75 72 6e 65  he count returne
14270 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f 74  d by sqlite3_tot
14280 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 63  al_changes() inc
14290 6c 75 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 65  ludes all change
142a0 73 0a 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b 43  s.** from all [C
142b0 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20  REATE TRIGGER | 
142c0 74 72 69 67 67 65 72 5d 20 63 6f 6e 74 65 78 74  trigger] context
142d0 73 20 61 6e 64 20 63 68 61 6e 67 65 73 20 6d 61  s and changes ma
142e0 64 65 20 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 67  de by.** [foreig
142f0 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20  n key actions]. 
14300 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20  However,.** the 
14310 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69  count does not i
14320 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75  nclude changes u
14330 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
14340 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74   [REPLACE] const
14350 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f  raints,.** do ro
14360 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54  llbacks or ABORT
14370 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20   processing, or 
14380 5b 44 52 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f  [DROP TABLE] pro
14390 63 65 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a  cessing.  The.**
143a0 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20   count does not 
143b0 69 6e 63 6c 75 64 65 20 72 6f 77 73 20 6f 66 20  include rows of 
143c0 76 69 65 77 73 20 74 68 61 74 20 66 69 72 65 20  views that fire 
143d0 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74  an [INSTEAD OF t
143e0 72 69 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75  rigger],.** thou
143f0 67 68 20 69 66 20 74 68 65 20 49 4e 53 54 45 41  gh if the INSTEA
14400 44 20 4f 46 20 74 72 69 67 67 65 72 20 6d 61 6b  D OF trigger mak
14410 65 73 20 63 68 61 6e 67 65 73 20 6f 66 20 69 74  es changes of it
14420 73 20 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68 61  s own, those cha
14430 6e 67 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75  nges .** are cou
14440 6e 74 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20  nted.)^.** ^The 
14450 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
14460 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e  anges() function
14470 20 63 6f 75 6e 74 73 20 74 68 65 20 63 68 61 6e   counts the chan
14480 67 65 73 20 61 73 20 73 6f 6f 6e 20 61 73 0a 2a  ges as soon as.*
14490 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  * the statement 
144a0 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d 20  that makes them 
144b0 69 73 20 63 6f 6d 70 6c 65 74 65 64 20 28 77 68  is completed (wh
144c0 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  en the statement
144d0 20 68 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 61   handle.** is pa
144e0 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33  ssed to [sqlite3
144f0 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
14500 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
14510 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ])..**.** See al
14520 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  so the [sqlite3_
14530 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72  changes()] inter
14540 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f  face, the.** [co
14550 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67  unt_changes prag
14560 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f  ma], and the [to
14570 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51  tal_changes() SQ
14580 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a  L function]..**.
14590 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65  ** If a separate
145a0 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68   thread makes ch
145b0 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d  anges on the sam
145c0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
145d0 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b  ction.** while [
145e0 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
145f0 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e  anges()] is runn
14600 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c  ing then the val
14610 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69  ue.** returned i
14620 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  s unpredictable 
14630 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66  and not meaningf
14640 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ul..*/.int sqlit
14650 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
14660 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
14670 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74  ** CAPI3REF: Int
14680 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75  errupt A Long-Ru
14690 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 0a 2a  nning Query.**.*
146a0 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
146b0 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64   causes any pend
146c0 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65  ing database ope
146d0 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20  ration to abort 
146e0 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74  and.** return at
146f0 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70   its earliest op
14700 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20  portunity. This 
14710 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63  routine is typic
14720 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69  ally.** called i
14730 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20  n response to a 
14740 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68  user action such
14750 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61   as pressing "Ca
14760 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c  ncel".** or Ctrl
14770 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65  -C where the use
14780 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71  r wants a long q
14790 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74  uery operation t
147a0 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69  o halt.** immedi
147b0 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74  ately..**.** ^It
147c0 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c   is safe to call
147d0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72   this routine fr
147e0 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66  om a thread diff
147f0 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a  erent from the.*
14800 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73  * thread that is
14810 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69   currently runni
14820 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ng the database 
14830 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20  operation.  But 
14840 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66  it.** is not saf
14850 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72  e to call this r
14860 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64  outine with a [d
14870 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
14880 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63  on] that.** is c
14890 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63  losed or might c
148a0 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69  lose before sqli
148b0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
148c0 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  returns..**.** ^
148d0 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74  If an SQL operat
148e0 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72  ion is very near
148f0 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 74  ly finished at t
14900 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20  he time when.** 
14910 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
14920 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74  t() is called, t
14930 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74  hen it might not
14940 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75   have an opportu
14950 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e  nity.** to be in
14960 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69  terrupted and mi
14970 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20  ght continue to 
14980 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a  completion..**.*
14990 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74  * ^An SQL operat
149a0 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65  ion that is inte
149b0 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74  rrupted will ret
149c0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  urn [SQLITE_INTE
149d0 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74  RRUPT]..** ^If t
149e0 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53  he interrupted S
149f0 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  QL operation is 
14a00 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  an INSERT, UPDAT
14a10 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
14a20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61  that is inside a
14a30 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
14a40 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  action, then the
14a50 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74   entire transact
14a60 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72  ion.** will be r
14a70 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d  olled back autom
14a80 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20  atically..**.** 
14a90 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  ^The sqlite3_int
14aa0 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69  errupt(D) call i
14ab0 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69  s in effect unti
14ac0 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20  l all currently 
14ad0 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73  running.** SQL s
14ae0 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61  tatements on [da
14af0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14b00 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20  n] D complete.  
14b10 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61  ^Any new SQL sta
14b20 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20  tements.** that 
14b30 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65  are started afte
14b40 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  r the sqlite3_in
14b50 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61  terrupt() call a
14b60 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a  nd before the .*
14b70 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d  * running statem
14b80 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65 72  ents reaches zer
14b90 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74 65  o are interrupte
14ba0 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61 64  d as if they had
14bb0 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67   been.** running
14bc0 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71   prior to the sq
14bd0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
14be0 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51  ) call.  ^New SQ
14bf0 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
14c00 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
14c10 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69   after the runni
14c20 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75  ng statement cou
14c30 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20  nt reaches zero 
14c40 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63  are.** not effec
14c50 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74  ted by the sqlit
14c60 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a  e3_interrupt()..
14c70 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71  ** ^A call to sq
14c80 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
14c90 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 20 77  D) that occurs w
14ca0 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f  hen there are no
14cb0 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20   running.** SQL 
14cc0 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20  statements is a 
14cd0 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f  no-op and has no
14ce0 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73   effect on SQL s
14cf0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
14d00 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
14d10 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ter the sqlite3_
14d20 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
14d30 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
14d40 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
14d50 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65  connection close
14d60 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  s while [sqlite3
14d70 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a  _interrupt()].**
14d80 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
14d90 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c   bad things will
14da0 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a   likely happen..
14db0 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
14dc0 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 65  interrupt(sqlite
14dd0 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
14de0 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20  3REF: Determine 
14df0 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  If An SQL Statem
14e00 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a  ent Is Complete.
14e10 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
14e20 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c 20  ines are useful 
14e30 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c  during command-l
14e40 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74  ine input to det
14e50 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a  ermine if the.**
14e60 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72   currently enter
14e70 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f  ed text seems to
14e80 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65   form a complete
14e90 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f   SQL statement o
14ea0 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e  r.** if addition
14eb0 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64  al input is need
14ec0 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e  ed before sendin
14ed0 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a  g the text into.
14ee0 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61  ** SQLite for pa
14ef0 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72  rsing.  ^These r
14f00 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31  outines return 1
14f10 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 73 74   if the input st
14f20 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20  ring.** appears 
14f30 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65  to be a complete
14f40 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20   SQL statement. 
14f50 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73   ^A statement is
14f60 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a   judged to be.**
14f70 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20   complete if it 
14f80 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d 69  ends with a semi
14f90 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20  colon token and 
14fa0 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20  is not a prefix 
14fb0 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72  of a.** well-for
14fc0 6d 65 64 20 43 52 45 41 54 45 20 54 52 49 47 47  med CREATE TRIGG
14fd0 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  ER statement.  ^
14fe0 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20  Semicolons that 
14ff0 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 69 74  are embedded wit
15000 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69  hin.** string li
15010 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64  terals or quoted
15020 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65   identifier name
15030 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72  s or comments ar
15040 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e  e not.** indepen
15050 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65  dent tokens (the
15060 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 74 68  y are part of th
15070 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68  e token in which
15080 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62   they are.** emb
15090 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 73 20  edded) and thus 
150a0 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20  do not count as 
150b0 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d  a statement term
150c0 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73  inator.  ^Whites
150d0 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d  pace.** and comm
150e0 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77  ents that follow
150f0 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63   the final semic
15100 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64  olon are ignored
15110 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  ..**.** ^These r
15120 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30  outines return 0
15130 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   if the statemen
15140 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e  t is incomplete.
15150 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72    ^If a.** memor
15160 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
15170 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f  ls, then SQLITE_
15180 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65  NOMEM is returne
15190 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  d..**.** ^These 
151a0 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20  routines do not 
151b0 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73 74  parse the SQL st
151c0 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a  atements thus.**
151d0 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74   will not detect
151e0 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69   syntactically i
151f0 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a  ncorrect SQL..**
15200 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20  .** ^(If SQLite 
15210 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69  has not been ini
15220 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b  tialized using [
15230 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
15240 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20  ze()] prior .** 
15250 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69  to invoking sqli
15260 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
15270 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e   then sqlite3_in
15280 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e  itialize() is in
15290 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74  voked.** automat
152a0 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65  ically by sqlite
152b0 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20  3_complete16(). 
152c0 20 49 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c   If that initial
152d0 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a  ization fails,.*
152e0 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72  * then the retur
152f0 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  n value from sql
15300 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
15310 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65  ) will be non-ze
15320 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73  ro.** regardless
15330 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
15340 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c  ot the input SQL
15350 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a   is complete.)^.
15360 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20  **.** The input 
15370 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70  to [sqlite3_comp
15380 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20  lete()] must be 
15390 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
153a0 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e  d.** UTF-8 strin
153b0 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70  g..**.** The inp
153c0 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ut to [sqlite3_c
153d0 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73  omplete16()] mus
153e0 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d  t be a zero-term
153f0 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36  inated.** UTF-16
15400 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76   string in nativ
15410 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f  e byte order..*/
15420 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d  .int sqlite3_com
15430 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72  plete(const char
15440 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   *sql);.int sqli
15450 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63  te3_complete16(c
15460 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b  onst void *sql);
15470 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
15480 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 61 6c  : Register A Cal
15490 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20  lback To Handle 
154a0 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f  SQLITE_BUSY Erro
154b0 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  rs.**.** ^This r
154c0 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 63 61  outine sets a ca
154d0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
154e0 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e  that might be in
154f0 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 0a 2a  voked whenever.*
15500 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20  * an attempt is 
15510 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 64  made to open a d
15520 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 74 68  atabase table th
15530 61 74 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61  at another threa
15540 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20  d.** or process 
15550 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a  has locked..**.*
15560 2a 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63  * ^If the busy c
15570 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c  allback is NULL,
15580 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55   then [SQLITE_BU
15590 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  SY] or [SQLITE_I
155a0 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a  OERR_BLOCKED].**
155b0 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d   is returned imm
155c0 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e  ediately upon en
155d0 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c  countering the l
155e0 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75  ock.  ^If the bu
155f0 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69  sy callback.** i
15600 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e  s not NULL, then
15610 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69   the callback mi
15620 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  ght be invoked w
15630 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  ith two argument
15640 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  s..**.** ^The fi
15650 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
15660 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
15670 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
15680 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20  e void* pointer 
15690 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20  which.** is the 
156a0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74  third argument t
156b0 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  o sqlite3_busy_h
156c0 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20  andler().  ^The 
156d0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
156e0 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68  to.** the busy h
156f0 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20  andler callback 
15700 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
15710 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20   times that the 
15720 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73  busy handler has
15730 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64  .** been invoked
15740 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e   for this lockin
15750 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68  g event.  ^If th
15760 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61  e.** busy callba
15770 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68  ck returns 0, th
15780 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c  en no additional
15790 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61   attempts are ma
157a0 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20  de to.** access 
157b0 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64  the database and
157c0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f   [SQLITE_BUSY] o
157d0 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
157e0 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 75  BLOCKED] is retu
157f0 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  rned..** ^If the
15800 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
15810 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  s non-zero, then
15820 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74   another attempt
15830 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 6f  .** is made to o
15840 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  pen the database
15850 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
15860 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61   the cycle repea
15870 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72  ts..**.** The pr
15880 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79  esence of a busy
15890 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f   handler does no
158a0 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74  t guarantee that
158b0 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f   it will be invo
158c0 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72  ked.** when ther
158d0 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e  e is lock conten
158e0 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65  tion. ^If SQLite
158f0 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74   determines that
15900 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75   invoking the bu
15910 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f  sy.** handler co
15920 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20  uld result in a 
15930 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c  deadlock, it wil
15940 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72  l go ahead and r
15950 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55  eturn [SQLITE_BU
15960 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54  SY].** or [SQLIT
15970 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
15980 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f   instead of invo
15990 6b 69 6e 67 20 74 68 65 20 62 75 73 79 20 68 61  king the busy ha
159a0 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64  ndler..** Consid
159b0 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68  er a scenario wh
159c0 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20  ere one process 
159d0 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61  is holding a rea
159e0 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69  d lock that.** i
159f0 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70  t is trying to p
15a00 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65  romote to a rese
15a10 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a  rved lock and.**
15a20 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73   a second proces
15a30 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72  s is holding a r
15a40 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61  eserved lock tha
15a50 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a  t it is trying.*
15a60 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20  * to promote to 
15a70 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63  an exclusive loc
15a80 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72  k.  The first pr
15a90 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f  ocess cannot pro
15aa0 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20  ceed.** because 
15ab0 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79  it is blocked by
15ac0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20   the second and 
15ad0 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  the second proce
15ae0 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f  ss cannot.** pro
15af0 63 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20  ceed because it 
15b00 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
15b10 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74  e first.  If bot
15b20 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69  h processes.** i
15b30 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68  nvoke the busy h
15b40 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72  andlers, neither
15b50 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70   will make any p
15b60 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66  rogress.  Theref
15b70 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72  ore,.** SQLite r
15b80 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42  eturns [SQLITE_B
15b90 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72  USY] for the fir
15ba0 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69  st process, hopi
15bb0 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20  ng that this.** 
15bc0 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20  will induce the 
15bd0 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f  first process to
15be0 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61   release its rea
15bf0 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77  d lock and allow
15c00 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70  .** the second p
15c10 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65  rocess to procee
15c20 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65  d..**.** ^The de
15c30 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62  fault busy callb
15c40 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ack is NULL..**.
15c50 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
15c60 42 55 53 59 5d 20 65 72 72 6f 72 20 69 73 20 63  BUSY] error is c
15c70 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b 53 51 4c  onverted to [SQL
15c80 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
15c90 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74  D].** when SQLit
15ca0 65 20 69 73 20 69 6e 20 74 68 65 20 6d 69 64 64  e is in the midd
15cb0 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 20 74 72  le of a large tr
15cc0 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 72 65 20  ansaction where 
15cd0 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67  all the.** chang
15ce0 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20  es will not fit 
15cf0 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f  into the in-memo
15d00 72 79 20 63 61 63 68 65 2e 20 20 53 51 4c 69 74  ry cache.  SQLit
15d10 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64  e will.** alread
15d20 79 20 68 6f 6c 64 20 61 20 52 45 53 45 52 56 45  y hold a RESERVE
15d30 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61  D lock on the da
15d40 74 61 62 61 73 65 20 66 69 6c 65 2c 20 62 75 74  tabase file, but
15d50 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20   it needs.** to 
15d60 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63  promote this loc
15d70 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 45 20 73  k to EXCLUSIVE s
15d80 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20 73 70  o that it can sp
15d90 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61 67  ill cache.** pag
15da0 65 73 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61  es into the data
15db0 62 61 73 65 20 66 69 6c 65 20 77 69 74 68 6f 75  base file withou
15dc0 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72  t harm to concur
15dd0 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e  rent.** readers.
15de0 20 20 5e 49 66 20 69 74 20 69 73 20 75 6e 61 62    ^If it is unab
15df0 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68  le to promote th
15e00 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65  e lock, then the
15e10 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61   in-memory.** ca
15e20 63 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 66 74  che will be left
15e30 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74   in an inconsist
15e40 65 6e 74 20 73 74 61 74 65 20 61 6e 64 20 73 6f  ent state and so
15e50 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f   the error.** co
15e60 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 20 66  de is promoted f
15e70 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 76 65  rom the relative
15e80 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54  ly benign [SQLIT
15e90 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68  E_BUSY] to.** th
15ea0 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20 5b 53  e more severe [S
15eb0 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
15ec0 4b 45 44 5d 2e 20 20 5e 54 68 69 73 20 65 72 72  KED].  ^This err
15ed0 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f  or code promotio
15ee0 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20 61  n.** forces an a
15ef0 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63  utomatic rollbac
15f00 6b 20 6f 66 20 74 68 65 20 63 68 61 6e 67 65 73  k of the changes
15f10 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61  .  See the.** <a
15f20 20 68 72 65 66 3d 22 2f 63 76 73 74 72 61 63 2f   href="/cvstrac/
15f30 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f  wiki?p=Corruptio
15f40 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72  nFollowingBusyEr
15f50 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74  ror">.** Corrupt
15f60 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79  ionFollowingBusy
15f70 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70  Error</a> wiki p
15f80 61 67 65 20 66 6f 72 20 61 20 64 69 73 63 75 73  age for a discus
15f90 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74  sion of why.** t
15fa0 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61 6e 74  his is important
15fb0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20  ..**.** ^(There 
15fc0 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69  can only be a si
15fd0 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65  ngle busy handle
15fe0 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61  r defined for ea
15ff0 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ch.** [database 
16000 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65  connection].  Se
16010 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79  tting a new busy
16020 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20   handler clears 
16030 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  any.** previousl
16040 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e  y set handler.)^
16050 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63 61 6c    ^Note that cal
16060 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75  ling [sqlite3_bu
16070 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a  sy_timeout()].**
16080 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f   will also set o
16090 72 20 63 6c 65 61 72 20 74 68 65 20 62 75 73 79  r clear the busy
160a0 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20   handler..**.** 
160b0 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  The busy callbac
160c0 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b  k should not tak
160d0 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68  e any actions wh
160e0 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a  ich modify the.*
160f0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
16100 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
16110 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ed the busy hand
16120 6c 65 72 2e 20 20 41 6e 79 20 73 75 63 68 20 61  ler.  Any such a
16130 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74  ctions.** result
16140 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65   in undefined be
16150 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41  havior..** .** A
16160 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75   busy handler mu
16170 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65  st not close the
16180 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
16190 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70  tion.** or [prep
161a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
161b0 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
161c0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a   busy handler..*
161d0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75  /.int sqlite3_bu
161e0 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74  sy_handler(sqlit
161f0 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64  e3*, int(*)(void
16200 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a  *,int), void*);.
16210 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
16220 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d 65   Set A Busy Time
16230 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  out.**.** ^This 
16240 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b  routine sets a [
16250 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
16260 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64  dler | busy hand
16270 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73  ler] that sleeps
16280 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66  .** for a specif
16290 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69  ied amount of ti
162a0 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20  me when a table 
162b0 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65  is locked.  ^The
162c0 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c   handler.** will
162d0 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20   sleep multiple 
162e0 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c  times until at l
162f0 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73  east "ms" millis
16300 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69  econds of sleepi
16310 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d  ng.** have accum
16320 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20  ulated.  ^After 
16330 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69  at least "ms" mi
16340 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
16350 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68  eeping,.** the h
16360 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30  andler returns 0
16370 20 77 68 69 63 68 20 63 61 75 73 65 73 20 5b 73   which causes [s
16380 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74  qlite3_step()] t
16390 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c  o return.** [SQL
163a0 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51  ITE_BUSY] or [SQ
163b0 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
163c0 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  ED]..**.** ^Call
163d0 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ing this routine
163e0 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e   with an argumen
163f0 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65  t less than or e
16400 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20  qual to zero.** 
16410 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75  turns off all bu
16420 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a  sy handlers..**.
16430 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f  ** ^(There can o
16440 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20  nly be a single 
16450 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72  busy handler for
16460 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a   a particular.**
16470 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
16480 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67  ction] any any g
16490 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66  iven moment.  If
164a0 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61   another busy ha
164b0 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66  ndler.** was def
164c0 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71  ined  (using [sq
164d0 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
164e0 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20  er()]) prior to 
164f0 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20  calling.** this 
16500 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74  routine, that ot
16510 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72  her busy handler
16520 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a   is cleared.)^.*
16530 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75  /.int sqlite3_bu
16540 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74  sy_timeout(sqlit
16550 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f  e3*, int ms);../
16560 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
16570 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69  onvenience Routi
16580 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20  nes For Running 
16590 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68  Queries.**.** Th
165a0 69 73 20 69 73 20 61 20 6c 65 67 61 63 79 20 69  is is a legacy i
165b0 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 69 73  nterface that is
165c0 20 70 72 65 73 65 72 76 65 64 20 66 6f 72 20 62   preserved for b
165d0 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
165e0 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f  bility..** Use o
165f0 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  f this interface
16600 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e   is not recommen
16610 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e  ded..**.** Defin
16620 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75  ition: A <b>resu
16630 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20  lt table</b> is 
16640 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75  memory data stru
16650 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79  cture created by
16660 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
16670 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e  _get_table()] in
16680 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75  terface.  A resu
16690 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73  lt table records
166a0 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65   the.** complete
166b0 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66   query results f
166c0 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  rom one or more 
166d0 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  queries..**.** T
166e0 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74  he table concept
166f0 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62  ually has a numb
16700 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63  er of rows and c
16710 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20  olumns.  But.** 
16720 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72  these numbers ar
16730 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68  e not part of th
16740 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  e result table i
16750 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a  tself.  These.**
16760 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74   numbers are obt
16770 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79  ained separately
16780 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20  .  Let N be the 
16790 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a  number of rows.*
167a0 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e  * and M be the n
167b0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
167c0 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ..**.** A result
167d0 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72   table is an arr
167e0 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
167f0 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  o zero-terminate
16800 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e  d UTF-8 strings.
16810 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e  .** There are (N
16820 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69  +1)*M elements i
16830 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68  n the array.  Th
16840 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65  e first M pointe
16850 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a  rs point.** to z
16860 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
16870 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e  trings that  con
16880 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f  tain the names o
16890 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a  f the columns..*
168a0 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20  * The remaining 
168b0 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e  entries all poin
168c0 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c  t to query resul
168d0 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73  ts.  NULL values
168e0 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55   result.** in NU
168f0 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c  LL pointers.  Al
16900 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61  l other values a
16910 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d  re in their UTF-
16920 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  8 zero-terminate
16930 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72  d.** string repr
16940 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65  esentation as re
16950 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
16960 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
16970 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c  ]..**.** A resul
16980 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f  t table might co
16990 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20  nsist of one or 
169a0 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  more memory allo
169b0 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69  cations..** It i
169c0 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61  s not safe to pa
169d0 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c  ss a result tabl
169e0 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73  e directly to [s
169f0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
16a00 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
16a10 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c  e should be deal
16a20 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73  located using [s
16a30 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
16a40 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73  e()]..**.** ^(As
16a50 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74   an example of t
16a60 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
16a70 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20  format, suppose 
16a80 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a  a query result.*
16a90 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  * is as follows:
16aa0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
16ab0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  te><pre>.**     
16ac0 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c     Name        |
16ad0 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d   Age.**        -
16ae0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
16af0 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20  ------.**       
16b00 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34   Alice       | 4
16b10 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20  3.**        Bob 
16b20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20          | 28.** 
16b30 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20         Cindy    
16b40 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65     | 21.** </pre
16b50 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
16b60 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74  *.** There are t
16b70 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29  wo column (M==2)
16b80 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20   and three rows 
16b90 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68  (N==3).  Thus th
16ba0 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c  e.** result tabl
16bb0 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e  e has 8 entries.
16bc0 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65    Suppose the re
16bd0 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74  sult table is st
16be0 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72  ored.** in an ar
16bf0 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75  ray names azResu
16c00 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75  lt.  Then azResu
16c10 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f  lt holds this co
16c20 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  ntent:.**.** <bl
16c30 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
16c40 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
16c50 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65  t&#91;0] = "Name
16c60 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
16c70 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22  esult&#91;1] = "
16c80 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  Age";.**        
16c90 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20  azResult&#91;2] 
16ca0 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20  = "Alice";.**   
16cb0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
16cc0 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20  1;3] = "43";.** 
16cd0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
16ce0 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a  #91;4] = "Bob";.
16cf0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
16d00 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22  lt&#91;5] = "28"
16d10 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
16d20 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43  sult&#91;6] = "C
16d30 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20  indy";.**       
16d40 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d   azResult&#91;7]
16d50 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72   = "21";.** </pr
16d60 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29  e></blockquote>)
16d70 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
16d80 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
16d90 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61   function evalua
16da0 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  tes one or more.
16db0 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70  ** semicolon-sep
16dc0 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  arated SQL state
16dd0 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72  ments in the zer
16de0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
16df0 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20  -8.** string of 
16e00 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65  its 2nd paramete
16e10 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  r and returns a 
16e20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20  result table to 
16e30 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67  the.** pointer g
16e40 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20  iven in its 3rd 
16e50 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
16e60 20 41 66 74 65 72 20 74 68 65 20 61 70 70 6c 69   After the appli
16e70 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73  cation has finis
16e80 68 65 64 20 77 69 74 68 20 74 68 65 20 72 65 73  hed with the res
16e90 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ult from sqlite3
16ea0 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a  _get_table(),.**
16eb0 20 69 74 20 6d 75 73 74 20 70 61 73 73 20 74 68   it must pass th
16ec0 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70  e result table p
16ed0 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ointer to sqlite
16ee0 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69  3_free_table() i
16ef0 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65  n order to.** re
16f00 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  lease the memory
16f10 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63   that was malloc
16f20 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20  ed.  Because of 
16f30 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b  the way the.** [
16f40 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
16f50 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e  ] happens within
16f60 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
16f70 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e  le(), the callin
16f80 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75  g.** function mu
16f90 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61  st not try to ca
16fa0 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ll [sqlite3_free
16fb0 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f  ()] directly.  O
16fc0 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nly.** [sqlite3_
16fd0 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73  free_table()] is
16fe0 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65   able to release
16ff0 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70   the memory prop
17000 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e  erly and safely.
17010 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
17020 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69  e3_get_table() i
17030 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c  nterface is impl
17040 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61  emented as a wra
17050 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b  pper around.** [
17060 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e  sqlite3_exec()].
17070 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65    The sqlite3_ge
17080 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e  t_table() routin
17090 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  e does not have 
170a0 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79  access.** to any
170b0 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73   internal data s
170c0 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c  tructures of SQL
170d0 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e  ite.  It uses on
170e0 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a  ly the public.**
170f0 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e   interface defin
17100 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63  ed here.  As a c
17110 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f  onsequence, erro
17120 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e  rs that occur in
17130 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20   the.** wrapper 
17140 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66  layer outside of
17150 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73   the internal [s
17160 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63  qlite3_exec()] c
17170 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72  all are not.** r
17180 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73  eflected in subs
17190 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
171a0 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
171b0 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
171c0 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f  e3_errmsg()]..*/
171d0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74  .int sqlite3_get
171e0 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65  _table(.  sqlite
171f0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
17200 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62  /* An open datab
17210 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ase */.  const c
17220 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f  har *zSql,     /
17230 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c  * SQL to be eval
17240 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20  uated */.  char 
17250 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20  ***pazResult,   
17260 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74   /* Results of t
17270 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e  he query */.  in
17280 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20  t *pnRow,       
17290 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
172a0 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69   result rows wri
172b0 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69  tten here */.  i
172c0 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20  nt *pnColumn,   
172d0 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
172e0 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73  f result columns
172f0 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
17300 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d  .  char **pzErrm
17310 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f  sg       /* Erro
17320 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65  r msg written he
17330 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71  re */.);.void sq
17340 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
17350 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b  (char **result);
17360 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
17370 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69  : Formatted Stri
17380 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63  ng Printing Func
17390 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
173a0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77  e routines are w
173b0 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68  ork-alikes of th
173c0 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d  e "printf()" fam
173d0 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73  ily of functions
173e0 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61  .** from the sta
173f0 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
17400 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
17410 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e  te3_mprintf() an
17420 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e  d sqlite3_vmprin
17430 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72  tf() routines wr
17440 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73  ite their.** res
17450 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  ults into memory
17460 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
17470 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
17480 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67  ]..** The string
17490 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
174a0 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73  ese two routines
174b0 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65   should be.** re
174c0 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74  leased by [sqlit
174d0 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f  e3_free()].  ^Bo
174e0 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  th routines retu
174f0 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69  rn a.** NULL poi
17500 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33  nter if [sqlite3
17510 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e  _malloc()] is un
17520 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
17530 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72   enough.** memor
17540 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65  y to hold the re
17550 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a  sulting string..
17560 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69  **.** ^(The sqli
17570 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72  te3_snprintf() r
17580 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61  outine is simila
17590 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29  r to "snprintf()
175a0 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74  " from.** the st
175b0 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
175c0 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73  .  The result is
175d0 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68   written into th
175e0 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70  e.** buffer supp
175f0 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  lied as the seco
17600 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f  nd parameter who
17610 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e  se size is given
17620 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74   by.** the first
17630 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65   parameter. Note
17640 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20   that the order 
17650 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  of the.** first 
17660 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69  two parameters i
17670 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20  s reversed from 
17680 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54  snprintf().)^  T
17690 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73  his is an.** his
176a0 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74  torical accident
176b0 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20   that cannot be 
176c0 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72  fixed without br
176d0 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61  eaking.** backwa
176e0 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
176f0 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20  y.  ^(Note also 
17700 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70  that sqlite3_snp
17710 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72  rintf().** retur
17720 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
17730 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65  its buffer inste
17740 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72  ad of the number
17750 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72   of.** character
17760 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74  s actually writt
17770 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66  en into the buff
17780 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20  er.)^  We admit 
17790 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  that.** the numb
177a0 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
177b0 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62   written would b
177c0 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20  e a more useful 
177d0 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20  return.** value 
177e0 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68  but we cannot ch
177f0 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65  ange the impleme
17800 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74  ntation of sqlit
17810 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
17820 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65   now without bre
17830 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c  aking compatibil
17840 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c  ity..**.** ^As l
17850 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65  ong as the buffe
17860 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65  r size is greate
17870 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c  r than zero, sql
17880 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
17890 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  ** guarantees th
178a0 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73  at the buffer is
178b0 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72   always zero-ter
178c0 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66  minated.  ^The f
178d0 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  irst.** paramete
178e0 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74  r "n" is the tot
178f0 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62  al size of the b
17900 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67  uffer, including
17910 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68   space for.** th
17920 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  e zero terminato
17930 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65  r.  So the longe
17940 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63  st string that c
17950 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79  an be completely
17960 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c  .** written will
17970 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65   be n-1 characte
17980 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  rs..**.** ^The s
17990 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66  qlite3_vsnprintf
179a0 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20  () routine is a 
179b0 76 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20  varargs version 
179c0 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  of sqlite3_snpri
179d0 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ntf()..**.** The
179e0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20  se routines all 
179f0 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61  implement some a
17a00 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74  dditional format
17a10 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20  ting.** options 
17a20 74 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20  that are useful 
17a30 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67  for constructing
17a40 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
17a50 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75  .** All of the u
17a60 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f  sual printf() fo
17a70 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73  rmatting options
17a80 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69   apply.  In addi
17a90 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69  tion, there.** i
17aa0 73 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22  s are "%q", "%Q"
17ab0 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f  , and "%z" optio
17ac0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ns..**.** ^(The 
17ad0 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  %q option works 
17ae0 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20  like %s in that 
17af0 69 74 20 73 75 62 73 74 69 74 75 74 65 73 20 61  it substitutes a
17b00 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61 74 65 64   null-terminated
17b10 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  .** string from 
17b20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73  the argument lis
17b30 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20  t.  But %q also 
17b40 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c  doubles every '\
17b50 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  '' character..**
17b60 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 64 20   %q is designed 
17b70 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61  for use inside a
17b80 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e   string literal.
17b90 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20  )^  By doubling 
17ba0 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61  each '\''.** cha
17bb0 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65  racter it escape
17bc0 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72  s that character
17bd0 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74   and allows it t
17be0 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e  o be inserted in
17bf0 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  to.** the string
17c00 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d  ..**.** For exam
17c10 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20  ple, assume the 
17c20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20  string variable 
17c30 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74  zText contains t
17c40 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  ext as follows:.
17c50 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
17c60 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
17c70 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20   *zText = "It's 
17c80 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a  a happy day!";.*
17c90 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
17ca0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20  uote>.**.** One 
17cb0 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78  can use this tex
17cc0 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  t in an SQL stat
17cd0 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73  ement as follows
17ce0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
17cf0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
17d00 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
17d10 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
17d20 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
17d30 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65  LUES('%q')", zTe
17d40 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33  xt);.**  sqlite3
17d50 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20  _exec(db, zSQL, 
17d60 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71  0, 0, 0);.**  sq
17d70 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29  lite3_free(zSQL)
17d80 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
17d90 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42  ckquote>.**.** B
17da0 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f  ecause the %q fo
17db0 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75  rmat string is u
17dc0 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68  sed, the '\'' ch
17dd0 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74  aracter in zText
17de0 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61  .** is escaped a
17df0 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72  nd the SQL gener
17e00 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f  ated is as follo
17e10 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
17e20 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
17e30 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
17e40 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73  e1 VALUES('It''s
17e50 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a   a happy day!').
17e60 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
17e70 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  quote>.**.** Thi
17e80 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48  s is correct.  H
17e90 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e  ad we used %s in
17ea0 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65  stead of %q, the
17eb0 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a   generated SQL.*
17ec0 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f  * would have loo
17ed0 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a  ked like this:.*
17ee0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
17ef0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52  ><pre>.**  INSER
17f00 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41  T INTO table1 VA
17f10 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70  LUES('It's a hap
17f20 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f  py day!');.** </
17f30 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
17f40 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63  >.**.** This sec
17f50 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61  ond example is a
17f60 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72  n SQL syntax err
17f70 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61  or.  As a genera
17f80 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c  l rule you shoul
17f90 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20  d.** always use 
17fa0 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73  %q instead of %s
17fb0 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20   when inserting 
17fc0 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69  text into a stri
17fd0 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a  ng literal..**.*
17fe0 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f  * ^(The %Q optio
17ff0 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20  n works like %q 
18000 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61  except it also a
18010 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65  dds single quote
18020 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20  s around.** the 
18030 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74  outside of the t
18040 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64  otal string.  Ad
18050 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74  ditionally, if t
18060 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20  he parameter in 
18070 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  the.** argument 
18080 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70  list is a NULL p
18090 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74  ointer, %Q subst
180a0 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20  itutes the text 
180b0 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a  "NULL" (without.
180c0 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73  ** single quotes
180d0 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78  ).)^  So, for ex
180e0 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64  ample, one could
180f0 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f   say:.**.** <blo
18100 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
18110 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73    char *zSQL = s
18120 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22  qlite3_mprintf("
18130 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
18140 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a  e VALUES(%Q)", z
18150 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
18160 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
18170 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
18180 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
18190 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
181a0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
181b0 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20   The code above 
181c0 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f  will render a co
181d0 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d  rrect SQL statem
181e0 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a  ent in the zSQL.
181f0 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e  ** variable even
18200 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61   if the zText va
18210 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c  riable is a NULL
18220 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
18230 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61  ^(The "%z" forma
18240 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72  tting option wor
18250 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74  ks like "%s" but
18260 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64   with the.** add
18270 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72  ition that after
18280 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 20   the string has 
18290 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f  been read and co
182a0 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65  pied into.** the
182b0 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65   result, [sqlite
182c0 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c  3_free()] is cal
182d0 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74  led on the input
182e0 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68   string.)^.*/.ch
182f0 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69  ar *sqlite3_mpri
18300 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ntf(const char*,
18310 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69  ...);.char *sqli
18320 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e  te3_vmprintf(con
18330 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73  st char*, va_lis
18340 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  t);.char *sqlite
18350 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63  3_snprintf(int,c
18360 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
18370 2c 20 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71  , ...);.char *sq
18380 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28  lite3_vsnprintf(
18390 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20  int,char*,const 
183a0 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b  char*, va_list);
183b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
183c0 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
183d0 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a  ion Subsystem.**
183e0 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
183f0 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74  ore uses these t
18400 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f  hree routines fo
18410 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e  r all of its own
18420 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d  .** internal mem
18430 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
18440 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20  eeds. "Core" in 
18450 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e  the previous sen
18460 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f  tence.** does no
18470 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74  t include operat
18480 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
18490 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  fic VFS implemen
184a0 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20  tation.  The.** 
184b0 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73  Windows VFS uses
184c0 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29   native malloc()
184d0 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20   and free() for 
184e0 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e  some operations.
184f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
18500 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75  te3_malloc() rou
18510 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70  tine returns a p
18520 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63  ointer to a bloc
18530 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61  k.** of memory a
18540 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20  t least N bytes 
18550 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65  in length, where
18560 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65   N is the parame
18570 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ter..** ^If sqli
18580 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20  te3_malloc() is 
18590 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e  unable to obtain
185a0 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65   sufficient free
185b0 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72  .** memory, it r
185c0 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
185d0 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20  inter.  ^If the 
185e0 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a  parameter N to.*
185f0 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
18600 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65  () is zero or ne
18610 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69  gative then sqli
18620 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74  te3_malloc() ret
18630 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70  urns.** a NULL p
18640 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43  ointer..**.** ^C
18650 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66  alling sqlite3_f
18660 72 65 65 28 29 20 77 69 74 68 20 61 20 70 6f 69  ree() with a poi
18670 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20  nter previously 
18680 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73  returned.** by s
18690 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
186a0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  or sqlite3_reall
186b0 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 68  oc() releases th
186c0 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20  at memory so.** 
186d0 74 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 65  that it might be
186e0 20 72 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73   reused.  ^The s
186f0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f  qlite3_free() ro
18700 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f  utine is.** a no
18710 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64  -op if is called
18720 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69   with a NULL poi
18730 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61  nter.  Passing a
18740 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
18750 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65   to sqlite3_free
18760 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20  () is harmless. 
18770 20 41 66 74 65 72 20 62 65 69 6e 67 20 66 72 65   After being fre
18780 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68  ed, memory.** sh
18790 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20  ould neither be 
187a0 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e  read nor written
187b0 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20  .  Even reading 
187c0 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64  previously freed
187d0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74  .** memory might
187e0 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67   result in a seg
187f0 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20  mentation fault 
18800 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20  or other severe 
18810 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79  error..** Memory
18820 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73   corruption, a s
18830 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c  egmentation faul
18840 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65  t, or other seve
18850 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68  re error.** migh
18860 74 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69  t result if sqli
18870 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 61  te3_free() is ca
18880 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d  lled with a non-
18890 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61  NULL pointer tha
188a0 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74  t.** was not obt
188b0 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74  ained from sqlit
188c0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73  e3_malloc() or s
188d0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
188e0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71  ..**.** ^(The sq
188f0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
18900 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
18910 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a  ts to resize a.*
18920 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61  * prior memory a
18930 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20  llocation to be 
18940 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
18950 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
18960 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
18970 65 74 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72  eter.  The memor
18980 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
18990 62 65 20 72 65 73 69 7a 65 64 20 69 73 20 74 68  be resized is th
189a0 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d  e first.** param
189b0 65 74 65 72 2e 29 5e 20 5e 20 49 66 20 74 68 65  eter.)^ ^ If the
189c0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
189d0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
189e0 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55  loc().** is a NU
189f0 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
18a00 69 74 73 20 62 65 68 61 76 69 6f 72 20 69 73 20  its behavior is 
18a10 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c  identical to cal
18a20 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ling.** sqlite3_
18a30 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65 20  malloc(N) where 
18a40 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  N is the second 
18a50 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
18a60 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a  ite3_realloc()..
18a70 2a 2a 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e  ** ^If the secon
18a80 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
18a90 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
18aa0 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e   is zero or.** n
18ab0 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65  egative then the
18ac0 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61   behavior is exa
18ad0 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73  ctly the same as
18ae0 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
18af0 74 65 33 5f 66 72 65 65 28 50 29 20 77 68 65 72  te3_free(P) wher
18b00 65 20 50 20 69 73 20 74 68 65 20 66 69 72 73 74  e P is the first
18b10 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
18b20 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e  lite3_realloc().
18b30 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61  .** ^sqlite3_rea
18b40 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 61  lloc() returns a
18b50 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65   pointer to a me
18b60 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
18b70 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e  ** of at least N
18b80 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f   bytes in size o
18b90 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 66 69 63  r NULL if suffic
18ba0 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 75  ient memory is u
18bb0 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e  navailable..** ^
18bc0 49 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65  If M is the size
18bd0 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c   of the prior al
18be0 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d  location, then m
18bf0 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a  in(N,M) bytes.**
18c00 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c   of the prior al
18c10 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70  location are cop
18c20 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67  ied into the beg
18c30 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72  inning of buffer
18c40 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
18c50 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
18c60 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20  ) and the prior 
18c70 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72  allocation is fr
18c80 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  eed..** ^If sqli
18c90 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65  te3_realloc() re
18ca0 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  turns NULL, then
18cb0 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
18cc0 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20  ation.** is not 
18cd0 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  freed..**.** ^Th
18ce0 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65  e memory returne
18cf0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c  d by sqlite3_mal
18d00 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69 74 65  loc() and sqlite
18d10 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69  3_realloc().** i
18d20 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64  s always aligned
18d30 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20   to at least an 
18d40 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2c  8 byte boundary,
18d50 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79   or to a.** 4 by
18d60 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20 74  te boundary if t
18d70 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54  he [SQLITE_4_BYT
18d80 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43  E_ALIGNED_MALLOC
18d90 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a  ] compile-time.*
18da0 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  * option is used
18db0 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74  ..**.** In SQLit
18dc0 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20  e version 3.5.0 
18dd0 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61  and 3.5.1, it wa
18de0 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65  s possible to de
18df0 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49  fine.** the SQLI
18e00 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41  TE_OMIT_MEMORY_A
18e10 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20  LLOCATION which 
18e20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65 20  would cause the 
18e30 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c  built-in.** impl
18e40 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
18e50 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ese routines to 
18e60 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61  be omitted.  Tha
18e70 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20  t capability.** 
18e80 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f  is no longer pro
18e90 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69  vided.  Only bui
18ea0 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
18eb0 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75  ocators can be u
18ec0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 57  sed..**.** The W
18ed0 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66  indows OS interf
18ee0 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 73 0a  ace layer calls.
18ef0 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61  ** the system ma
18f00 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
18f10 29 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20  ) directly when 
18f20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69  converting.** fi
18f30 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20  lenames between 
18f40 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69  the UTF-8 encodi
18f50 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c 69 74  ng used by SQLit
18f60 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65  e.** and whateve
18f70 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64  r filename encod
18f80 69 6e 67 20 69 73 20 75 73 65 64 20 62 79 20 74  ing is used by t
18f90 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 57 69  he particular Wi
18fa0 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c  ndows.** install
18fb0 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61  ation.  Memory a
18fc0 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73  llocation errors
18fd0 20 61 72 65 20 64 65 74 65 63 74 65 64 2c 20 62   are detected, b
18fe0 75 74 0a 2a 2a 20 74 68 65 79 20 61 72 65 20 72  ut.** they are r
18ff0 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20  eported back as 
19000 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  [SQLITE_CANTOPEN
19010 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
19020 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68  IOERR] rather th
19030 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  an [SQLITE_NOMEM
19040 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69  ]..**.** The poi
19050 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74  nter arguments t
19060 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
19070 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
19080 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75  realloc()].** mu
19090 73 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c  st be either NUL
190a0 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65  L or else pointe
190b0 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  rs obtained from
190c0 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f   a prior.** invo
190d0 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  cation of [sqlit
190e0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20  e3_malloc()] or 
190f0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
19100 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a  ()] that have.**
19110 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65   not yet been re
19120 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  leased..**.** Th
19130 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
19140 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77  st not read or w
19150 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66  rite any part of
19160 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d  .** a block of m
19170 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68  emory after it h
19180 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64  as been released
19190 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
191a0 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73  e3_free()] or [s
191b0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
191c0 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  ]..*/.void *sqli
191d0 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b  te3_malloc(int);
191e0 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72  .void *sqlite3_r
191f0 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e  ealloc(void*, in
19200 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
19210 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f  _free(void*);../
19220 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
19230 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20  emory Allocator 
19240 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a  Statistics.**.**
19250 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73   SQLite provides
19260 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72   these two inter
19270 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74  faces for report
19280 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75  ing on the statu
19290 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  s.** of the [sql
192a0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20  ite3_malloc()], 
192b0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
192c0 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  , and [sqlite3_r
192d0 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75  ealloc()].** rou
192e0 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72  tines, which for
192f0 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d  m the built-in m
19300 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
19310 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a   subsystem..**.*
19320 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
19330 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72  memory_used()] r
19340 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
19350 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
19360 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20  es.** of memory 
19370 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61  currently outsta
19380 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20  nding (malloced 
19390 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a  but not freed)..
193a0 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
193b0 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
193c0 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74  r()] routine ret
193d0 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  urns the maximum
193e0 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71  .** value of [sq
193f0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
19400 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68  d()] since the h
19410 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a  igh-water mark.*
19420 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 74  * was last reset
19430 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72  .  ^The values r
19440 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
19450 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
19460 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
19470 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
19480 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61  ter()] include a
19490 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61  ny overhead.** a
194a0 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69  dded by SQLite i
194b0 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61  n its implementa
194c0 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
194d0 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62  _malloc()],.** b
194e0 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20  ut not overhead 
194f0 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79  added by the any
19500 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74   underlying syst
19510 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f  em library.** ro
19520 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c  utines that [sql
19530 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d  ite3_malloc()] m
19540 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  ay call..**.** ^
19550 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d  The memory high-
19560 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65  water mark is re
19570 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65  set to the curre
19580 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b  nt value of.** [
19590 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
195a0 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e  sed()] if and on
195b0 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  ly if the parame
195c0 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ter to.** [sqlit
195d0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
195e0 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20  ter()] is true. 
195f0 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75   ^The value retu
19600 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69  rned.** by [sqli
19610 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
19620 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20  ater(1)] is the 
19630 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a  high-water mark.
19640 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20  ** prior to the 
19650 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65  reset..*/.sqlite
19660 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
19670 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64  memory_used(void
19680 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
19690 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
196a0 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 65  highwater(int re
196b0 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a  setFlag);../*.**
196c0 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 75 64   CAPI3REF: Pseud
196d0 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20  o-Random Number 
196e0 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20  Generator.**.** 
196f0 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20  SQLite contains 
19700 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70  a high-quality p
19710 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d  seudo-random num
19720 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50  ber generator (P
19730 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20  RNG) used to.** 
19740 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52  select random [R
19750 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77  OWID | ROWIDs] w
19760 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65  hen inserting ne
19770 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61  w records into a
19780 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61   table that.** a
19790 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65 20  lready uses the 
197a0 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65  largest possible
197b0 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50   [ROWID].  The P
197c0 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64  RNG is also used
197d0 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c   for.** the buil
197e0 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e  d-in random() an
197f0 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53  d randomblob() S
19800 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54  QL functions.  T
19810 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c  his interface al
19820 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74  lows.** applicat
19830 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74  ions to access t
19840 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72  he same PRNG for
19850 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e   other purposes.
19860 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74  .**.** ^A call t
19870 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73  o this routine s
19880 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66  tores N bytes of
19890 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f   randomness into
198a0 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a   buffer P..**.**
198b0 20 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65   ^The first time
198c0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
198d0 20 69 6e 76 6f 6b 65 64 20 28 65 69 74 68 65 72   invoked (either
198e0 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62   internally or b
198f0 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  y.** the applica
19900 74 69 6f 6e 29 20 74 68 65 20 50 52 4e 47 20 69  tion) the PRNG i
19910 73 20 73 65 65 64 65 64 20 75 73 69 6e 67 20 72  s seeded using r
19920 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e  andomness obtain
19930 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78  ed.** from the x
19940 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f  Randomness metho
19950 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74  d of the default
19960 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
19970 62 6a 65 63 74 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c  bject..** ^On al
19980 6c 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76  l subsequent inv
19990 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65 20 70 73  ocations, the ps
199a0 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20  eudo-randomness 
199b0 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20  is generated.** 
199c0 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77  internally and w
199d0 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20  ithout recourse 
199e0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
199f0 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73  vfs] xRandomness
19a00 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76  .** method..*/.v
19a10 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64  oid sqlite3_rand
19a20 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f  omness(int N, vo
19a30 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  id *P);../*.** C
19a40 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65  API3REF: Compile
19a50 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74  -Time Authorizat
19a60 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ion Callbacks.**
19a70 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
19a80 65 20 72 65 67 69 73 74 65 72 73 20 61 6e 20 61  e registers an a
19a90 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
19aa0 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 63  ck with a partic
19ab0 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ular.** [databas
19ac0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73  e connection], s
19ad0 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66  upplied in the f
19ae0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
19af0 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65  * ^The authorize
19b00 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
19b10 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61  voked as SQL sta
19b20 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e  tements are bein
19b30 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79  g compiled.** by
19b40 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
19b50 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  e()] or its vari
19b60 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72  ants [sqlite3_pr
19b70 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20  epare_v2()],.** 
19b80 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
19b90 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  16()] and [sqlit
19ba0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
19bb0 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73  )].  ^At various
19bc0 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e  .** points durin
19bd0 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f  g the compilatio
19be0 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f  n process, as lo
19bf0 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65  gic is being cre
19c00 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f  ated.** to perfo
19c10 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f  rm various actio
19c20 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ns, the authoriz
19c30 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
19c40 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65  nvoked to.** see
19c50 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e   if those action
19c60 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20  s are allowed.  
19c70 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ^The authorizer 
19c80 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a  callback should.
19c90 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
19ca0 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74  E_OK] to allow t
19cb0 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49  he action, [SQLI
19cc0 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69  TE_IGNORE] to di
19cd0 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70  sallow the.** sp
19ce0 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75  ecific action bu
19cf0 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20  t allow the SQL 
19d00 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e  statement to con
19d10 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63  tinue to be.** c
19d20 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c  ompiled, or [SQL
19d30 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75  ITE_DENY] to cau
19d40 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 51  se the entire SQ
19d50 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62  L statement to b
19d60 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69  e.** rejected wi
19d70 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49  th an error.  ^I
19d80 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  f the authorizer
19d90 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
19da0 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f  s.** any value o
19db0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
19dc0 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49  E_IGNORE], [SQLI
19dd0 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49  TE_OK], or [SQLI
19de0 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e  TE_DENY].** then
19df0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   the [sqlite3_pr
19e00 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65  epare_v2()] or e
19e10 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74  quivalent call t
19e20 68 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a  hat triggered.**
19e30 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
19e40 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61  will fail with a
19e50 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  n error message.
19e60 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
19e70 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
19e80 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68   [SQLITE_OK], th
19e90 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65  at means the ope
19ea0 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73  ration.** reques
19eb0 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65  ted is ok.  ^Whe
19ec0 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  n the callback r
19ed0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44  eturns [SQLITE_D
19ee0 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71  ENY], the.** [sq
19ef0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
19f00 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e  ()] or equivalen
19f10 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  t call that trig
19f20 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74  gered the.** aut
19f30 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69  horizer will fai
19f40 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  l with an error 
19f50 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69  message explaini
19f60 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73  ng that.** acces
19f70 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a  s is denied. .**
19f80 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70  .** ^The first p
19f90 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
19fa0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
19fb0 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ack is a copy of
19fc0 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61   the third.** pa
19fd0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
19fe0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
19ff0 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63  rizer() interfac
1a000 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  e. ^The second p
1a010 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74  arameter.** to t
1a020 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  he callback is a
1a030 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54  n integer [SQLIT
1a040 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20  E_COPY | action 
1a050 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69  code] that speci
1a060 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74  fies.** the part
1a070 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f  icular action to
1a080 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20   be authorized. 
1a090 5e 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75  ^The third throu
1a0a0 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74  gh sixth paramet
1a0b0 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61  ers.** to the ca
1a0c0 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d  llback are zero-
1a0d0 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
1a0e0 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20  gs that contain 
1a0f0 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65  additional.** de
1a100 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20  tails about the 
1a110 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74  action to be aut
1a120 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  horized..**.** ^
1a130 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f  If the action co
1a140 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45  de is [SQLITE_RE
1a150 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63  AD].** and the c
1a160 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
1a170 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
1a180 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65  then the.** [pre
1a190 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1a1a0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f   statement is co
1a1b0 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 62  nstructed to sub
1a1c0 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c  stitute.** a NUL
1a1d0 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65  L value in place
1a1e0 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f   of the table co
1a1f0 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20  lumn that would 
1a200 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61  have.** been rea
1a210 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  d if [SQLITE_OK]
1a220 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e   had been return
1a230 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  ed.  The [SQLITE
1a240 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75  _IGNORE].** retu
1a250 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  rn can be used t
1a260 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73  o deny an untrus
1a270 74 65 64 20 75 73 65 72 20 61 63 63 65 73 73 20  ted user access 
1a280 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a  to individual.**
1a290 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61   columns of a ta
1a2a0 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ble..** ^If the 
1a2b0 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b  action code is [
1a2c0 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61  SQLITE_DELETE] a
1a2d0 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  nd the callback 
1a2e0 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49  returns.** [SQLI
1a2f0 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20  TE_IGNORE] then 
1a300 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65  the [DELETE] ope
1a310 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20  ration proceeds 
1a320 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e  but the.** [trun
1a330 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f  cate optimizatio
1a340 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20 61  n] is disabled a
1a350 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20  nd all rows are 
1a360 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75  deleted individu
1a370 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61  ally..**.** An a
1a380 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65  uthorizer is use
1a390 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  d when [sqlite3_
1a3a0 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72  prepare | prepar
1a3b0 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ing].** SQL stat
1a3c0 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75  ements from an u
1a3d0 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c  ntrusted source,
1a3e0 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20   to ensure that 
1a3f0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
1a400 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79  ts.** do not try
1a410 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 20   to access data 
1a420 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c  they are not all
1a430 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20  owed to see, or 
1a440 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74  that they do not
1a450 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75  .** try to execu
1a460 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61  te malicious sta
1a470 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d  tements that dam
1a480 61 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  age the database
1a490 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c  .  For.** exampl
1a4a0 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  e, an applicatio
1a4b0 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73  n may allow a us
1a4c0 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69  er to enter arbi
1a4d0 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65  trary.** SQL que
1a4e0 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74  ries for evaluat
1a4f0 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73  ion by a databas
1a500 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c  e.  But the appl
1a510 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20  ication does.** 
1a520 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65  not want the use
1a530 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20  r to be able to 
1a540 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63  make arbitrary c
1a550 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a  hanges to the.**
1a560 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61   database.  An a
1a570 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20  uthorizer could 
1a580 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70  then be put in p
1a590 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a  lace while the.*
1a5a0 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53  * user-entered S
1a5b0 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c  QL is being [sql
1a5c0 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70  ite3_prepare | p
1a5d0 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a  repared] that.**
1a5e0 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79   disallows every
1a5f0 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45  thing except [SE
1a600 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73  LECT] statements
1a610 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ..**.** Applicat
1a620 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74  ions that need t
1a630 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72  o process SQL fr
1a640 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75  om untrusted sou
1a650 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c  rces.** might al
1a660 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65  so consider lowe
1a670 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69  ring resource li
1a680 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69  mits using [sqli
1a690 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20  te3_limit()].** 
1a6a0 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74  and limiting dat
1a6b0 61 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67  abase size using
1a6c0 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63   the [max_page_c
1a6d0 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a  ount] [PRAGMA].*
1a6e0 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f  * in addition to
1a6f0 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72   using an author
1a700 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e  izer..**.** ^(On
1a710 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68  ly a single auth
1a720 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e  orizer can be in
1a730 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61   place on a data
1a740 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
1a750 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45  ** at a time.  E
1a760 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ach call to sqli
1a770 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1a780 65 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65  er overrides the
1a790 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c  .** previous cal
1a7a0 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74  l.)^  ^Disable t
1a7b0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79  he authorizer by
1a7c0 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55   installing a NU
1a7d0 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  LL callback..** 
1a7e0 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69  The authorizer i
1a7f0 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  s disabled by de
1a800 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  fault..**.** The
1a810 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1a820 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f  back must not do
1a830 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77   anything that w
1a840 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68  ill modify.** th
1a850 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1a860 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
1a870 65 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ed the authorize
1a880 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e  r callback..** N
1a890 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65  ote that [sqlite
1a8a0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1a8b0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  and [sqlite3_ste
1a8c0 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79  p()] both modify
1a8d0 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61   their.** databa
1a8e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66  se connections f
1a8f0 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f  or the meaning o
1a900 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68  f "modify" in th
1a910 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a  is paragraph..**
1a920 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74  .** ^When [sqlit
1a930 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1a940 20 69 73 20 75 73 65 64 20 74 6f 20 70 72 65 70   is used to prep
1a950 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c  are a statement,
1a960 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   the.** statemen
1a970 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72  t might be re-pr
1a980 65 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73  epared during [s
1a990 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64  qlite3_step()] d
1a9a0 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65  ue to a .** sche
1a9b0 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63  ma change.  Henc
1a9c0 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  e, the applicati
1a9d0 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65  on should ensure
1a9e0 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72   that the.** cor
1a9f0 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20  rect authorizer 
1aa00 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73  callback remains
1aa10 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67   in place during
1aa20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
1aa30 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f  ep()]..**.** ^No
1aa40 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68  te that the auth
1aa50 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1aa60 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20  is invoked only 
1aa70 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74  during.** [sqlit
1aa80 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
1aa90 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20   its variants.  
1aaa0 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73  Authorization is
1aab0 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65   not.** performe
1aac0 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65  d during stateme
1aad0 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e  nt evaluation in
1aae0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1aaf0 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20  ], unless.** as 
1ab00 73 74 61 74 65 64 20 69 6e 20 74 68 65 20 70 72  stated in the pr
1ab10 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68  evious paragraph
1ab20 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  , sqlite3_step()
1ab30 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69   invokes.** sqli
1ab40 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1ab50 20 74 6f 20 72 65 70 72 65 70 61 72 65 20 61 20   to reprepare a 
1ab60 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20  statement after 
1ab70 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e  a schema change.
1ab80 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1ab90 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a  set_authorizer(.
1aba0 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e    sqlite3*,.  in
1abb0 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a  t (*xAuth)(void*
1abc0 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a  ,int,const char*
1abd0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
1abe0 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
1abf0 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70  har*),.  void *p
1ac00 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a  UserData.);../*.
1ac10 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74  ** CAPI3REF: Aut
1ac20 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43  horizer Return C
1ac30 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  odes.**.** The [
1ac40 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1ac50 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69  orizer | authori
1ac60 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  zer callback fun
1ac70 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72  ction] must.** r
1ac80 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51  eturn either [SQ
1ac90 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20  LITE_OK] or one 
1aca0 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e  of these two con
1acb0 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a  stants in order.
1acc0 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c  ** to signal SQL
1acd0 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e  ite whether or n
1ace0 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73  ot the action is
1acf0 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65   permitted.  See
1ad00 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
1ad10 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
1ad20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63  | authorizer doc
1ad30 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20  umentation] for 
1ad40 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e  additional.** in
1ad50 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
1ad60 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49 54   Note that SQLIT
1ad70 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f  E_IGNORE is also
1ad80 20 75 73 65 64 20 61 73 20 61 20 5b 53 51 4c 49   used as a [SQLI
1ad90 54 45 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 65  TE_ROLLBACK | re
1ada0 74 75 72 6e 20 63 6f 64 65 5d 0a 2a 2a 20 66 72  turn code].** fr
1adb0 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  om the [sqlite3_
1adc0 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74  vtab_on_conflict
1add0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
1ade0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1adf0 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41  _DENY   1   /* A
1ae00 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61  bort the SQL sta
1ae10 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65  tement with an e
1ae20 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
1ae30 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20  SQLITE_IGNORE 2 
1ae40 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77    /* Don't allow
1ae50 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e   access, but don
1ae60 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65  't generate an e
1ae70 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  rror */../*.** C
1ae80 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
1ae90 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73  zer Action Codes
1aea0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
1aeb0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1aec0 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  er()] interface 
1aed0 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
1aee0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  back function.**
1aef0 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64   that is invoked
1af00 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65   to authorize ce
1af10 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d  rtain SQL statem
1af20 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68  ent actions.  Th
1af30 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
1af40 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c  meter to the cal
1af50 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65  lback is an inte
1af60 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70  ger code that sp
1af70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20  ecifies.** what 
1af80 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20  action is being 
1af90 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65  authorized.  The
1afa0 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67  se are the integ
1afb0 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20  er action codes 
1afc0 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68  that.** the auth
1afd0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1afe0 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a  may be passed..*
1aff0 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f  *.** These actio
1b000 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69  n code values si
1b010 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20  gnify what kind 
1b020 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  of operation is 
1b030 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69  to be.** authori
1b040 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e  zed.  The 3rd an
1b050 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73  d 4th parameters
1b060 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
1b070 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63  ation.** callbac
1b080 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20  k function will 
1b090 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72  be parameters or
1b0a0 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20   NULL depending 
1b0b0 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73  on which of thes
1b0c0 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73  e.** codes is us
1b0d0 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
1b0e0 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54   parameter.  ^(T
1b0f0 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
1b100 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f   to the.** autho
1b110 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
1b120 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
1b130 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69  e database ("mai
1b140 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65  n", "temp",.** e
1b150 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62  tc.) if applicab
1b160 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20  le.)^  ^The 6th 
1b170 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1b180 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1b190 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e  back.** is the n
1b1a0 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72  ame of the inner
1b1b0 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72  -most trigger or
1b1c0 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65   view that is re
1b1d0 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a  sponsible for.**
1b1e0 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65   the access atte
1b1f0 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  mpt or NULL if t
1b200 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d  his access attem
1b210 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66  pt is directly f
1b220 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c  rom.** top-level
1b230 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a   SQL code..*/./*
1b240 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1b250 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1b260 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a  ********** 3rd *
1b270 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20  *********** 4th 
1b280 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65  ***********/.#de
1b290 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1b2a0 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  TE_INDEX        
1b2b0 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e    1   /* Index N
1b2c0 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
1b2d0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1b2e0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1b2f0 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  E_TABLE         
1b300 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   2   /* Table Na
1b310 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1b320 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1b330 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1b340 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
1b350 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  3   /* Index Nam
1b360 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
1b370 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1b380 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1b390 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34  TEMP_TABLE     4
1b3a0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1b3b0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1b3c0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1b3d0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1b3e0 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20  EMP_TRIGGER   5 
1b3f0 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
1b400 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
1b410 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1b420 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
1b430 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20  MP_VIEW      6  
1b440 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
1b450 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1b460 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1b470 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49  QLITE_CREATE_TRI
1b480 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20  GGER        7   
1b490 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
1b4a0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1b4b0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1b4c0 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57  LITE_CREATE_VIEW
1b4d0 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f             8   /
1b4e0 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
1b4f0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1b500 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1b510 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20  ITE_DELETE      
1b520 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a            9   /*
1b530 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1b540 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1b550 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1b560 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20  TE_DROP_INDEX   
1b570 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20          10   /* 
1b580 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
1b590 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1b5a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1b5b0 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20  E_DROP_TABLE    
1b5c0 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54         11   /* T
1b5d0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1b5e0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1b5f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1b600 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58  _DROP_TEMP_INDEX
1b610 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e        12   /* In
1b620 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
1b630 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1b640 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1b650 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20  DROP_TEMP_TABLE 
1b660 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62       13   /* Tab
1b670 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1b680 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1b690 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1b6a0 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52  ROP_TEMP_TRIGGER
1b6b0 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67      14   /* Trig
1b6c0 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
1b6d0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1b6e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1b6f0 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20  OP_TEMP_VIEW    
1b700 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20     15   /* View 
1b710 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
1b720 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1b730 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1b740 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  P_TRIGGER       
1b750 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65    16   /* Trigge
1b760 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
1b770 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1b780 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1b790 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20  _VIEW           
1b7a0 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   17   /* View Na
1b7b0 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
1b7c0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1b7d0 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52  ine SQLITE_INSER
1b7e0 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
1b7f0 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  18   /* Table Na
1b800 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1b810 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1b820 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41  ne SQLITE_PRAGMA
1b830 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
1b840 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61  9   /* Pragma Na
1b850 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f  me     1st arg o
1b860 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e  r NULL */.#defin
1b870 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20  e SQLITE_READ   
1b880 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30                20
1b890 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1b8a0 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
1b8b0 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
1b8c0 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20   SQLITE_SELECT  
1b8d0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20               21 
1b8e0 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
1b8f0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1b900 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1b910 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49  SQLITE_TRANSACTI
1b920 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20  ON          22  
1b930 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20   /* Operation   
1b940 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1b950 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1b960 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20  QLITE_UPDATE    
1b970 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20             23   
1b980 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1b990 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20     Column Name  
1b9a0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1b9b0 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20  LITE_ATTACH     
1b9c0 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f            24   /
1b9d0 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20  * Filename      
1b9e0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1b9f0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1ba00 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20  ITE_DETACH      
1ba10 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a           25   /*
1ba20 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20   Database Name  
1ba30 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1ba40 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1ba50 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20  TE_ALTER_TABLE  
1ba60 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20          26   /* 
1ba70 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20  Database Name   
1ba80 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1ba90 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1baa0 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20  E_REINDEX       
1bab0 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49         27   /* I
1bac0 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e  ndex Name      N
1bad0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1bae0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1baf0 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20  _ANALYZE        
1bb00 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61        28   /* Ta
1bb10 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
1bb20 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1bb30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1bb40 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20  CREATE_VTABLE   
1bb50 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62       29   /* Tab
1bb60 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64  le Name      Mod
1bb70 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  ule Name     */.
1bb80 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1bb90 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20  ROP_VTABLE      
1bba0 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c      30   /* Tabl
1bbb0 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75  e Name      Modu
1bbc0 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  le Name     */.#
1bbd0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55  define SQLITE_FU
1bbe0 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20  NCTION          
1bbf0 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20     31   /* NULL 
1bc00 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63 74             Funct
1bc10 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64  ion Name   */.#d
1bc20 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56  efine SQLITE_SAV
1bc30 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20  EPOINT          
1bc40 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74    32   /* Operat
1bc50 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f  ion       Savepo
1bc60 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65  int Name  */.#de
1bc70 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59  fine SQLITE_COPY
1bc80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1bc90 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67    0   /* No long
1bca0 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a  er used */../*.*
1bcb0 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63  * CAPI3REF: Trac
1bcc0 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e  ing And Profilin
1bcd0 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  g Functions.**.*
1bce0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1bcf0 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61   register callba
1bd00 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61  ck functions tha
1bd10 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f  t can be used fo
1bd20 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64  r.** tracing and
1bd30 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65   profiling the e
1bd40 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20  xecution of SQL 
1bd50 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
1bd60 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  * ^The callback 
1bd70 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65  function registe
1bd80 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74  red by sqlite3_t
1bd90 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  race() is invoke
1bda0 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20  d at.** various 
1bdb0 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51  times when an SQ
1bdc0 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62  L statement is b
1bdd0 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c  eing run by [sql
1bde0 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a  ite3_step()]..**
1bdf0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72   ^The sqlite3_tr
1be00 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69  ace() callback i
1be10 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61  s invoked with a
1be20 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67   UTF-8 rendering
1be30 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73   of the.** SQL s
1be40 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73  tatement text as
1be50 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66   the statement f
1be60 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 65 63  irst begins exec
1be70 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69  uting..** ^(Addi
1be80 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74  tional sqlite3_t
1be90 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73  race() callbacks
1bea0 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20   might occur.** 
1beb0 61 73 20 65 61 63 68 20 74 72 69 67 67 65 72 65  as each triggere
1bec0 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20  d subprogram is 
1bed0 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63 61  entered.  The ca
1bee0 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67  llbacks for trig
1bef0 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20  gers.** contain 
1bf00 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d  a UTF-8 SQL comm
1bf10 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69 66  ent that identif
1bf20 69 65 73 20 74 68 65 20 74 72 69 67 67 65 72 2e  ies the trigger.
1bf30 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61  )^.**.** ^The ca
1bf40 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
1bf50 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
1bf60 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20  lite3_profile() 
1bf70 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73  is invoked.** as
1bf80 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d   each SQL statem
1bf90 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e  ent finishes.  ^
1bfa0 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c  The profile call
1bfb0 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a  back contains.**
1bfc0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
1bfd0 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64  atement text and
1bfe0 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20   an estimate of 
1bff0 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a  wall-clock time.
1c000 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74  ** of how long t
1c010 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  hat statement to
1c020 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65  ok to run.  ^The
1c030 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63   profile callbac
1c040 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20  k.** time is in 
1c050 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63  units of nanosec
1c060 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68  onds, however th
1c070 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d  e current implem
1c080 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f  entation.** is o
1c090 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d  nly capable of m
1c0a0 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c  illisecond resol
1c0b0 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78  ution so the six
1c0c0 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63 61   least significa
1c0d0 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20  nt.** digits in 
1c0e0 74 68 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61  the time are mea
1c0f0 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72  ningless.  Futur
1c100 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
1c110 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72  Lite.** might pr
1c120 6f 76 69 64 65 20 67 72 65 61 74 65 72 20 72 65  ovide greater re
1c130 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20  solution on the 
1c140 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63  profiler callbac
1c150 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74  k.  The.** sqlit
1c160 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e  e3_profile() fun
1c170 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65  ction is conside
1c180 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c  red experimental
1c190 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65   and is.** subje
1c1a0 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20  ct to change in 
1c1b0 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  future versions 
1c1c0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 76 6f  of SQLite..*/.vo
1c1d0 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63  id *sqlite3_trac
1c1e0 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64  e(sqlite3*, void
1c1f0 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c  (*xTrace)(void*,
1c200 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f  const char*), vo
1c210 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 45 58 50  id*);.SQLITE_EXP
1c220 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a  ERIMENTAL void *
1c230 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
1c240 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69  sqlite3*,.   voi
1c250 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69  d(*xProfile)(voi
1c260 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73  d*,const char*,s
1c270 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20  qlite3_uint64), 
1c280 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
1c290 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50  API3REF: Query P
1c2a0 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b  rogress Callback
1c2b0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
1c2c0 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
1c2d0 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69  ndler(D,N,X,P) i
1c2e0 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
1c2f0 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  the callback.** 
1c300 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65  function X to be
1c310 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69   invoked periodi
1c320 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e  cally during lon
1c330 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20  g running calls 
1c340 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  to.** [sqlite3_e
1c350 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  xec()], [sqlite3
1c360 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71  _step()] and [sq
1c370 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1c380 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61  )] for.** databa
1c390 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e  se connection D.
1c3a0 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65    An example use
1c3b0 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74   for this.** int
1c3c0 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65  erface is to kee
1c3d0 70 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20  p a GUI updated 
1c3e0 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71  during a large q
1c3f0 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  uery..**.** ^The
1c400 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20   parameter P is 
1c410 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61  passed through a
1c420 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d  s the only param
1c430 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20  eter to the .** 
1c440 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1c450 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d  n X.  ^The param
1c460 65 74 65 72 20 4e 20 69 73 20 74 68 65 20 6e 75  eter N is the nu
1c470 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72  mber of .** [vir
1c480 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73  tual machine ins
1c490 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20  tructions] that 
1c4a0 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 62 65  are evaluated be
1c4b0 74 77 65 65 6e 20 73 75 63 63 65 73 73 69 76 65  tween successive
1c4c0 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  .** invocations 
1c4d0 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  of the callback 
1c4e0 58 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61  X..**.** ^Only a
1c4f0 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73   single progress
1c500 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 20   handler may be 
1c510 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 74  defined at one t
1c520 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61  ime per.** [data
1c530 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1c540 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77 20  ; setting a new 
1c550 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
1c560 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20   cancels the.** 
1c570 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69  old one.  ^Setti
1c580 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58 20 74  ng parameter X t
1c590 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 20  o NULL disables 
1c5a0 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  the progress han
1c5b0 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72  dler..** ^The pr
1c5c0 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 69  ogress handler i
1c5d0 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 20  s also disabled 
1c5e0 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20  by setting N to 
1c5f0 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20  a value less.** 
1c600 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49  than 1..**.** ^I
1c610 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63  f the progress c
1c620 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
1c630 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70  non-zero, the op
1c640 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e  eration is.** in
1c650 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 69 73  terrupted.  This
1c660 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65 20   feature can be 
1c670 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
1c680 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20  t a.** "Cancel" 
1c690 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20  button on a GUI 
1c6a0 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20  progress dialog 
1c6b0 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  box..**.** The p
1c6c0 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
1c6d0 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f  callback must no
1c6e0 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68  t do anything th
1c6f0 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a  at will modify.*
1c700 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
1c710 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
1c720 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72  nvoked the progr
1c730 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20  ess handler..** 
1c740 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
1c750 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1c760 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
1c770 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
1c780 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
1c790 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
1c7a0 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
1c7b0 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
1c7c0 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
1c7d0 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  *.*/.void sqlite
1c7e0 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c  3_progress_handl
1c7f0 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  er(sqlite3*, int
1c800 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c  , int(*)(void*),
1c810 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
1c820 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e  CAPI3REF: Openin
1c830 67 20 41 20 4e 65 77 20 44 61 74 61 62 61 73 65  g A New Database
1c840 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a   Connection.**.*
1c850 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
1c860 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65  s open an SQLite
1c870 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 61   database file a
1c880 73 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  s specified by t
1c890 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20  he .** filename 
1c8a0 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66  argument. ^The f
1c8b0 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
1c8c0 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
1c8d0 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20  as UTF-8 for.** 
1c8e0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
1c8f0 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nd sqlite3_open_
1c900 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d  v2() and as UTF-
1c910 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
1c920 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66   byte.** order f
1c930 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  or sqlite3_open1
1c940 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61  6(). ^(A [databa
1c950 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
1c960 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79  andle is usually
1c970 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20  .** returned in 
1c980 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61  *ppDb, even if a
1c990 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20  n error occurs. 
1c9a0 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74   The only except
1c9b0 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69  ion is that.** i
1c9c0 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62  f SQLite is unab
1c9d0 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  le to allocate m
1c9e0 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
1c9f0 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
1ca00 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69  ct,.** a NULL wi
1ca10 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e  ll be written in
1ca20 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64  to *ppDb instead
1ca30 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   of a pointer to
1ca40 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a   the [sqlite3].*
1ca50 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66  * object.)^ ^(If
1ca60 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
1ca70 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20   opened (and/or 
1ca80 63 72 65 61 74 65 64 29 20 73 75 63 63 65 73 73  created) success
1ca90 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b  fully, then.** [
1caa0 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65  SQLITE_OK] is re
1cab0 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69  turned.  Otherwi
1cac0 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  se an [error cod
1cad0 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  e] is returned.)
1cae0 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ^ ^The.** [sqlit
1caf0 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20  e3_errmsg()] or 
1cb00 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  [sqlite3_errmsg1
1cb10 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61  6()] routines ca
1cb20 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  n be used to obt
1cb30 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73  ain.** an Englis
1cb40 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72  h language descr
1cb50 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72  iption of the er
1cb60 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  ror following a 
1cb70 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a  failure of any.*
1cb80 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  * of the sqlite3
1cb90 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73  _open() routines
1cba0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66  ..**.** ^The def
1cbb0 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f  ault encoding fo
1cbc0 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 77  r the database w
1cbd0 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 69 66 0a  ill be UTF-8 if.
1cbe0 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
1cbf0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
1cc00 6e 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64  n_v2() is called
1cc10 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69   and.** UTF-16 i
1cc20 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
1cc30 65 20 6f 72 64 65 72 20 69 66 20 73 71 6c 69 74  e order if sqlit
1cc40 65 33 5f 6f 70 65 6e 31 36 28 29 20 69 73 20 75  e3_open16() is u
1cc50 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68  sed..**.** Wheth
1cc60 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72  er or not an err
1cc70 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69  or occurs when i
1cc80 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73  t is opened, res
1cc90 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69  ources.** associ
1cca0 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64  ated with the [d
1ccb0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1ccc0 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c  on] handle shoul
1ccd0 64 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79  d be released by
1cce0 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74  .** passing it t
1ccf0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  o [sqlite3_close
1cd00 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e  ()] when it is n
1cd10 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65  o longer require
1cd20 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
1cd30 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
1cd40 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c  nterface works l
1cd50 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ike sqlite3_open
1cd60 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61  ().** except tha
1cd70 74 20 69 74 20 61 63 63 65 70 74 73 20 74 77 6f  t it accepts two
1cd80 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61   additional para
1cd90 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 74  meters for addit
1cda0 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a  ional control.**
1cdb0 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64 61   over the new da
1cdc0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1cdd0 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20  n.  ^(The flags 
1cde0 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
1cdf0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1ce00 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f  ) can take one o
1ce10 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69  f.** the followi
1ce20 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c  ng three values,
1ce30 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62   optionally comb
1ce40 69 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a  ined with the .*
1ce50 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  * [SQLITE_OPEN_N
1ce60 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45  OMUTEX], [SQLITE
1ce70 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d  _OPEN_FULLMUTEX]
1ce80 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  , [SQLITE_OPEN_S
1ce90 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20  HAREDCACHE],.** 
1cea0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49  [SQLITE_OPEN_PRI
1ceb0 56 41 54 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f  VATECACHE], and/
1cec0 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  or [SQLITE_OPEN_
1ced0 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a  URI] flags:)^.**
1cee0 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64  .** <dl>.** ^(<d
1cef0 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
1cf00 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a  EADONLY]</dt>.**
1cf10 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
1cf20 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72  e is opened in r
1cf30 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20  ead-only mode.  
1cf40 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
1cf50 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65  does not.** alre
1cf60 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72  ady exist, an er
1cf70 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ror is returned.
1cf80 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
1cf90 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
1cfa0 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e  _READWRITE]</dt>
1cfb0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
1cfc0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
1cfd0 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77  or reading and w
1cfe0 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62  riting if possib
1cff0 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a  le, or reading.*
1d000 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69  * only if the fi
1d010 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74  le is write prot
1d020 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65  ected by the ope
1d030 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20  rating system.  
1d040 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73  In either.** cas
1d050 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6d  e the database m
1d060 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 73  ust already exis
1d070 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  t, otherwise an 
1d080 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
1d090 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  d.</dd>)^.**.** 
1d0a0 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  ^(<dt>[SQLITE_OP
1d0b0 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20  EN_READWRITE] | 
1d0c0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
1d0d0 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATE]</dt>.** <dd
1d0e0 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
1d0f0 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
1d100 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c  ing and writing,
1d110 20 61 6e 64 20 69 73 20 63 72 65 61 74 65 64 20   and is created 
1d120 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f  if.** it does no
1d130 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e  t already exist.
1d140 20 54 68 69 73 20 69 73 20 74 68 65 20 62 65 68   This is the beh
1d150 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c  avior that is al
1d160 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a  ways used for.**
1d170 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
1d180 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
1d190 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20  16().</dd>)^.** 
1d1a0 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  </dl>.**.** If t
1d1b0 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
1d1c0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
1d1d0 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65  _v2() is not one
1d1e0 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69   of the.** combi
1d1f0 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62  nations shown ab
1d200 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63  ove optionally c
1d210 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 6f 74 68  ombined with oth
1d220 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  er.** [SQLITE_OP
1d230 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51  EN_READONLY | SQ
1d240 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73  LITE_OPEN_* bits
1d250 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65  ].** then the be
1d260 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
1d270 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ned..**.** ^If t
1d280 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
1d290 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73  NOMUTEX] flag is
1d2a0 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64   set, then the d
1d2b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1d2c0 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74  on.** opens in t
1d2d0 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20  he multi-thread 
1d2e0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
1d2f0 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20   as long as the 
1d300 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a  single-thread.**
1d310 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65   mode has not be
1d320 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c  en set at compil
1d330 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d  e-time or start-
1d340 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a  time.  ^If the.*
1d350 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  * [SQLITE_OPEN_F
1d360 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69  ULLMUTEX] flag i
1d370 73 20 73 65 74 20 74 68 65 6e 20 74 68 65 20 64  s set then the d
1d380 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1d390 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74  on opens.** in t
1d3a0 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74  he serialized [t
1d3b0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75  hreading mode] u
1d3c0 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72  nless single-thr
1d3d0 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69  ead was.** previ
1d3e0 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61  ously selected a
1d3f0 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  t compile-time o
1d400 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a  r start-time..**
1d410 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50   ^The [SQLITE_OP
1d420 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20  EN_SHAREDCACHE] 
1d430 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20  flag causes the 
1d440 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1d450 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69  ion to be.** eli
1d460 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68  gible to use [sh
1d470 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d  ared cache mode]
1d480 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  , regardless of 
1d490 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73  whether or not s
1d4a0 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69  hared.** cache i
1d4b0 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20  s enabled using 
1d4c0 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f  [sqlite3_enable_
1d4d0 73 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e  shared_cache()].
1d4e0 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54    ^The.** [SQLIT
1d4f0 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
1d500 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73  CHE] flag causes
1d510 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1d520 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a  nnection to not.
1d530 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65 20 69  ** participate i
1d540 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20  n [shared cache 
1d550 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74  mode] even if it
1d560 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a   is enabled..**.
1d570 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70  ** ^The fourth p
1d580 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1d590 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
1d5a0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
1d5b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  .** [sqlite3_vfs
1d5c0 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65  ] object that de
1d5d0 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74  fines the operat
1d5e0 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72  ing system inter
1d5f0 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  face that.** the
1d600 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f   new database co
1d610 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20  nnection should 
1d620 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f  use.  ^If the fo
1d630 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
1d640 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s.** a NULL poin
1d650 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65 66  ter then the def
1d660 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
1d670 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  s] object is use
1d680 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
1d690 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d   filename is ":m
1d6a0 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20  emory:", then a 
1d6b0 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61  private, tempora
1d6c0 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  ry in-memory dat
1d6d0 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61  abase.** is crea
1d6e0 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e  ted for the conn
1d6f0 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69  ection.  ^This i
1d700 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
1d710 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68  e will vanish wh
1d720 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  en.** the databa
1d730 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
1d740 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65   closed.  Future
1d750 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
1d760 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b  ite might.** mak
1d770 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f  e use of additio
1d780 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65  nal special file
1d790 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e  names that begin
1d7a0 20 77 69 74 68 20 74 68 65 20 22 3a 22 20 63 68   with the ":" ch
1d7b0 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69  aracter..** It i
1d7c0 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
1d7d0 61 74 20 77 68 65 6e 20 61 20 64 61 74 61 62 61  at when a databa
1d7e0 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75  se filename actu
1d7f0 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20  ally does begin 
1d800 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68  with.** a ":" ch
1d810 61 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75  aracter you shou
1d820 6c 64 20 70 72 65 66 69 78 20 74 68 65 20 66 69  ld prefix the fi
1d830 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61  lename with a pa
1d840 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a  thname such as.*
1d850 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20  * "./" to avoid 
1d860 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a  ambiguity..**.**
1d870 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d   ^If the filenam
1d880 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74  e is an empty st
1d890 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69  ring, then a pri
1d8a0 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a  vate, temporary.
1d8b0 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62  ** on-disk datab
1d8c0 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61  ase will be crea
1d8d0 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76  ted.  ^This priv
1d8e0 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c  ate database wil
1d8f0 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  l be.** automati
1d900 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73  cally deleted as
1d910 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74   soon as the dat
1d920 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1d930 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a   is closed..**.*
1d940 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  * [[URI filename
1d950 73 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65  s in sqlite3_ope
1d960 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69  n()]] <h3>URI Fi
1d970 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a  lenames</h3>.**.
1d980 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66 69 6c 65  ** ^If [URI file
1d990 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72 65 74 61  name] interpreta
1d9a0 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c  tion is enabled,
1d9b0 20 61 6e 64 20 74 68 65 20 66 69 6c 65 6e 61 6d   and the filenam
1d9c0 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65  e argument.** be
1d9d0 67 69 6e 73 20 77 69 74 68 20 22 66 69 6c 65 3a  gins with "file:
1d9e0 22 2c 20 74 68 65 6e 20 74 68 65 20 66 69 6c 65  ", then the file
1d9f0 6e 61 6d 65 20 69 73 20 69 6e 74 65 72 70 72 65  name is interpre
1da00 74 65 64 20 61 73 20 61 20 55 52 49 2e 20 5e 55  ted as a URI. ^U
1da10 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69  RI.** filename i
1da20 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73  nterpretation is
1da30 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20   enabled if the 
1da40 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
1da50 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74  ] flag is.** set
1da60 20 69 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61   in the fourth a
1da70 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
1da80 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72  e3_open_v2(), or
1da90 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 62 65   if it has.** be
1daa0 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61  en enabled globa
1dab0 6c 6c 79 20 75 73 69 6e 67 20 74 68 65 20 5b 53  lly using the [S
1dac0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
1dad0 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68 20 74 68  ] option with th
1dae0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  e.** [sqlite3_co
1daf0 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f  nfig()] method o
1db00 72 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45  r by the [SQLITE
1db10 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c  _USE_URI] compil
1db20 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a  e-time option..*
1db30 2a 20 41 73 20 6f 66 20 53 51 4c 69 74 65 20 76  * As of SQLite v
1db40 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 52  ersion 3.7.7, UR
1db50 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72  I filename inter
1db60 70 72 65 74 61 74 69 6f 6e 20 69 73 20 74 75 72  pretation is tur
1db70 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65  ned off.** by de
1db80 66 61 75 6c 74 2c 20 62 75 74 20 66 75 74 75 72  fault, but futur
1db90 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
1dba0 4c 69 74 65 20 6d 69 67 68 74 20 65 6e 61 62 6c  Lite might enabl
1dbb0 65 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a  e URI filename.*
1dbc0 2a 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  * interpretation
1dbd0 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20 53 65   by default.  Se
1dbe0 65 20 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  e "[URI filename
1dbf0 73 5d 22 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  s]" for addition
1dc00 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
1dc10 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c  n..**.** URI fil
1dc20 65 6e 61 6d 65 73 20 61 72 65 20 70 61 72 73 65  enames are parse
1dc30 64 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 52  d according to R
1dc40 46 43 20 33 39 38 36 2e 20 5e 49 66 20 74 68 65  FC 3986. ^If the
1dc50 20 55 52 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e   URI contains an
1dc60 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c 20 74  .** authority, t
1dc70 68 65 6e 20 69 74 20 6d 75 73 74 20 62 65 20 65  hen it must be e
1dc80 69 74 68 65 72 20 61 6e 20 65 6d 70 74 79 20 73  ither an empty s
1dc90 74 72 69 6e 67 20 6f 72 20 74 68 65 20 73 74 72  tring or the str
1dca0 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f  ing .** "localho
1dcb0 73 74 22 2e 20 5e 49 66 20 74 68 65 20 61 75 74  st". ^If the aut
1dcc0 68 6f 72 69 74 79 20 69 73 20 6e 6f 74 20 61 6e  hority is not an
1dcd0 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72   empty string or
1dce0 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e   "localhost", an
1dcf0 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20 72 65   .** error is re
1dd00 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20 63 61  turned to the ca
1dd10 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72 61 67 6d  ller. ^The fragm
1dd20 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ent component of
1dd30 20 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70   a URI, if .** p
1dd40 72 65 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72  resent, is ignor
1dd50 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  ed..**.** ^SQLit
1dd60 65 20 75 73 65 73 20 74 68 65 20 70 61 74 68 20  e uses the path 
1dd70 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65  component of the
1dd80 20 55 52 49 20 61 73 20 74 68 65 20 6e 61 6d 65   URI as the name
1dd90 20 6f 66 20 74 68 65 20 64 69 73 6b 20 66 69 6c   of the disk fil
1dda0 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74 61  e.** which conta
1ddb0 69 6e 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ins the database
1ddc0 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 62  . ^If the path b
1ddd0 65 67 69 6e 73 20 77 69 74 68 20 61 20 27 2f 27  egins with a '/'
1dde0 20 63 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20   character, .** 
1ddf0 74 68 65 6e 20 69 74 20 69 73 20 69 6e 74 65 72  then it is inter
1de00 70 72 65 74 65 64 20 61 73 20 61 6e 20 61 62 73  preted as an abs
1de10 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e 49 66 20  olute path. ^If 
1de20 74 68 65 20 70 61 74 68 20 64 6f 65 73 20 6e 6f  the path does no
1de30 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68  t begin .** with
1de40 20 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20   a '/' (meaning 
1de50 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69  that the authori
1de60 74 79 20 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d  ty section is om
1de70 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 55  itted from the U
1de80 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  RI).** then the 
1de90 70 61 74 68 20 69 73 20 69 6e 74 65 72 70 72 65  path is interpre
1dea0 74 65 64 20 61 73 20 61 20 72 65 6c 61 74 69 76  ted as a relativ
1deb0 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 4f 6e 20  e path. .** ^On 
1dec0 77 69 6e 64 6f 77 73 2c 20 74 68 65 20 66 69 72  windows, the fir
1ded0 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  st component of 
1dee0 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68  an absolute path
1def0 20 0a 2a 2a 20 69 73 20 61 20 64 72 69 76 65 20   .** is a drive 
1df00 73 70 65 63 69 66 69 63 61 74 69 6f 6e 20 28 65  specification (e
1df10 2e 67 2e 20 22 43 3a 22 29 2e 0a 2a 2a 0a 2a 2a  .g. "C:")..**.**
1df20 20 5b 5b 63 6f 72 65 20 55 52 49 20 71 75 65 72   [[core URI quer
1df30 79 20 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a  y parameters]].*
1df40 2a 20 54 68 65 20 71 75 65 72 79 20 63 6f 6d 70  * The query comp
1df50 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 6d  onent of a URI m
1df60 61 79 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d  ay contain param
1df70 65 74 65 72 73 20 74 68 61 74 20 61 72 65 20 69  eters that are i
1df80 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 69  nterpreted.** ei
1df90 74 68 65 72 20 62 79 20 53 51 4c 69 74 65 20 69  ther by SQLite i
1dfa0 74 73 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b  tself, or by a [
1dfb0 56 46 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 53  VFS | custom VFS
1dfc0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d   implementation]
1dfd0 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65  ..** SQLite inte
1dfe0 72 70 72 65 74 73 20 74 68 65 20 66 6f 6c 6c 6f  rprets the follo
1dff0 77 69 6e 67 20 74 68 72 65 65 20 71 75 65 72 79  wing three query
1e000 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a   parameters:.**.
1e010 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69  ** <ul>.**   <li
1e020 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54  > <b>vfs</b>: ^T
1e030 68 65 20 22 76 66 73 22 20 70 61 72 61 6d 65 74  he "vfs" paramet
1e040 65 72 20 6d 61 79 20 62 65 20 75 73 65 64 20 74  er may be used t
1e050 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 6e 61  o specify the na
1e060 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56  me of.**     a V
1e070 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20 70  FS object that p
1e080 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65 72  rovides the oper
1e090 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74  ating system int
1e0a0 65 72 66 61 63 65 20 74 68 61 74 20 73 68 6f 75  erface that shou
1e0b0 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 65  ld.**     be use
1e0c0 64 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  d to access the 
1e0d0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f 6e  database file on
1e0e0 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 20   disk. ^If this 
1e0f0 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f  option is set to
1e100 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 79  .**     an empty
1e110 20 73 74 72 69 6e 67 20 74 68 65 20 64 65 66 61   string the defa
1e120 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20 69  ult VFS object i
1e130 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66 79  s used. ^Specify
1e140 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a  ing an unknown.*
1e150 2a 20 20 20 20 20 56 46 53 20 69 73 20 61 6e 20  *     VFS is an 
1e160 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74  error. ^If sqlit
1e170 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
1e180 75 73 65 64 20 61 6e 64 20 74 68 65 20 76 66 73  used and the vfs
1e190 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20   option is.**   
1e1a0 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e 20    present, then 
1e1b0 74 68 65 20 56 46 53 20 73 70 65 63 69 66 69 65  the VFS specifie
1e1c0 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e 20  d by the option 
1e1d0 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63 65  takes precedence
1e1e0 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 65   over.**     the
1e1f0 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73   value passed as
1e200 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
1e210 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
1e220 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  _open_v2()..**.*
1e230 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65  *   <li> <b>mode
1e240 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65  </b>: ^(The mode
1e250 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
1e260 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20  e set to either 
1e270 22 72 6f 22 2c 20 22 72 77 22 20 6f 72 0a 2a 2a  "ro", "rw" or.**
1e280 20 20 20 20 20 22 72 77 63 22 2e 20 41 74 74 65       "rwc". Atte
1e290 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74  mpting to set it
1e2a0 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61   to any other va
1e2b0 6c 75 65 20 69 73 20 61 6e 20 65 72 72 6f 72 29  lue is an error)
1e2c0 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22  ^. .**     ^If "
1e2d0 72 6f 22 20 69 73 20 73 70 65 63 69 66 69 65 64  ro" is specified
1e2e0 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
1e2f0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
1e300 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20  r read-only .** 
1e310 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73 74      access, just
1e320 20 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c 49   as if the [SQLI
1e330 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
1e340 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e 20  ] flag had been 
1e350 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20  set in the .**  
1e360 20 20 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e     third argumen
1e370 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 70 72 65  t to sqlite3_pre
1e380 70 61 72 65 5f 76 32 28 29 2e 20 5e 49 66 20 74  pare_v2(). ^If t
1e390 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69  he mode option i
1e3a0 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20  s set to .**    
1e3b0 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20   "rw", then the 
1e3c0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
1e3d0 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74  ed for read-writ
1e3e0 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74  e (but not creat
1e3f0 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73  e) .**     acces
1e400 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f  s, as if SQLITE_
1e410 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28  OPEN_READWRITE (
1e420 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f  but not SQLITE_O
1e430 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20  PEN_CREATE) had 
1e440 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74  .**     been set
1e450 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69  . ^Value "rwc" i
1e460 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20  s equivalent to 
1e470 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a  setting both .**
1e480 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e       SQLITE_OPEN
1e490 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64 20 53  _READWRITE and S
1e4a0 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
1e4b0 45 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f  E. ^If sqlite3_o
1e4c0 70 65 6e 5f 76 32 28 29 20 69 73 20 0a 2a 2a 20  pen_v2() is .** 
1e4d0 20 20 20 20 75 73 65 64 2c 20 69 74 20 69 73 20      used, it is 
1e4e0 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65 63  an error to spec
1e4f0 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f 72 20  ify a value for 
1e500 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74  the mode paramet
1e510 65 72 20 74 68 61 74 20 69 73 20 0a 2a 2a 20 20  er that is .**  
1e520 20 20 20 6c 65 73 73 20 72 65 73 74 72 69 63 74     less restrict
1e530 69 76 65 20 74 68 61 6e 20 74 68 61 74 20 73 70  ive than that sp
1e540 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 66  ecified by the f
1e550 6c 61 67 73 20 70 61 73 73 65 64 20 61 73 20 74  lags passed as t
1e560 68 65 20 74 68 69 72 64 20 0a 2a 2a 20 20 20 20  he third .**    
1e570 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
1e580 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68  *   <li> <b>cach
1e590 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68  e</b>: ^The cach
1e5a0 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
1e5b0 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72  be set to either
1e5c0 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20   "shared" or.** 
1e5d0 20 20 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e      "private". ^
1e5e0 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73  Setting it to "s
1e5f0 68 61 72 65 64 22 20 69 73 20 65 71 75 69 76 61  hared" is equiva
1e600 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
1e610 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  the.**     SQLIT
1e620 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
1e630 48 45 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c  HE bit in the fl
1e640 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73  ags argument pas
1e650 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71  sed to.**     sq
1e660 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
1e670 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20 63 61   ^Setting the ca
1e680 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  che parameter to
1e690 20 22 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a   "private" is .*
1e6a0 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74  *     equivalent
1e6b0 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20   to setting the 
1e6c0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
1e6d0 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a  ATECACHE bit..**
1e6e0 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33       ^If sqlite3
1e6f0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73  _open_v2() is us
1e700 65 64 20 61 6e 64 20 74 68 65 20 22 63 61 63 68  ed and the "cach
1e710 65 22 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  e" parameter is 
1e720 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20  present in.**   
1e730 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65    a URI filename
1e740 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72  , its value over
1e750 72 69 64 65 73 20 61 6e 79 20 62 65 68 61 76 69  rides any behavi
1e760 6f 75 72 20 72 65 71 75 65 73 74 65 64 20 62 79  our requested by
1e770 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20   setting.**     
1e780 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
1e790 41 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49  ATECACHE or SQLI
1e7a0 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
1e7b0 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 20 3c 2f 75  CHE flag..** </u
1e7c0 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66  l>.**.** ^Specif
1e7d0 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20  ying an unknown 
1e7e0 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65  parameter in the
1e7f0 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74   query component
1e800 20 6f 66 20 61 20 55 52 49 20 69 73 20 6e 6f 74   of a URI is not
1e810 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46   an.** error.  F
1e820 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
1e830 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 75  f SQLite might u
1e840 6e 64 65 72 73 74 61 6e 64 20 61 64 64 69 74 69  nderstand additi
1e850 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61  onal query.** pa
1e860 72 61 6d 65 74 65 72 73 2e 20 20 53 65 65 20 22  rameters.  See "
1e870 5b 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72  [query parameter
1e880 73 20 77 69 74 68 20 73 70 65 63 69 61 6c 20 6d  s with special m
1e890 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74 65  eaning to SQLite
1e8a0 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69  ]" for.** additi
1e8b0 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
1e8c0 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69  ..**.** [[URI fi
1e8d0 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d  lename examples]
1e8e0 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e 61  ] <h3>URI filena
1e8f0 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e  me examples</h3>
1e900 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f  .**.** <table bo
1e910 72 64 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63  rder="1" align=c
1e920 65 6e 74 65 72 20 63 65 6c 6c 70 61 64 64 69 6e  enter cellpaddin
1e930 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e  g=5>.** <tr><th>
1e940 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c   URI filenames <
1e950 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c  th> Results.** <
1e960 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74  tr><td> file:dat
1e970 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  a.db <td> .**   
1e980 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20         Open the 
1e990 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69  file "data.db" i
1e9a0 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69  n the current di
1e9b0 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e  rectory..** <tr>
1e9c0 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f  <td> file:/home/
1e9d0 66 72 65 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e  fred/data.db<br>
1e9e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c  .**          fil
1e9f0 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  e:///home/fred/d
1ea00 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20  ata.db <br> .** 
1ea10 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f           file://
1ea20 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66  localhost/home/f
1ea30 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e  red/data.db <br>
1ea40 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
1ea50 20 20 20 4f 70 65 6e 20 74 68 65 20 64 61 74 61     Open the data
1ea60 62 61 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65  base file "/home
1ea70 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a  /fred/data.db"..
1ea80 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
1ea90 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65  ://darkstar/home
1eaa0 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 74  /fred/data.db <t
1eab0 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
1eac0 41 6e 20 65 72 72 6f 72 2e 20 22 64 61 72 6b 73  An error. "darks
1ead0 74 61 72 22 20 69 73 20 6e 6f 74 20 61 20 72 65  tar" is not a re
1eae0 63 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f 72 69  cognized authori
1eaf0 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73  ty..** <tr><td s
1eb00 74 79 6c 65 3d 22 77 68 69 74 65 2d 73 70 61 63  tyle="white-spac
1eb10 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20  e:nowrap"> .**  
1eb20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f          file:///
1eb30 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30 61  C:/Documents%20a
1eb40 6e 64 25 32 30 53 65 74 74 69 6e 67 73 2f 66 72  nd%20Settings/fr
1eb50 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e  ed/Desktop/data.
1eb60 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57  db.**     <td> W
1eb70 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65  indows only: Ope
1eb80 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61  n the file "data
1eb90 2e 64 62 22 20 6f 6e 20 66 72 65 64 27 73 20 64  .db" on fred's d
1eba0 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a  esktop on drive.
1ebb0 2a 2a 20 20 20 20 20 20 20 20 20 20 43 3a 2e 20  **          C:. 
1ebc0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 25 32  Note that the %2
1ebd0 30 20 65 73 63 61 70 69 6e 67 20 69 6e 20 74 68  0 escaping in th
1ebe0 69 73 20 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f  is example is no
1ebf0 74 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20  t strictly .**  
1ec00 20 20 20 20 20 20 20 20 6e 65 63 65 73 73 61 72          necessar
1ec10 79 20 2d 20 73 70 61 63 65 20 63 68 61 72 61 63  y - space charac
1ec20 74 65 72 73 20 63 61 6e 20 62 65 20 75 73 65 64  ters can be used
1ec30 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20   literally.**   
1ec40 20 20 20 20 20 20 20 69 6e 20 55 52 49 20 66 69         in URI fi
1ec50 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e  lenames..** <tr>
1ec60 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64  <td> file:data.d
1ec70 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d  b?mode=ro&cache=
1ec80 70 72 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a  private <td> .**
1ec90 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66            Open f
1eca0 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e  ile "data.db" in
1ecb0 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72   the current dir
1ecc0 65 63 74 6f 72 79 20 66 6f 72 20 72 65 61 64 2d  ectory for read-
1ecd0 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20  only access..** 
1ece0 20 20 20 20 20 20 20 20 20 52 65 67 61 72 64 6c           Regardl
1ecf0 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
1ed00 72 20 6e 6f 74 20 73 68 61 72 65 64 2d 63 61 63  r not shared-cac
1ed10 68 65 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c  he mode is enabl
1ed20 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20  ed by.**        
1ed30 20 20 64 65 66 61 75 6c 74 2c 20 75 73 65 20 61    default, use a
1ed40 20 70 72 69 76 61 74 65 20 63 61 63 68 65 2e 0a   private cache..
1ed50 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
1ed60 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  :/home/fred/data
1ed70 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d 6e 6f 6c  .db?vfs=unix-nol
1ed80 6f 63 6b 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20  ock <td>.**     
1ed90 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22       Open file "
1eda0 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
1edb0 64 62 22 2e 20 55 73 65 20 74 68 65 20 73 70 65  db". Use the spe
1edc0 63 69 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 6e  cial VFS "unix-n
1edd0 6f 6c 6f 63 6b 22 2e 0a 2a 2a 20 3c 74 72 3e 3c  olock"..** <tr><
1ede0 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62  td> file:data.db
1edf0 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c  ?mode=readonly <
1ee00 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
1ee10 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64   An error. "read
1ee20 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76  only" is not a v
1ee30 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20  alid option for 
1ee40 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d  the "mode" param
1ee50 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65  eter..** </table
1ee60 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78  >.**.** ^URI hex
1ee70 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20  adecimal escape 
1ee80 73 65 71 75 65 6e 63 65 73 20 28 25 48 48 29 20  sequences (%HH) 
1ee90 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 77 69  are supported wi
1eea0 74 68 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e  thin the path an
1eeb0 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f  d.** query compo
1eec0 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20  nents of a URI. 
1eed0 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73  A hexadecimal es
1eee0 63 61 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f  cape sequence co
1eef0 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70  nsists of a.** p
1ef00 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25  ercent sign - "%
1ef10 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  " - followed by 
1ef20 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61  exactly two hexa
1ef30 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a  decimal digits .
1ef40 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e  ** specifying an
1ef50 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42   octet value. ^B
1ef60 65 66 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f  efore the path o
1ef70 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  r query componen
1ef80 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66  ts of a.** URI f
1ef90 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65  ilename are inte
1efa0 72 70 72 65 74 65 64 2c 20 74 68 65 79 20 61 72  rpreted, they ar
1efb0 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20  e encoded using 
1efc0 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a  UTF-8 and all .*
1efd0 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73  * hexadecimal es
1efe0 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 72  cape sequences r
1eff0 65 70 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e  eplaced by a sin
1f000 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e  gle byte contain
1f010 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65  ing the.** corre
1f020 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20  sponding octet. 
1f030 49 66 20 74 68 69 73 20 70 72 6f 63 65 73 73 20  If this process 
1f040 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76  generates an inv
1f050 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64  alid UTF-8 encod
1f060 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75  ing,.** the resu
1f070 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
1f080 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65  d..**.** <b>Note
1f090 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72   to Windows user
1f0a0 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f  s:</b>  The enco
1f0b0 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68  ding used for th
1f0c0 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
1f0d0 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65  ent.** of sqlite
1f0e0 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
1f0f0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d  ite3_open_v2() m
1f100 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f  ust be UTF-8, no
1f110 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f  t whatever.** co
1f120 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65 6e  depage is curren
1f130 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69  tly defined.  Fi
1f140 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69  lenames containi
1f150 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c  ng international
1f160 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d  .** characters m
1f170 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
1f180 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20   to UTF-8 prior 
1f190 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20  to passing them 
1f1a0 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  into.** sqlite3_
1f1b0 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  open() or sqlite
1f1c0 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2f 0a  3_open_v2()..*/.
1f1d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
1f1e0 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
1f1f0 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
1f200 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
1f210 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
1f220 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
1f230 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
1f240 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
1f250 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
1f260 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74  _open16(.  const
1f270 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c   void *filename,
1f280 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
1f290 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29  ilename (UTF-16)
1f2a0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
1f2b0 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
1f2c0 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
1f2d0 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74  handle */.);.int
1f2e0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1f2f0 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
1f300 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
1f310 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
1f320 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
1f330 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20  lite3 **ppDb,   
1f340 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
1f350 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
1f360 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20  /.  int flags,  
1f370 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46              /* F
1f380 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  lags */.  const 
1f390 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20  char *zVfs      
1f3a0 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53    /* Name of VFS
1f3b0 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a   module to use *
1f3c0 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
1f3d0 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c  3REF: Obtain Val
1f3e0 75 65 73 20 46 6f 72 20 55 52 49 20 50 61 72 61  ues For URI Para
1f3f0 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 69  meters.**.** Thi
1f400 73 20 69 73 20 61 20 75 74 69 6c 69 74 79 20 72  s is a utility r
1f410 6f 75 74 69 6e 65 2c 20 75 73 65 66 75 6c 20 74  outine, useful t
1f420 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  o VFS implementa
1f430 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63  tions, that chec
1f440 6b 73 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20  ks.** to see if 
1f450 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
1f460 77 61 73 20 61 20 55 52 49 20 74 68 61 74 20 63  was a URI that c
1f470 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63 69  ontained a speci
1f480 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61  fic query .** pa
1f490 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20  rameter, and if 
1f4a0 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76  so obtains the v
1f4b0 61 6c 75 65 20 6f 66 20 74 68 65 20 71 75 65 72  alue of the quer
1f4c0 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  y parameter..**.
1f4d0 2a 2a 20 54 68 65 20 7a 46 69 6c 65 6e 61 6d 65  ** The zFilename
1f4e0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
1f4f0 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65   filename pointe
1f500 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68  r passed into th
1f510 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 6d 65 74  e xOpen().** met
1f520 68 6f 64 20 6f 66 20 61 20 56 46 53 20 69 6d 70  hod of a VFS imp
1f530 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68  lementation.  Th
1f540 65 20 7a 50 61 72 61 6d 20 61 72 67 75 6d 65 6e  e zParam argumen
1f550 74 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  t is the name of
1f560 20 74 68 65 0a 2a 2a 20 71 75 65 72 79 20 70 61   the.** query pa
1f570 72 61 6d 65 74 65 72 20 77 65 20 73 65 65 6b 2e  rameter we seek.
1f580 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72    This routine r
1f590 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65  eturns the value
1f5a0 20 6f 66 20 74 68 65 20 7a 50 61 72 61 6d 0a 2a   of the zParam.*
1f5b0 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66 20 69  * parameter if i
1f5c0 74 20 65 78 69 73 74 73 2e 20 20 49 66 20 74 68  t exists.  If th
1f5d0 65 20 70 61 72 61 6d 65 74 65 72 20 64 6f 65 73  e parameter does
1f5e0 20 6e 6f 74 20 65 78 69 73 74 2c 20 74 68 69 73   not exist, this
1f5f0 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 74 75   routine.** retu
1f600 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
1f610 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  er..**.** If the
1f620 20 7a 46 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d   zFilename argum
1f630 65 6e 74 20 74 6f 20 74 68 69 73 20 66 75 6e 63  ent to this func
1f640 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 20 70 6f  tion is not a po
1f650 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69 74  inter that SQLit
1f660 65 0a 2a 2a 20 70 61 73 73 65 64 20 69 6e 74 6f  e.** passed into
1f670 20 74 68 65 20 78 4f 70 65 6e 20 56 46 53 20 6d   the xOpen VFS m
1f680 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 20  ethod, then the 
1f690 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73  behavior of this
1f6a0 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 69 73 20 75   routine.** is u
1f6b0 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f  ndefined and pro
1f6c0 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c  bably undesirabl
1f6d0 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  e..*/.const char
1f6e0 20 2a 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61   *sqlite3_uri_pa
1f6f0 72 61 6d 65 74 65 72 28 63 6f 6e 73 74 20 63 68  rameter(const ch
1f700 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63  ar *zFilename, c
1f710 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61  onst char *zPara
1f720 6d 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  m);.../*.** CAPI
1f730 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65  3REF: Error Code
1f740 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a  s And Messages.*
1f750 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1f760 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65  3_errcode() inte
1f770 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
1f780 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c  e numeric [resul
1f790 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65  t code] or.** [e
1f7a0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
1f7b0 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73  ode] for the mos
1f7c0 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20  t recent failed 
1f7d0 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61  sqlite3_* API ca
1f7e0 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  ll.** associated
1f7f0 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73   with a [databas
1f800 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49  e connection]. I
1f810 66 20 61 20 70 72 69 6f 72 20 41 50 49 20 63 61  f a prior API ca
1f820 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74  ll failed.** but
1f830 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
1f840 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65   API call succee
1f850 64 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20  ded, the return 
1f860 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71  value from.** sq
1f870 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20  lite3_errcode() 
1f880 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 5e  is undefined.  ^
1f890 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
1f8a0 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a  nded_errcode().*
1f8b0 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  * interface is t
1f8c0 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 74  he same except t
1f8d0 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 65  hat it always re
1f8e0 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65  turns the .** [e
1f8f0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
1f900 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65  ode] even when e
1f910 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
1f920 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61  odes are.** disa
1f930 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bled..**.** ^The
1f940 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28   sqlite3_errmsg(
1f950 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72  ) and sqlite3_er
1f960 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20  rmsg16() return 
1f970 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65  English-language
1f980 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65  .** text that de
1f990 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
1f9a0 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46  r, as either UTF
1f9b0 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73  -8 or UTF-16 res
1f9c0 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28  pectively..** ^(
1f9d0 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  Memory to hold t
1f9e0 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
1f9f0 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67   string is manag
1fa00 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a  ed internally..*
1fa10 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
1fa20 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  n does not need 
1fa30 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66  to worry about f
1fa40 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c  reeing the resul
1fa50 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74  t..** However, t
1fa60 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20  he error string 
1fa70 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 69  might be overwri
1fa80 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61  tten or dealloca
1fa90 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71  ted by.** subseq
1faa0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74  uent calls to ot
1fab0 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
1fac0 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29  face functions.)
1fad0 5e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ^.**.** When the
1fae0 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   serialized [thr
1faf0 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20  eading mode] is 
1fb00 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74  in use, it might
1fb10 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20   be the.** case 
1fb20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72  that a second er
1fb30 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20  ror occurs on a 
1fb40 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
1fb50 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68  in between.** th
1fb60 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69  e time of the fi
1fb70 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68  rst error and th
1fb80 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20  e call to these 
1fb90 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57  interfaces..** W
1fba0 68 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73  hen that happens
1fbb0 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72  , the second err
1fbc0 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72  or will be repor
1fbd0 74 65 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a  ted since these.
1fbe0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c  ** interfaces al
1fbf0 77 61 79 73 20 72 65 70 6f 72 74 20 74 68 65 20  ways report the 
1fc00 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73 75  most recent resu
1fc10 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a  lt.  To avoid.**
1fc20 20 74 68 69 73 2c 20 65 61 63 68 20 74 68 72 65   this, each thre
1fc30 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78  ad can obtain ex
1fc40 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20 74  clusive use of t
1fc50 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
1fc60 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79  nection] D.** by
1fc70 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74   invoking [sqlit
1fc80 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28  e3_mutex_enter](
1fc90 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65  [sqlite3_db_mute
1fca0 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62 65  x](D)) before be
1fcb0 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73  ginning.** to us
1fcc0 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67  e D and invoking
1fcd0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
1fce0 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f  leave]([sqlite3_
1fcf0 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66  db_mutex](D)) af
1fd00 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73  ter.** all calls
1fd10 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63   to the interfac
1fd20 65 73 20 6c 69 73 74 65 64 20 68 65 72 65 20 61  es listed here a
1fd30 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a  re completed..**
1fd40 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66  .** If an interf
1fd50 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 53  ace fails with S
1fd60 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68  QLITE_MISUSE, th
1fd70 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74  at means the int
1fd80 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e  erface.** was in
1fd90 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c  voked incorrectl
1fda0 79 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  y by the applica
1fdb0 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63  tion.  In that c
1fdc0 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f  ase, the.** erro
1fdd0 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61  r code and messa
1fde0 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f  ge may or may no
1fdf0 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74  t be set..*/.int
1fe00 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
1fe10 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69  (sqlite3 *db);.i
1fe20 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  nt sqlite3_exten
1fe30 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69  ded_errcode(sqli
1fe40 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20  te3 *db);.const 
1fe50 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72  char *sqlite3_er
1fe60 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a  rmsg(sqlite3*);.
1fe70 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
1fe80 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c  te3_errmsg16(sql
1fe90 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
1fea0 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53 74 61  API3REF: SQL Sta
1feb0 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a  tement Object.**
1fec0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70   KEYWORDS: {prep
1fed0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20  ared statement} 
1fee0 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  {prepared statem
1fef0 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  ents}.**.** An i
1ff00 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
1ff10 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74  object represent
1ff20 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73  s a single SQL s
1ff30 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69  tatement..** Thi
1ff40 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61 72 69  s object is vari
1ff50 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61  ously known as a
1ff60 20 22 70 72 65 70 61 72 65 64 20 73 74 61 74 65   "prepared state
1ff70 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22 63  ment" or a.** "c
1ff80 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74  ompiled SQL stat
1ff90 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79  ement" or simply
1ffa0 20 61 73 20 61 20 22 73 74 61 74 65 6d 65 6e 74   as a "statement
1ffb0 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66  "..**.** The lif
1ffc0 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65 6e 74  e of a statement
1ffd0 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d   object goes som
1ffe0 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 69 73  ething like this
1fff0 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20  :.**.** <ol>.** 
20000 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65 20  <li> Create the 
20010 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71  object using [sq
20020 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
20030 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 65 64  ()] or a related
20040 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 69 6f  .**      functio
20050 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20  n..** <li> Bind 
20060 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74 20  values to [host 
20070 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e  parameters] usin
20080 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  g the sqlite3_bi
20090 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69  nd_*().**      i
200a0 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c  nterfaces..** <l
200b0 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62  i> Run the SQL b
200c0 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
200d0 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f  e3_step()] one o
200e0 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a  r more times..**
200f0 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20   <li> Reset the 
20100 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20  statement using 
20110 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
20120 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a  ] then go back.*
20130 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 20 32  *      to step 2
20140 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20  .  Do this zero 
20150 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
20160 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74  * <li> Destroy t
20170 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20  he object using 
20180 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
20190 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a  e()]..** </ol>.*
201a0 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 6f  *.** Refer to do
201b0 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69  cumentation on i
201c0 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f 64  ndividual method
201d0 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64 69  s above for addi
201e0 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d  tional.** inform
201f0 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65  ation..*/.typede
20200 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
20210 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74  _stmt sqlite3_st
20220 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  mt;../*.** CAPI3
20230 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69  REF: Run-time Li
20240 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69  mits.**.** ^(Thi
20250 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f  s interface allo
20260 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76  ws the size of v
20270 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74  arious construct
20280 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a  s to be limited.
20290 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69  ** on a connecti
202a0 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e  on by connection
202b0 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 69 72   basis.  The fir
202c0 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
202d0 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  the.** [database
202e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f   connection] who
202f0 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62  se limit is to b
20300 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 65 64  e set or queried
20310 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64  .  The.** second
20320 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e   parameter is on
20330 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20  e of the [limit 
20340 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74  categories] that
20350 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61   define a.** cla
20360 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73  ss of constructs
20370 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69   to be size limi
20380 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 64 20  ted.  The third 
20390 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
203a0 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f  .** new limit fo
203b0 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74  r that construct
203c0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  .)^.**.** ^If th
203d0 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61  e new limit is a
203e0 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72   negative number
203f0 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75  , the limit is u
20400 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46  nchanged..** ^(F
20410 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 20 63 61  or each limit ca
20420 74 65 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49  tegory SQLITE_LI
20430 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20  MIT_<i>NAME</i> 
20440 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b  there is a .** [
20450 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20 75 70  limits | hard up
20460 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65  per bound].** se
20470 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  t at compile-tim
20480 65 20 62 79 20 61 20 43 20 70 72 65 70 72 6f 63  e by a C preproc
20490 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c  essor macro call
204a0 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20  ed.** [limits | 
204b0 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41  SQLITE_MAX_<i>NA
204c0 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65  ME</i>]..** (The
204d0 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68   "_LIMIT_" in th
204e0 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65  e name is change
204f0 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e  d to "_MAX_".))^
20500 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20 74 6f  .** ^Attempts to
20510 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69   increase a limi
20520 74 20 61 62 6f 76 65 20 69 74 73 20 68 61 72 64  t above its hard
20530 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65   upper bound are
20540 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75  .** silently tru
20550 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20 68 61  ncated to the ha
20560 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a  rd upper bound..
20570 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73  **.** ^Regardles
20580 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
20590 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 20 77 61  not the limit wa
205a0 73 20 63 68 61 6e 67 65 64 2c 20 74 68 65 20 0a  s changed, the .
205b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  ** [sqlite3_limi
205c0 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  t()] interface r
205d0 65 74 75 72 6e 73 20 74 68 65 20 70 72 69 6f 72  eturns the prior
205e0 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69   value of the li
205f0 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20  mit..** ^Hence, 
20600 74 6f 20 66 69 6e 64 20 74 68 65 20 63 75 72 72  to find the curr
20610 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61 20 6c  ent value of a l
20620 69 6d 69 74 20 77 69 74 68 6f 75 74 20 63 68 61  imit without cha
20630 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d  nging it,.** sim
20640 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69 73 20  ply invoke this 
20650 69 6e 74 65 72 66 61 63 65 20 77 69 74 68 20 74  interface with t
20660 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
20670 65 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a  er set to -1..**
20680 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d  .** Run-time lim
20690 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  its are intended
206a0 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c   for use in appl
206b0 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61  ications that ma
206c0 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65  nage.** both the
206d0 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20  ir own internal 
206e0 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73  database and als
206f0 6f 20 64 61 74 61 62 61 73 65 73 20 74 68 61 74  o databases that
20700 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a   are controlled.
20710 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64 20  ** by untrusted 
20720 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73  external sources
20730 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70  .  An example ap
20740 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20  plication might 
20750 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77  be a.** web brow
20760 73 65 72 20 74 68 61 74 20 68 61 73 20 69 74 73  ser that has its
20770 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20 66   own databases f
20780 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f  or storing histo
20790 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61  ry and.** separa
207a0 74 65 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e  te databases con
207b0 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53  trolled by JavaS
207c0 63 72 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f  cript applicatio
207d0 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a  ns downloaded.**
207e0 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65   off the Interne
207f0 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c  t.  The internal
20800 20 64 61 74 61 62 61 73 65 73 20 63 61 6e 20 62   databases can b
20810 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c  e given the.** l
20820 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69  arge, default li
20830 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73 65 73  mits.  Databases
20840 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74 65   managed by exte
20850 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e  rnal sources can
20860 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63  .** be given muc
20870 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73  h smaller limits
20880 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65   designed to pre
20890 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66  vent a denial of
208a0 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61   service.** atta
208b0 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20  ck.  Developers 
208c0 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20  might also want 
208d0 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69  to use the [sqli
208e0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
208f0 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61  er()].** interfa
20900 63 65 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f  ce to further co
20910 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20  ntrol untrusted 
20920 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f  SQL.  The size o
20930 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  f the database.*
20940 2a 20 63 72 65 61 74 65 64 20 62 79 20 61 6e 20  * created by an 
20950 75 6e 74 72 75 73 74 65 64 20 73 63 72 69 70 74  untrusted script
20960 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65   can be containe
20970 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  d using the.** [
20980 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20  max_page_count] 
20990 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20  [PRAGMA]..**.** 
209a0 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d  New run-time lim
209b0 69 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61  it categories ma
209c0 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
209d0 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a  ture releases..*
209e0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69  /.int sqlite3_li
209f0 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  mit(sqlite3*, in
20a00 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c  t id, int newVal
20a10 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
20a20 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d  EF: Run-Time Lim
20a30 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a  it Categories.**
20a40 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69   KEYWORDS: {limi
20a50 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69  t category} {*li
20a60 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a  mit categories}.
20a70 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
20a80 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72  tants define var
20a90 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65  ious performance
20aa0 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20   limits.** that 
20ab0 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61  can be lowered a
20ac0 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67  t run-time using
20ad0 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
20ae0 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70  )]..** The synop
20af0 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69  sis of the meani
20b00 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f  ngs of the vario
20b10 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f  us limits is sho
20b20 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64  wn below..** Add
20b30 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
20b40 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65  ion is available
20b50 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69   at [limits | Li
20b60 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e  mits in SQLite].
20b70 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b  .**.** <dl>.** [
20b80 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  [SQLITE_LIMIT_LE
20b90 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  NGTH]] ^(<dt>SQL
20ba0 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
20bb0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
20bc0 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66   maximum size of
20bd0 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42   any string or B
20be0 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77  LOB or table row
20bf0 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29  , in bytes.<dd>)
20c00 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
20c10 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
20c20 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
20c30 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
20c40 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
20c50 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
20c60 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65   of an SQL state
20c70 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c  ment, in bytes.<
20c80 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
20c90 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
20ca0 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  MN]] ^(<dt>SQLIT
20cb0 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f  E_LIMIT_COLUMN</
20cc0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
20cd0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
20ce0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61   columns in a ta
20cf0 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f  ble definition o
20d00 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75  r in the.** resu
20d10 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c  lt set of a [SEL
20d20 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69  ECT] or the maxi
20d30 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  mum number of co
20d40 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65  lumns in an inde
20d50 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52  x.** or in an OR
20d60 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20  DER BY or GROUP 
20d70 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29  BY clause.</dd>)
20d80 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
20d90 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54  _LIMIT_EXPR_DEPT
20da0 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
20db0 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54  _LIMIT_EXPR_DEPT
20dc0 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
20dd0 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20  e maximum depth 
20de0 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 72 65  of the parse tre
20df0 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73  e on any express
20e00 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ion.</dd>)^.**.*
20e10 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
20e20 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54  _COMPOUND_SELECT
20e30 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
20e40 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53  LIMIT_COMPOUND_S
20e50 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ELECT</dt>.** <d
20e60 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
20e70 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e  mber of terms in
20e80 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45   a compound SELE
20e90 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64  CT statement.</d
20ea0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
20eb0 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
20ec0 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  P]] ^(<dt>SQLITE
20ed0 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f  _LIMIT_VDBE_OP</
20ee0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
20ef0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
20f00 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e   instructions in
20f10 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69   a virtual machi
20f20 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73  ne program.** us
20f30 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
20f40 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
20f50 2e 20 20 54 68 69 73 20 6c 69 6d 69 74 20 69 73  .  This limit is
20f60 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a   not currently.*
20f70 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75  * enforced, thou
20f80 67 68 20 74 68 61 74 20 6d 69 67 68 74 20 62 65  gh that might be
20f90 20 61 64 64 65 64 20 69 6e 20 73 6f 6d 65 20 66   added in some f
20fa0 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66  uture release of
20fb0 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e  .** SQLite.</dd>
20fc0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
20fd0 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
20fe0 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  _ARG]] ^(<dt>SQL
20ff0 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
21000 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c  ON_ARG</dt>.** <
21010 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
21020 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
21030 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e  ts on a function
21040 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
21050 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54  [SQLITE_LIMIT_AT
21060 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53  TACHED]] ^(<dt>S
21070 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41  QLITE_LIMIT_ATTA
21080 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  CHED</dt>.** <dd
21090 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
210a0 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c  ber of [ATTACH |
210b0 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
210c0 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a  ses].)^</dd>.**.
210d0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
210e0 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
210f0 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74  ENGTH]].** ^(<dt
21100 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49  >SQLITE_LIMIT_LI
21110 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54  KE_PATTERN_LENGT
21120 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
21130 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
21140 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e 20   of the pattern 
21150 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
21160 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c  [LIKE] or.** [GL
21170 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f  OB] operators.</
21180 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
21190 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
211a0 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20  BLE_NUMBER]].** 
211b0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
211c0 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
211d0 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ER</dt>.** <dd>T
211e0 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78  he maximum index
211f0 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b   number of any [
21200 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e  parameter] in an
21210 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29   SQL statement.)
21220 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
21230 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44  _LIMIT_TRIGGER_D
21240 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  EPTH]] ^(<dt>SQL
21250 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45  ITE_LIMIT_TRIGGE
21260 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20  R_DEPTH</dt>.** 
21270 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
21280 64 65 70 74 68 20 6f 66 20 72 65 63 75 72 73 69  depth of recursi
21290 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73 2e  on for triggers.
212a0 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e  </dd>)^.** </dl>
212b0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
212c0 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20  TE_LIMIT_LENGTH 
212d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
212e0 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
212f0 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
21300 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
21310 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
21320 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
21330 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  N               
21340 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
21350 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
21360 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20  _DEPTH          
21370 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
21380 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d  SQLITE_LIMIT_COM
21390 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20  POUND_SELECT    
213a0 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
213b0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44   SQLITE_LIMIT_VD
213c0 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20  BE_OP           
213d0 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e          5.#defin
213e0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  e SQLITE_LIMIT_F
213f0 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20  UNCTION_ARG     
21400 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69           6.#defi
21410 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
21420 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20  ATTACHED        
21430 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66            7.#def
21440 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
21450 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
21460 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65  NGTH       8.#de
21470 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
21480 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
21490 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64  R           9.#d
214a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
214b0 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  IT_TRIGGER_DEPTH
214c0 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 0a              10..
214d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
214e0 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c  Compiling An SQL
214f0 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45   Statement.** KE
21500 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61  YWORDS: {SQL sta
21510 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d  tement compiler}
21520 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74  .**.** To execut
21530 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20  e an SQL query, 
21540 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65  it must first be
21550 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61   compiled into a
21560 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72   byte-code.** pr
21570 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20  ogram using one 
21580 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
21590 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  s..**.** The fir
215a0 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62  st argument, "db
215b0 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73  ", is a [databas
215c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62  e connection] ob
215d0 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a  tained from a.**
215e0 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75   prior successfu
215f0 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
21600 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
21610 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
21620 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  or.** [sqlite3_o
21630 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64  pen16()].  The d
21640 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
21650 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65  on must not have
21660 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a   been closed..**
21670 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
21680 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c  rgument, "zSql",
21690 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   is the statemen
216a0 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64  t to be compiled
216b0 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20  , encoded.** as 
216c0 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20  either UTF-8 or 
216d0 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c  UTF-16.  The sql
216e0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61  ite3_prepare() a
216f0 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
21700 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72  re_v2().** inter
21710 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c  faces use UTF-8,
21720 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
21730 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c  pare16() and sql
21740 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
21750 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31  2().** use UTF-1
21760 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  6..**.** ^If the
21770 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20   nByte argument 
21780 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72  is less than zer
21790 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20  o, then zSql is 
217a0 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a  read up to the.*
217b0 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  * first zero ter
217c0 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79  minator. ^If nBy
217d0 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  te is non-negati
217e0 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74  ve, then it is t
217f0 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75  he maximum.** nu
21800 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73 20 72  mber of  bytes r
21810 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20  ead from zSql.  
21820 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e  ^When nByte is n
21830 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
21840 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20  .** zSql string 
21850 65 6e 64 73 20 61 74 20 65 69 74 68 65 72 20 74  ends at either t
21860 68 65 20 66 69 72 73 74 20 27 5c 30 30 30 27 20  he first '\000' 
21870 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68 61 72  or '\u0000' char
21880 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20  acter or.** the 
21890 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77  nByte-th byte, w
218a0 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66  hichever comes f
218b0 69 72 73 74 2e 20 49 66 20 74 68 65 20 63 61 6c  irst. If the cal
218c0 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61  ler knows.** tha
218d0 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 73  t the supplied s
218e0 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72  tring is nul-ter
218f0 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74 68  minated, then th
21900 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a  ere is a small.*
21910 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64  * performance ad
21920 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20 67 61  vantage to be ga
21930 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e 67 20  ined by passing 
21940 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74  an nByte paramet
21950 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 65 71  er that.** is eq
21960 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62 65  ual to the numbe
21970 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
21980 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c  e input string <
21990 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a  i>including</i>.
219a0 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69  ** the nul-termi
219b0 6e 61 74 6f 72 20 62 79 74 65 73 20 61 73 20 74  nator bytes as t
219c0 68 69 73 20 73 61 76 65 73 20 53 51 4c 69 74 65  his saves SQLite
219d0 20 66 72 6f 6d 20 68 61 76 69 6e 67 20 74 6f 0a   from having to.
219e0 2a 2a 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f  ** make a copy o
219f0 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  f the input stri
21a00 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a  ng..**.** ^If pz
21a10 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  Tail is not NULL
21a20 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73   then *pzTail is
21a30 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
21a40 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 74 65  o the first byte
21a50 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64  .** past the end
21a60 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 53 51   of the first SQ
21a70 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a  L statement in z
21a80 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74  Sql.  These rout
21a90 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d  ines only.** com
21aa0 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 20 73  pile the first s
21ab0 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c  tatement in zSql
21ac0 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20  , so *pzTail is 
21ad0 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f  left pointing to
21ae0 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73  .** what remains
21af0 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a   uncompiled..**.
21b00 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c  ** ^*ppStmt is l
21b10 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20  eft pointing to 
21b20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70  a compiled [prep
21b30 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
21b40 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65  that can be.** e
21b50 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73  xecuted using [s
21b60 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20  qlite3_step()]. 
21b70 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 61 6e   ^If there is an
21b80 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20   error, *ppStmt 
21b90 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c  is set.** to NUL
21ba0 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75  L.  ^If the inpu
21bb0 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20  t text contains 
21bc0 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20 69  no SQL (if the i
21bd0 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79  nput is an empty
21be0 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20  .** string or a 
21bf0 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70  comment) then *p
21c00 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20  pStmt is set to 
21c10 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c  NULL..** The cal
21c20 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69  ling procedure i
21c30 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
21c40 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63  r deleting the c
21c50 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73  ompiled.** SQL s
21c60 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b  tatement using [
21c70 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
21c80 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73  ()] after it has
21c90 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
21ca0 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79  t..** ppStmt may
21cb0 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a   not be NULL..**
21cc0 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c  .** ^On success,
21cd0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   the sqlite3_pre
21ce0 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66  pare() family of
21cf0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
21d00 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a   [SQLITE_OK];.**
21d10 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65   otherwise an [e
21d20 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
21d30 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  turned..**.** Th
21d40 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
21d50 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74  e_v2() and sqlit
21d60 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
21d70 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  ) interfaces are
21d80 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20  .** recommended 
21d90 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67  for all new prog
21da0 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c  rams. The two ol
21db0 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 61  der interfaces a
21dc0 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66  re retained.** f
21dd0 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  or backwards com
21de0 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20  patibility, but 
21df0 74 68 65 69 72 20 75 73 65 20 69 73 20 64 69 73  their use is dis
21e00 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e  couraged..** ^In
21e10 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
21e20 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 61 72  aces, the prepar
21e30 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ed statement.** 
21e40 74 68 61 74 20 69 73 20 72 65 74 75 72 6e 65 64  that is returned
21e50 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73   (the [sqlite3_s
21e60 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e  tmt] object) con
21e70 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20  tains a copy of 
21e80 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20  the.** original 
21e90 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63  SQL text. This c
21ea0 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74  auses the [sqlit
21eb0 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72  e3_step()] inter
21ec0 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76  face to.** behav
21ed0 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e  e differently in
21ee0 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a   three ways:.**.
21ef0 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a  ** <ol>.** <li>.
21f00 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62  ** ^If the datab
21f10 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67  ase schema chang
21f20 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72  es, instead of r
21f30 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45  eturning [SQLITE
21f40 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a  _SCHEMA] as it.*
21f50 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f  * always used to
21f60 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74   do, [sqlite3_st
21f70 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d  ep()] will autom
21f80 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69  atically recompi
21f90 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74  le the SQL.** st
21fa0 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20  atement and try 
21fb0 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e  to run it again.
21fc0 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20  .** </li>.**.** 
21fd0 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e  <li>.** ^When an
21fe0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b   error occurs, [
21ff0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
22000 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20  will return one 
22010 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a  of the detailed.
22020 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ** [error codes]
22030 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72   or [extended er
22040 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68  ror codes].  ^Th
22050 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f  e legacy behavio
22060 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73  r was that.** [s
22070 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
22080 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e  ould only return
22090 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49   a generic [SQLI
220a0 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74  TE_ERROR] result
220b0 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65   code.** and the
220c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75   application wou
220d0 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20  ld have to make 
220e0 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f  a second call to
220f0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
22100 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74  )].** in order t
22110 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72  o find the under
22120 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74  lying cause of t
22130 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68  he problem. With
22140 20 74 68 65 20 22 76 32 22 20 70 72 65 70 61 72   the "v2" prepar
22150 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c  e.** interfaces,
22160 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
22170 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65  reason for the e
22180 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
22190 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a   immediately..**
221a0 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   </li>.**.** <li
221b0 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65  >.** ^If the spe
221c0 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e  cific value boun
221d0 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20  d to [parameter 
221e0 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  | host parameter
221f0 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45  ] in the .** WHE
22200 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20  RE clause might 
22210 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68  influence the ch
22220 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c  oice of query pl
22230 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65  an for a stateme
22240 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  nt,.** then the 
22250 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62  statement will b
22260 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
22270 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69  recompiled, as i
22280 66 20 74 68 65 72 65 20 68 61 64 20 62 65 65 6e  f there had been
22290 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68   .** a schema ch
222a0 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72  ange, on the fir
222b0 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  st  [sqlite3_ste
222c0 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77  p()] call follow
222d0 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a  ing any change.*
222e0 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  * to the [sqlite
222f0 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69  3_bind_text | bi
22300 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20  ndings] of that 
22310 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a  [parameter]. .**
22320 20 5e 54 68 65 20 73 70 65 63 69 66 69 63 20 76   ^The specific v
22330 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c  alue of WHERE-cl
22340 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d  ause [parameter]
22350 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65   might influence
22360 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20   the .** choice 
22370 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66  of query plan if
22380 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
22390 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20  s the left-hand 
223a0 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d  side of a [LIKE]
223b0 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70  .** or [GLOB] op
223c0 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65  erator or if the
223d0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f   parameter is co
223e0 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64  mpared to an ind
223f0 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61  exed column.** a
22400 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45  nd the [SQLITE_E
22410 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d  NABLE_STAT3] com
22420 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
22430 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20   is enabled..** 
22440 74 68 65 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  the .** </li>.**
22450 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71   </ol>.*/.int sq
22460 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20  lite3_prepare(. 
22470 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
22480 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
22490 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
224a0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
224b0 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
224c0 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38  statement, UTF-8
224d0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
224e0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
224f0 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
22500 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
22510 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
22520 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
22530 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
22540 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
22550 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
22560 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
22570 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
22580 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
22590 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
225a0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
225b0 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
225c0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
225d0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
225e0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
225f0 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
22600 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
22610 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
22620 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
22630 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
22640 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
22650 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
22660 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
22670 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
22680 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
22690 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
226a0 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20   char **pzTail  
226b0 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
226c0 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
226d0 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
226e0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
226f0 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69  repare16(.  sqli
22700 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
22710 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
22720 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
22730 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20  t void *zSql,   
22740 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
22750 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63  ment, UTF-16 enc
22760 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
22770 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
22780 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
22790 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
227a0 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
227b0 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
227c0 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
227d0 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
227e0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a   const void **pz
227f0 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
22800 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
22810 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
22820 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
22830 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
22840 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
22850 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
22860 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
22870 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
22880 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
22890 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
228a0 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
228b0 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
228c0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
228d0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
228e0 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
228f0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
22900 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
22910 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
22920 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
22930 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
22940 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
22950 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
22960 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
22970 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
22980 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74  F: Retrieving St
22990 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a  atement SQL.**.*
229a0 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63  * ^This interfac
229b0 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
229c0 20 72 65 74 72 69 65 76 65 20 61 20 73 61 76 65   retrieve a save
229d0 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6f 72  d copy of the or
229e0 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65  iginal.** SQL te
229f0 78 74 20 75 73 65 64 20 74 6f 20 63 72 65 61 74  xt used to creat
22a00 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  e a [prepared st
22a10 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68 61 74  atement] if that
22a20 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a   statement was.*
22a30 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67  * compiled using
22a40 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33   either [sqlite3
22a50 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
22a60 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
22a70 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 63  re16_v2()]..*/.c
22a80 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
22a90 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73  e3_sql(sqlite3_s
22aa0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
22ab0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
22ac0 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51  termine If An SQ
22ad0 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72 69 74  L Statement Writ
22ae0 65 73 20 54 68 65 20 44 61 74 61 62 61 73 65 0a  es The Database.
22af0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
22b00 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
22b10 28 58 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (X) interface re
22b20 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d  turns true (non-
22b30 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20  zero) if.** and 
22b40 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65  only if the [pre
22b50 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
22b60 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65   X makes no dire
22b70 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a  ct changes to.**
22b80 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
22b90 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
22ba0 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  e..**.** Note th
22bb0 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  at [application-
22bc0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
22bd0 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69  tions] or.** [vi
22be0 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69  rtual tables] mi
22bf0 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 20 64  ght change the d
22c00 61 74 61 62 61 73 65 20 69 6e 64 69 72 65 63 74  atabase indirect
22c10 6c 79 20 61 73 20 61 20 73 69 64 65 20 65 66 66  ly as a side eff
22c20 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20  ect.  .** ^(For 
22c30 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61  example, if an a
22c40 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
22c50 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65  es a function "e
22c60 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20  val()" that .** 
22c70 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65  calls [sqlite3_e
22c80 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65  xec()], then the
22c90 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73   following SQL s
22ca0 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a  tatement would.*
22cb0 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74  * change the dat
22cc0 61 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75  abase file throu
22cd0 67 68 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a  gh side-effects:
22ce0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
22cf0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53  te><pre>.**    S
22d00 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45  ELECT eval('DELE
22d10 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f  TE FROM t1') FRO
22d20 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  M t2;.** </pre><
22d30 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
22d40 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65 20 74  ** But because t
22d50 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  he [SELECT] stat
22d60 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63  ement does not c
22d70 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61  hange the databa
22d80 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63  se file.** direc
22d90 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d  tly, sqlite3_stm
22da0 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75  t_readonly() wou
22db0 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20  ld still return 
22dc0 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  true.)^.**.** ^T
22dd0 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72  ransaction contr
22de0 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75  ol statements su
22df0 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b  ch as [BEGIN], [
22e00 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41  COMMIT], [ROLLBA
22e10 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49  CK],.** [SAVEPOI
22e20 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53  NT], and [RELEAS
22e30 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65 33  E] cause sqlite3
22e40 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29  _stmt_readonly()
22e50 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c   to return true,
22e60 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74  .** since the st
22e70 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c  atements themsel
22e80 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61  ves do not actua
22e90 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64  lly modify the d
22ea0 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72  atabase but.** r
22eb0 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72  ather they contr
22ec0 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66  ol the timing of
22ed0 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74   when other stat
22ee0 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68  ements modify th
22ef0 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20  e .** database. 
22f00 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61   ^The [ATTACH] a
22f10 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74  nd [DETACH] stat
22f20 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73  ements also caus
22f30 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d  e.** sqlite3_stm
22f40 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20  t_readonly() to 
22f50 72 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63  return true sinc
22f60 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73  e, while those s
22f70 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61  tatements.** cha
22f80 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72  nge the configur
22f90 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62  ation of a datab
22fa0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20  ase connection, 
22fb0 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65  they do not make
22fc0 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20   .** changes to 
22fd0 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
22fe0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
22ff0 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 69 6e  s on disk..*/.in
23000 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  t sqlite3_stmt_r
23010 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f  eadonly(sqlite3_
23020 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
23030 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
23040 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64  ynamically Typed
23050 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a   Value Object.**
23060 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74   KEYWORDS: {prot
23070 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
23080 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65  lue} {unprotecte
23090 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d  d sqlite3_value}
230a0 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73  .**.** SQLite us
230b0 65 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  es the sqlite3_v
230c0 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72  alue object to r
230d0 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c  epresent all val
230e0 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20  ues.** that can 
230f0 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64  be stored in a d
23100 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53  atabase table. S
23110 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d  QLite uses dynam
23120 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72  ic typing.** for
23130 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 20 73   the values it s
23140 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20  tores.  ^Values 
23150 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65  stored in sqlite
23160 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a  3_value objects.
23170 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65  ** can be intege
23180 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  rs, floating poi
23190 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e  nt values, strin
231a0 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55  gs, BLOBs, or NU
231b0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c  LL..**.** An sql
231c0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
231d0 74 20 6d 61 79 20 62 65 20 65 69 74 68 65 72 20  t may be either 
231e0 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22  "protected" or "
231f0 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a  unprotected"..**
23200 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73   Some interfaces
23210 20 72 65 71 75 69 72 65 20 61 20 70 72 6f 74 65   require a prote
23220 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
23230 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72  ue.  Other inter
23240 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63  faces.** will ac
23250 63 65 70 74 20 65 69 74 68 65 72 20 61 20 70 72  cept either a pr
23260 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e  otected or an un
23270 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
23280 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72  3_value..** Ever
23290 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  y interface that
232a0 20 61 63 63 65 70 74 73 20 73 71 6c 69 74 65 33   accepts sqlite3
232b0 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73  _value arguments
232c0 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68   specifies.** wh
232d0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20  ether or not it 
232e0 72 65 71 75 69 72 65 73 20 61 20 70 72 6f 74 65  requires a prote
232f0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
23300 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65  ue..**.** The te
23310 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22 20  rms "protected" 
23320 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64  and "unprotected
23330 22 20 72 65 66 65 72 20 74 6f 20 77 68 65 74 68  " refer to wheth
23340 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d  er or not.** a m
23350 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41  utex is held.  A
23360 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78  n internal mutex
23370 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70   is held for a p
23380 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
23390 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
233a0 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73   but no mutex is
233b0 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70   held for an unp
233c0 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
233d0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
233e0 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20  .  If SQLite is 
233f0 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73  compiled to be s
23400 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a  ingle-threaded.*
23410 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  * (with [SQLITE_
23420 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e  THREADSAFE=0] an
23430 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f  d with [sqlite3_
23440 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 72 65  threadsafe()] re
23450 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72  turning 0).** or
23460 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 72 75   if SQLite is ru
23470 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75  n in one of redu
23480 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20  ced mutex modes 
23490 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
234a0 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d  IG_SINGLETHREAD]
234b0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   or [SQLITE_CONF
234c0 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a  IG_MULTITHREAD].
234d0 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69 73  ** then there is
234e0 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20   no distinction 
234f0 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65  between protecte
23500 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65  d and unprotecte
23510 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
23520 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74  ue objects and t
23530 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 64 20  hey can be used 
23540 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e  interchangeably.
23550 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f    However,.** fo
23560 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70  r maximum code p
23570 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 69 73  ortability it is
23580 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61   recommended tha
23590 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  t applications.*
235a0 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65  * still make the
235b0 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74   distinction bet
235c0 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61  ween protected a
235d0 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  nd unprotected.*
235e0 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
235f0 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65  objects even whe
23600 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72  n not strictly r
23610 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  equired..**.** ^
23620 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
23630 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61  e objects that a
23640 72 65 20 70 61 73 73 65 64 20 61 73 20 70 61 72  re passed as par
23650 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65  ameters into the
23660 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
23670 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69  on of [applicati
23680 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
23690 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72  unctions] are pr
236a0 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65  otected..** ^The
236b0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
236c0 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
236d0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
236e0 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
236f0 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a   unprotected..**
23700 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   Unprotected sql
23710 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
23720 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75  ts may only be u
23730 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c  sed with.** [sql
23740 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
23750 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
23760 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e  3_bind_value()].
23770 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
23780 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71  _value_blob | sq
23790 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65  lite3_value_type
237a0 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a  ()] family of.**
237b0 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75   interfaces requ
237c0 69 72 65 20 70 72 6f 74 65 63 74 65 64 20 73 71  ire protected sq
237d0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
237e0 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  cts..*/.typedef 
237f0 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74  struct Mem sqlit
23800 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a  e3_value;../*.**
23810 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46   CAPI3REF: SQL F
23820 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20  unction Context 
23830 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65  Object.**.** The
23840 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63   context in whic
23850 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f  h an SQL functio
23860 6e 20 65 78 65 63 75 74 65 73 20 69 73 20 73 74  n executes is st
23870 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71  ored in an.** sq
23880 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62  lite3_context ob
23890 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65  ject.  ^A pointe
238a0 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f  r to an sqlite3_
238b0 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a  context object.*
238c0 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69 72 73  * is always firs
238d0 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  t parameter to [
238e0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
238f0 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
23900 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  s]..** The appli
23910 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
23920 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  QL function impl
23930 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20  ementation will 
23940 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69  pass this.** poi
23950 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74  nter through int
23960 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  o calls to [sqli
23970 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c  te3_result_int |
23980 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28   sqlite3_result(
23990 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
239a0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
239b0 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75  t()], [sqlite3_u
239c0 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20  ser_data()],.** 
239d0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
239e0 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b  _db_handle()], [
239f0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
23a00 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f  ata()],.** and/o
23a10 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  r [sqlite3_set_a
23a20 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79  uxdata()]..*/.ty
23a30 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
23a40 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c  ite3_context sql
23a50 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f  ite3_context;../
23a60 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42  *.** CAPI3REF: B
23a70 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f  inding Values To
23a80 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
23a90 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ents.** KEYWORDS
23aa0 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  : {host paramete
23ab0 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  r} {host paramet
23ac0 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d  ers} {host param
23ad0 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45  eter name}.** KE
23ae0 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72  YWORDS: {SQL par
23af0 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72  ameter} {SQL par
23b00 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65  ameters} {parame
23b10 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a  ter binding}.**.
23b20 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20  ** ^(In the SQL 
23b30 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69  statement text i
23b40 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  nput to [sqlite3
23b50 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
23b60 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c  nd its variants,
23b70 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79  .** literals may
23b80 20 62 65 20 72 65 70 6c 61 63 65 64 20 62 79 20   be replaced by 
23b90 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68  a [parameter] th
23ba0 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f  at matches one o
23bb0 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74  f following.** t
23bc0 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20  emplates:.**.** 
23bd0 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a  <ul>.** <li>  ?.
23be0 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a  ** <li>  ?NNN.**
23bf0 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c   <li>  :VVV.** <
23c00 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69  li>  @VVV.** <li
23c10 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e  >  $VVV.** </ul>
23c20 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65  .**.** In the te
23c30 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e  mplates above, N
23c40 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  NN represents an
23c50 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c   integer literal
23c60 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70  ,.** and VVV rep
23c70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61  resents an alpha
23c80 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69  numeric identifi
23c90 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75  er.)^  ^The valu
23ca0 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70  es of these.** p
23cb0 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20  arameters (also 
23cc0 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72  called "host par
23cd0 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72  ameter names" or
23ce0 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   "SQL parameters
23cf0 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74  ").** can be set
23d00 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
23d10 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
23d20 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65 72  ines defined her
23d30 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  e..**.** ^The fi
23d40 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
23d50 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
23d60 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73  _*() routines is
23d70 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69   always.** a poi
23d80 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  nter to the [sql
23d90 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63  ite3_stmt] objec
23da0 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a  t returned from.
23db0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
23dc0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73  are_v2()] or its
23dd0 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a   variants..**.**
23de0 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67   ^The second arg
23df0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64  ument is the ind
23e00 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61  ex of the SQL pa
23e10 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65  rameter to be se
23e20 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d  t..** ^The leftm
23e30 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65  ost SQL paramete
23e40 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f  r has an index o
23e50 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20  f 1.  ^When the 
23e60 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51  same named.** SQ
23e70 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75  L parameter is u
23e80 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  sed more than on
23e90 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73  ce, second and s
23ea0 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63  ubsequent.** occ
23eb0 75 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 68  urrences have th
23ec0 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20  e same index as 
23ed0 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72  the first occurr
23ee0 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e  ence..** ^The in
23ef0 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61  dex for named pa
23f00 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20  rameters can be 
23f10 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20  looked up using 
23f20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
23f30 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
23f40 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66 20 64  ndex()] API if d
23f50 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e  esired.  ^The in
23f60 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e  dex.** for "?NNN
23f70 22 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20  " parameters is 
23f80 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e  the value of NNN
23f90 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61  ..** ^The NNN va
23fa0 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 77  lue must be betw
23fb0 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73  een 1 and the [s
23fc0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a  qlite3_limit()].
23fd0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51  ** parameter [SQ
23fe0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
23ff0 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66  BLE_NUMBER] (def
24000 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29  ault value: 999)
24010 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69  ..**.** ^The thi
24020 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  rd argument is t
24030 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64  he value to bind
24040 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65   to the paramete
24050 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68  r..**.** ^(In th
24060 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ose routines tha
24070 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 20  t have a fourth 
24080 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61  argument, its va
24090 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75  lue is the.** nu
240a0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
240b0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20   the parameter. 
240c0 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68   To be clear: th
240d0 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a  e value is the.*
240e0 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62  * number of <u>b
240f0 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20  ytes</u> in the 
24100 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e  value, not the n
24110 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
24120 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68  ers.)^.** ^If th
24130 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
24140 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  er is negative, 
24150 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  the length of th
24160 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74  e string is.** t
24170 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
24180 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72  es up to the fir
24190 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
241a0 6f 72 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d  or..** If a non-
241b0 6e 65 67 61 74 69 76 65 20 66 6f 75 72 74 68 20  negative fourth 
241c0 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 6f  parameter is pro
241d0 76 69 64 65 64 20 74 6f 20 73 71 6c 69 74 65 33  vided to sqlite3
241e0 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20  _bind_text().** 
241f0 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
24200 74 65 78 74 31 36 28 29 20 74 68 65 6e 20 74 68  text16() then th
24210 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73  at parameter mus
24220 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66  t be the byte of
24230 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68  fset.** where th
24240 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72  e NUL terminator
24250 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73   would occur ass
24260 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67  uming the string
24270 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72   were NUL.** ter
24280 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79  minated.  If any
24290 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 20   NUL characters 
242a0 6f 63 63 75 72 20 61 74 20 62 79 74 65 20 6f 66  occur at byte of
242b0 66 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20  fsets less than 
242c0 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66  .** the value of
242d0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
242e0 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65 20 72  meter then the r
242f0 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20  esulting string 
24300 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f  value will.** co
24310 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e  ntain embedded N
24320 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74  ULs.  The result
24330 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20   of expressions 
24340 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67  involving string
24350 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64  s.** with embedd
24360 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66  ed NULs is undef
24370 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ined..**.** ^The
24380 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
24390 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
243a0 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f  blob(), sqlite3_
243b0 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e 64  bind_text(), and
243c0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  .** sqlite3_bind
243d0 5f 74 65 78 74 31 36 28 29 20 69 73 20 61 20 64  _text16() is a d
243e0 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 74  estructor used t
243f0 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65  o dispose of the
24400 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69   BLOB or.** stri
24410 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 20  ng after SQLite 
24420 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
24430 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73 74  h it.  ^The dest
24440 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64  ructor is called
24450 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 6f  .** to dispose o
24460 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74  f the BLOB or st
24470 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65  ring even if the
24480 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
24490 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 0a 2a 2a  _bind_blob(),.**
244a0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
244b0 78 74 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33  xt(), or sqlite3
244c0 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 66  _bind_text16() f
244d0 61 69 6c 73 2e 20 20 0a 2a 2a 20 5e 49 66 20 74  ails.  .** ^If t
244e0 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
244f0 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63  t is.** the spec
24500 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54  ial value [SQLIT
24510 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20  E_STATIC], then 
24520 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74  SQLite assumes t
24530 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72  hat the.** infor
24540 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61  mation is in sta
24550 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73  tic, unmanaged s
24560 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f  pace and does no
24570 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65  t need to be fre
24580 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  ed..** ^If the f
24590 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61  ifth argument ha
245a0 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c  s the value [SQL
245b0 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20  ITE_TRANSIENT], 
245c0 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  then.** SQLite m
245d0 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69  akes its own pri
245e0 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65  vate copy of the
245f0 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c   data immediatel
24600 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65  y, before.** the
24610 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
24620 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
24630 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
24640 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
24650 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69  lob() routine bi
24660 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65  nds a BLOB of le
24670 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69  ngth N that.** i
24680 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65  s filled with ze
24690 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c  roes.  ^A zerobl
246a0 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20  ob uses a fixed 
246b0 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79  amount of memory
246c0 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74  .** (just an int
246d0 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73  eger to hold its
246e0 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20   size) while it 
246f0 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73  is being process
24700 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73  ed..** Zeroblobs
24710 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f   are intended to
24720 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 68   serve as placeh
24730 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73  olders for BLOBs
24740 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e   whose.** conten
24750 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74  t is later writt
24760 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  en using.** [sql
24770 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c  ite3_blob_open |
24780 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f   incremental BLO
24790 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e  B I/O] routines.
247a0 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20  .** ^A negative 
247b0 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65  value for the ze
247c0 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69  roblob results i
247d0 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  n a zero-length 
247e0 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  BLOB..**.** ^If 
247f0 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74  any of the sqlit
24800 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
24810 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
24820 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
24830 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b  ter.** for the [
24840 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
24850 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72  nt] or with a pr
24860 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
24870 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73   for which.** [s
24880 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
24890 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d  as been called m
248a0 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61  ore recently tha
248b0 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
248c0 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ()],.** then the
248d0 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72   call will retur
248e0 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  n [SQLITE_MISUSE
248f0 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74  ].  If any sqlit
24900 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f  e3_bind_().** ro
24910 75 74 69 6e 65 20 69 73 20 70 61 73 73 65 64 20  utine is passed 
24920 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
24930 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20  ement] that has 
24940 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20  been finalized, 
24950 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73  the.** result is
24960 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
24970 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e  robably harmful.
24980 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73  .**.** ^Bindings
24990 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64   are not cleared
249a0 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
249b0 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e  _reset()] routin
249c0 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70  e..** ^Unbound p
249d0 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e  arameters are in
249e0 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c  terpreted as NUL
249f0 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  L..**.** ^The sq
24a00 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75  lite3_bind_* rou
24a10 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51  tines return [SQ
24a20 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
24a30 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72  ess or an.** [er
24a40 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79  ror code] if any
24a50 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67  thing goes wrong
24a60 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41  ..** ^[SQLITE_RA
24a70 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64  NGE] is returned
24a80 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
24a90 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75  r.** index is ou
24aa0 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53  t of range.  ^[S
24ab0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20  QLITE_NOMEM] is 
24ac0 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c  returned if mall
24ad0 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a  oc() fails..**.*
24ae0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
24af0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
24b00 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a  ter_count()],.**
24b10 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
24b20 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
24b30 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  , and [sqlite3_b
24b40 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
24b50 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  dex()]..*/.int s
24b60 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
24b70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
24b80 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
24b90 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29  , int n, void(*)
24ba0 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
24bb0 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c  lite3_bind_doubl
24bc0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
24bd0 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69   int, double);.i
24be0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
24bf0 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  int(sqlite3_stmt
24c00 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e  *, int, int);.in
24c10 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69  t sqlite3_bind_i
24c20 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  nt64(sqlite3_stm
24c30 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33  t*, int, sqlite3
24c40 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c  _int64);.int sql
24c50 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73  ite3_bind_null(s
24c60 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
24c70 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  t);.int sqlite3_
24c80 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65  bind_text(sqlite
24c90 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
24ca0 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e  nst char*, int n
24cb0 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
24cc0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
24cd0 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74  ind_text16(sqlit
24ce0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
24cf0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
24d00 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
24d10 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
24d20 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  nd_value(sqlite3
24d30 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
24d40 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  st sqlite3_value
24d50 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
24d60 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71  bind_zeroblob(sq
24d70 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
24d80 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int n);../*.**
24d90 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
24da0 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74  r Of SQL Paramet
24db0 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ers.**.** ^This 
24dc0 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75  routine can be u
24dd0 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20  sed to find the 
24de0 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70  number of [SQL p
24df0 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e  arameters].** in
24e00 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
24e10 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61  tement].  SQL pa
24e20 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b  rameters are tok
24e30 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f  ens of the.** fo
24e40 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20  rm "?", "?NNN", 
24e50 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20  ":AAA", "$AAA", 
24e60 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20 73  or "@AAA" that s
24e70 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65  erve as.** place
24e80 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75  holders for valu
24e90 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c  es that are [sql
24ea0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
24eb0 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68   bound].** to th
24ec0 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 20  e parameters at 
24ed0 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a  a later time..**
24ee0 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69  .** ^(This routi
24ef0 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75  ne actually retu
24f00 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66  rns the index of
24f10 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 72 69   the largest (ri
24f20 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61  ghtmost).** para
24f30 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66  meter. For all f
24f40 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e  orms except ?NNN
24f50 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72  , this will corr
24f60 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a  espond to the.**
24f70 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75   number of uniqu
24f80 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49  e parameters.  I
24f90 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20  f parameters of 
24fa0 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72  the ?NNN form ar
24fb0 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65  e used,.** there
24fc0 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e 20   may be gaps in 
24fd0 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a  the list.)^.**.*
24fe0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
24ff0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
25000 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
25010 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
25020 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
25030 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
25040 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
25050 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
25060 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
25070 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
25080 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
25090 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
250a0 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74  : Name Of A Host
250b0 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a   Parameter.**.**
250c0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
250d0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
250e0 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65  e(P,N) interface
250f0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
25100 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68  name of the N-th
25110 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d   [SQL parameter]
25120 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65   in the [prepare
25130 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a  d statement] P..
25140 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74  ** ^(SQL paramet
25150 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
25160 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22  "?NNN" or ":AAA"
25170 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24   or "@AAA" or "$
25180 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e  AAA".** have a n
25190 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 65  ame which is the
251a0 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f   string "?NNN" o
251b0 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41  r ":AAA" or "@AA
251c0 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20  A" or "$AAA".** 
251d0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
251e0 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
251f0 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22   the initial ":"
25200 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f   or "$" or "@" o
25210 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c  r "?".** is incl
25220 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  uded as part of 
25230 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e  the name.)^.** ^
25240 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  Parameters of th
25250 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f  e form "?" witho
25260 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69  ut a following i
25270 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e  nteger have no n
25280 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72  ame.** and are r
25290 65 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e  eferred to as "n
252a0 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f  ameless" or "ano
252b0 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72  nymous parameter
252c0 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  s"..**.** ^The f
252d0 69 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65  irst host parame
252e0 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
252f0 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a   of 1, not 0..**
25300 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75  .** ^If the valu
25310 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61  e N is out of ra
25320 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d  nge or if the N-
25330 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a  th parameter is.
25340 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65  ** nameless, the
25350 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e  n NULL is return
25360 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e  ed.  ^The return
25370 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20  ed string is.** 
25380 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20  always in UTF-8 
25390 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66  encoding even if
253a0 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d   the named param
253b0 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67  eter was.** orig
253c0 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64  inally specified
253d0 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73   as UTF-16 in [s
253e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
253f0 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
25400 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
25410 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  )]..**.** See al
25420 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
25430 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
25440 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
25450 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
25460 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64  er_count()], and
25470 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
25480 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
25490 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  x()]..*/.const c
254a0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e  har *sqlite3_bin
254b0 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
254c0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
254d0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
254e0 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20  I3REF: Index Of 
254f0 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 68  A Parameter With
25500 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a   A Given Name.**
25510 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20  .** ^Return the 
25520 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20  index of an SQL 
25530 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20  parameter given 
25540 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a  its name.  ^The.
25550 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72  ** index value r
25560 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 61  eturned is suita
25570 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 74  ble for use as t
25580 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72  he second.** par
25590 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
255a0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
255b0 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e  ite3_bind()].  ^
255c0 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74  A zero.** is ret
255d0 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63  urned if no matc
255e0 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69  hing parameter i
255f0 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70  s found.  ^The p
25600 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65  arameter.** name
25610 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 69   must be given i
25620 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20  n UTF-8 even if 
25630 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61  the original sta
25640 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72  tement.** was pr
25650 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d  epared from UTF-
25660 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73  16 text using [s
25670 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
25680 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65  _v2()]..**.** Se
25690 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
256a0 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
256b0 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
256c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
256d0 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
256e0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
256f0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
25700 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  index()]..*/.int
25710 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
25720 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71  rameter_index(sq
25730 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e  lite3_stmt*, con
25740 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
25750 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
25760 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64  : Reset All Bind
25770 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72  ings On A Prepar
25780 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a  ed Statement.**.
25790 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20  ** ^Contrary to 
257a0 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66  the intuition of
257b0 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f   many, [sqlite3_
257c0 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f  reset()] does no
257d0 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b  t reset.** the [
257e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
257f0 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  b | bindings] on
25800 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
25810 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65  tement]..** ^Use
25820 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f   this routine to
25830 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20   reset all host 
25840 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55  parameters to NU
25850 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  LL..*/.int sqlit
25860 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
25870 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  s(sqlite3_stmt*)
25880 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
25890 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c  F: Number Of Col
258a0 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74  umns In A Result
258b0 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75   Set.**.** ^Retu
258c0 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  rn the number of
258d0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
258e0 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72  result set retur
258f0 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70  ned by the.** [p
25900 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
25910 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  t]. ^This routin
25920 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 70  e returns 0 if p
25930 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a  Stmt is an SQL.*
25940 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  * statement that
25950 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e   does not return
25960 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70   data (for examp
25970 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e  le an [UPDATE]).
25980 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
25990 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63   [sqlite3_data_c
259a0 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73  ount()].*/.int s
259b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
259c0 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
259d0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
259e0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d   CAPI3REF: Colum
259f0 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73  n Names In A Res
25a00 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 54  ult Set.**.** ^T
25a10 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
25a20 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73  turn the name as
25a30 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74  signed to a part
25a40 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a  icular column.**
25a50 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73   in the result s
25a60 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d  et of a [SELECT]
25a70 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68   statement.  ^Th
25a80 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
25a90 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72  _name().** inter
25aa0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
25ab0 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f  ointer to a zero
25ac0 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
25ad0 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20  8 string.** and 
25ae0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
25af0 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73 20  ame16() returns 
25b00 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a  a pointer to a z
25b10 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
25b20 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e  * UTF-16 string.
25b30 20 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72    ^The first par
25b40 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 70  ameter is the [p
25b50 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
25b60 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65  t].** that imple
25b70 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43  ments the [SELEC
25b80 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54  T] statement. ^T
25b90 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
25ba0 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f  ter is the.** co
25bb0 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54  lumn number.  ^T
25bc0 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75  he leftmost colu
25bd0 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a  mn is number 0..
25be0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  **.** ^The retur
25bf0 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  ned string point
25c00 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  er is valid unti
25c10 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b 70 72  l either the [pr
25c20 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
25c30 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65  ].** is destroye
25c40 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69  d by [sqlite3_fi
25c50 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74  nalize()] or unt
25c60 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  il the statement
25c70 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   is automaticall
25c80 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20  y.** reprepared 
25c90 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c  by the first cal
25ca0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
25cb0 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74  ep()] for a part
25cc0 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72  icular run.** or
25cd0 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20   until the next 
25ce0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  call to.** sqlit
25cf0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
25d00 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
25d10 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74  mn_name16() on t
25d20 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a  he same column..
25d30 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  **.** ^If sqlite
25d40 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73  3_malloc() fails
25d50 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63   during the proc
25d60 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72  essing of either
25d70 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72   routine.** (for
25d80 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20   example during 
25d90 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f  a conversion fro
25da0 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31  m UTF-8 to UTF-1
25db0 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c  6) then a.** NUL
25dc0 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
25dd0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
25de0 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75  e name of a resu
25df0 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65  lt column is the
25e00 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41   value of the "A
25e10 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a  S" clause for.**
25e20 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66   that column, if
25e30 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 20   there is an AS 
25e40 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 72  clause.  If ther
25e50 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73  e is no AS claus
25e60 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61  e.** then the na
25e70 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  me of the column
25e80 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 20   is unspecified 
25e90 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66  and may change f
25ea0 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61  rom.** one relea
25eb0 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20  se of SQLite to 
25ec0 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e  the next..*/.con
25ed0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
25ee0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c  _column_name(sql
25ef0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
25f00 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  N);.const void *
25f10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
25f20 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
25f30 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a  mt*, int N);../*
25f40 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f  .** CAPI3REF: So
25f50 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20  urce Of Data In 
25f60 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a  A Query Result.*
25f70 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
25f80 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d  ines provide a m
25f90 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e  eans to determin
25fa0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2c 20  e the database, 
25fb0 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61  table, and.** ta
25fc0 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
25fd0 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66  is the origin of
25fe0 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65   a particular re
25ff0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a  sult column in.*
26000 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  * [SELECT] state
26010 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61  ment..** ^The na
26020 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
26030 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63  se or table or c
26040 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74  olumn can be ret
26050 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68  urned as.** eith
26060 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54  er a UTF-8 or UT
26070 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54  F-16 string.  ^T
26080 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f  he _database_ ro
26090 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a  utines return.**
260a0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61   the database na
260b0 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20  me, the _table_ 
260c0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
260d0 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20  the table name, 
260e0 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69  and.** the origi
260f0 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  n_ routines retu
26100 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61  rn the column na
26110 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  me..** ^The retu
26120 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76  rned string is v
26130 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b  alid until the [
26140 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
26150 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64  nt] is destroyed
26160 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  .** using [sqlit
26170 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
26180 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74  r until the stat
26190 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74  ement is automat
261a0 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70  ically.** reprep
261b0 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73  ared by the firs
261c0 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
261d0 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61  e3_step()] for a
261e0 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a   particular run.
261f0 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  ** or until the 
26200 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  same information
26210 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a   is requested.**
26220 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66   again in a diff
26230 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a  erent encoding..
26240 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73  **.** ^The names
26250 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68   returned are th
26260 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c  e original un-al
26270 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74  iased names of t
26280 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20  he.** database, 
26290 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d  table, and colum
262a0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  n..**.** ^The fi
262b0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
262c0 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
262d0 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20   is a [prepared 
262e0 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
262f0 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
26300 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69  return informati
26310 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68  on about the Nth
26320 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72   result column r
26330 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68  eturned by.** th
26340 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65  e statement, whe
26350 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f  re N is the seco
26360 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75  nd function argu
26370 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65  ment..** ^The le
26380 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69  ft-most column i
26390 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74  s column 0 for t
263a0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  hese routines..*
263b0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68  *.** ^If the Nth
263c0 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64   column returned
263d0 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e   by the statemen
263e0 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69  t is an expressi
263f0 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72  on or.** subquer
26400 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63  y and is not a c
26410 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65  olumn value, the
26420 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66  n all of these f
26430 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a  unctions return.
26440 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65  ** NULL.  ^These
26450 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61   routine might a
26460 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20  lso return NULL 
26470 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  if a memory allo
26480 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20  cation error.** 
26490 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77  occurs.  ^Otherw
264a0 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e  ise, they return
264b0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
264c0 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
264d0 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72  se, table,.** or
264e0 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65   column that que
264f0 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  ry result column
26500 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66   was extracted f
26510 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77  rom..**.** ^As w
26520 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51  ith all other SQ
26530 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65  Lite APIs, those
26540 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64   whose names end
26550 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72   with "16" retur
26560 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f  n.** UTF-16 enco
26570 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20  ded strings and 
26580 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69  the other functi
26590 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38  ons return UTF-8
265a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41  ..**.** ^These A
265b0 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61  PIs are only ava
265c0 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69  ilable if the li
265d0 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c  brary was compil
265e0 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ed with the.** [
265f0 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f  SQLITE_ENABLE_CO
26600 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43  LUMN_METADATA] C
26610 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79  -preprocessor sy
26620 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  mbol..**.** If t
26630 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
26640 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
26650 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75  ore of these rou
26660 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68  tines against th
26670 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72  e same.** prepar
26680 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  ed statement and
26690 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73   column at the s
266a0 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68  ame time then th
266b0 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a  e results are.**
266c0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
266d0 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65  * If two or more
266e0 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e   threads call on
266f0 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71  e or more.** [sq
26700 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
26710 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c  abase_name | col
26720 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74  umn metadata int
26730 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20  erfaces].** for 
26740 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72  the same [prepar
26750 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e  ed statement] an
26760 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a  d result column.
26770 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  ** at the same t
26780 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73  ime then the res
26790 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
267a0 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  ed..*/.const cha
267b0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
267c0 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28  n_database_name(
267d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
267e0 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
267f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
26800 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73  atabase_name16(s
26810 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
26820 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
26830 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
26840 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ble_name(sqlite3
26850 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
26860 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
26870 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61  _column_table_na
26880 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
26890 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63  t*,int);.const c
268a0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
268b0 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28  umn_origin_name(
268c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
268d0 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
268e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f  sqlite3_column_o
268f0 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c  rigin_name16(sql
26900 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
26910 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
26920 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61 74  : Declared Datat
26930 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20 52  ype Of A Query R
26940 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  esult.**.** ^(Th
26950 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
26960 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64  r is a [prepared
26970 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
26980 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e  If this statemen
26990 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20  t is a [SELECT] 
269a0 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68  statement and th
269b0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
269c0 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  the.** returned 
269d0 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68  result set of th
269e0 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61  at [SELECT] is a
269f0 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e   table column (n
26a00 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73  ot an.** express
26a10 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29  ion or subquery)
26a20 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72   then the declar
26a30 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 74  ed type of the t
26a40 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69  able.** column i
26a50 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e  s returned.)^  ^
26a60 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  If the Nth colum
26a70 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  n of the result 
26a80 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70  set is an.** exp
26a90 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
26aa0 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c  ery, then a NULL
26ab0 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75   pointer is retu
26ac0 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65  rned..** ^The re
26ad0 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
26ae0 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e   always UTF-8 en
26af0 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46  coded..**.** ^(F
26b00 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65  or example, give
26b10 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73  n the database s
26b20 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45  chema:.**.** CRE
26b30 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 20  ATE TABLE t1(c1 
26b40 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20  VARIANT);.**.** 
26b50 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  and the followin
26b60 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62  g statement to b
26b70 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a  e compiled:.**.*
26b80 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c  * SELECT c1 + 1,
26b90 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a   c1 FROM t1;.**.
26ba0 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ** this routine 
26bb0 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65  would return the
26bc0 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54   string "VARIANT
26bd0 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64  " for the second
26be0 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d   result.** colum
26bf0 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20  n (i==1), and a 
26c00 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72  NULL pointer for
26c10 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75 6c   the first resul
26c20 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e  t column (i==0).
26c30 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  )^.**.** ^SQLite
26c40 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75   uses dynamic ru
26c50 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20  n-time typing.  
26c60 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65  ^So just because
26c70 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20   a column.** is 
26c80 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74  declared to cont
26c90 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72  ain a particular
26ca0 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d   type does not m
26cb0 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ean that the.** 
26cc0 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74  data stored in t
26cd0 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66  hat column is of
26ce0 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79   the declared ty
26cf0 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a  pe.  SQLite is.*
26d00 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64  * strongly typed
26d10 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e 67  , but the typing
26d20 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20   is dynamic not 
26d30 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a  static.  ^Type.*
26d40 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  * is associated 
26d50 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20  with individual 
26d60 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68  values, not with
26d70 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a   the containers.
26d80 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20  ** used to hold 
26d90 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f  those values..*/
26da0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
26db0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
26dc0 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  type(sqlite3_stm
26dd0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
26de0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
26df0 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73  umn_decltype16(s
26e00 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
26e10 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
26e20 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20  EF: Evaluate An 
26e30 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL Statement.**
26e40 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65  .** After a [pre
26e50 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
26e60 20 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 72   has been prepar
26e70 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a  ed using either.
26e80 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
26e90 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
26ea0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
26eb0 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  v2()] or one of 
26ec0 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  the legacy.** in
26ed0 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65  terfaces [sqlite
26ee0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
26ef0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
26f00 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63  16()], this func
26f10 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20  tion.** must be 
26f20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f  called one or mo
26f30 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c  re times to eval
26f40 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65  uate the stateme
26f50 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65  nt..**.** The de
26f60 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68  tails of the beh
26f70 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c  avior of the sql
26f80 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65  ite3_step() inte
26f90 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20  rface depend.** 
26fa0 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 73  on whether the s
26fb0 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65  tatement was pre
26fc0 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  pared using the 
26fd0 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74 65 72  newer "v2" inter
26fe0 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  face.** [sqlite3
26ff0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
27000 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
27010 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74  are16_v2()] or t
27020 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a  he older legacy.
27030 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71  ** interface [sq
27040 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
27050 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
27060 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65  epare16()].  The
27070 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e   use of the.** n
27080 65 77 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  ew "v2" interfac
27090 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e is recommended
270a0 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61   for new applica
270b0 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65  tions but the le
270c0 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
270d0 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20  e will continue 
270e0 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e  to be supported.
270f0 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c  .**.** ^In the l
27100 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
27110 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
27120 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72  e will be either
27130 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a   [SQLITE_BUSY],.
27140 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  ** [SQLITE_DONE]
27150 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  , [SQLITE_ROW], 
27160 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
27170 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  or [SQLITE_MISUS
27180 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65  E]..** ^With the
27190 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c   "v2" interface,
271a0 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65   any of the othe
271b0 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  r [result codes]
271c0 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   or.** [extended
271d0 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d   result codes] m
271e0 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64  ight be returned
271f0 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20   as well..**.** 
27200 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d  ^[SQLITE_BUSY] m
27210 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 61  eans that the da
27220 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61  tabase engine wa
27230 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75  s unable to acqu
27240 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  ire the.** datab
27250 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65  ase locks it nee
27260 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62  ds to do its job
27270 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61 74 65  .  ^If the state
27280 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49  ment is a [COMMI
27290 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20  T].** or occurs 
272a0 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78  outside of an ex
272b0 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
272c0 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e  on, then you can
272d0 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74   retry the.** st
272e0 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65  atement.  If the
272f0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f   statement is no
27300 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64  t a [COMMIT] and
27310 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
27320 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72  n.** explicit tr
27330 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79  ansaction then y
27340 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61  ou should rollba
27350 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  ck the transacti
27360 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e  on before.** con
27370 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e  tinuing..**.** ^
27380 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65  [SQLITE_DONE] me
27390 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61  ans that the sta
273a0 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73  tement has finis
273b0 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a  hed executing.**
273c0 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20   successfully.  
273d0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73  sqlite3_step() s
273e0 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c  hould not be cal
273f0 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69  led again on thi
27400 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63  s virtual.** mac
27410 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72  hine without fir
27420 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  st calling [sqli
27430 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20  te3_reset()] to 
27440 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61  reset the virtua
27450 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63  l.** machine bac
27460 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c  k to its initial
27470 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49   state..**.** ^I
27480 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
27490 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74  ent being execut
274a0 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64  ed returns any d
274b0 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54  ata, then [SQLIT
274c0 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74  E_ROW].** is ret
274d0 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20  urned each time 
274e0 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74  a new row of dat
274f0 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 70  a is ready for p
27500 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65  rocessing by the
27510 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20  .** caller. The 
27520 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63  values may be ac
27530 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 65  cessed using the
27540 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   [column access 
27550 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73  functions]..** s
27560 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73  qlite3_step() is
27570 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f   called again to
27580 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65   retrieve the ne
27590 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a  xt row of data..
275a0 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45  **.** ^[SQLITE_E
275b0 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74  RROR] means that
275c0 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f   a run-time erro
275d0 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e  r (such as a con
275e0 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61  straint.** viola
275f0 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72  tion) has occurr
27600 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65  ed.  sqlite3_ste
27610 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  p() should not b
27620 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f  e called again o
27630 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72  n.** the VM. Mor
27640 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61  e information ma
27650 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61  y be found by ca
27660 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65  lling [sqlite3_e
27670 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69  rrmsg()]..** ^Wi
27680 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  th the legacy in
27690 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20  terface, a more 
276a0 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63  specific error c
276b0 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  ode (for example
276c0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54  ,.** [SQLITE_INT
276d0 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45  ERRUPT], [SQLITE
276e0 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54  _SCHEMA], [SQLIT
276f0 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20  E_CORRUPT], and 
27700 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e  so forth).** can
27710 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20   be obtained by 
27720 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
27730 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65  _reset()] on the
27740 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
27750 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74  atement].  ^In t
27760 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
27770 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73  e,.** the more s
27780 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f  pecific error co
27790 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 64  de is returned d
277a0 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74  irectly by sqlit
277b0 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a  e3_step()..**.**
277c0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
277d0 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
277e0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73  this routine was
277f0 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70   called inapprop
27800 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68  riately..** Perh
27810 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65  aps it was calle
27820 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64  d on a [prepared
27830 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
27840 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20   has.** already 
27850 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  been [sqlite3_fi
27860 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a  nalize | finaliz
27870 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68  ed] or on one th
27880 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f  at had.** previo
27890 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53  usly returned [S
278a0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20  QLITE_ERROR] or 
278b0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20  [SQLITE_DONE].  
278c0 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62  Or it could.** b
278d0 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20  e the case that 
278e0 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
278f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
27900 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 77  being used by tw
27910 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72  o or.** more thr
27920 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65  eads at the same
27930 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e   moment in time.
27940 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76  .**.** For all v
27950 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
27960 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c  e up to and incl
27970 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20  uding 3.6.23.1, 
27980 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  a call to.** [sq
27990 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77  lite3_reset()] w
279a0 61 73 20 72 65 71 75 69 72 65 64 20 61 66 74 65  as required afte
279b0 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  r sqlite3_step()
279c0 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69   returned anythi
279d0 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e  ng.** other than
279e0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65   [SQLITE_ROW] be
279f0 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71 75  fore any subsequ
27a00 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ent invocation o
27a10 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  f.** sqlite3_ste
27a20 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f  p().  Failure to
27a30 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61   reset the prepa
27a40 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73  red statement us
27a50 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ing .** [sqlite3
27a60 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20  _reset()] would 
27a70 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51  result in an [SQ
27a80 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74  LITE_MISUSE] ret
27a90 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69  urn from.** sqli
27aa0 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74  te3_step().  But
27ab0 20 61 66 74 65 72 20 76 65 72 73 69 6f 6e 20 33   after version 3
27ac0 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65 33  .6.23.1, sqlite3
27ad0 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a  _step() began.**
27ae0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
27af0 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d  3_reset()] autom
27b00 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73  atically in this
27b10 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61   circumstance ra
27b20 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74  ther.** than ret
27b30 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d  urning [SQLITE_M
27b40 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73  ISUSE].  This is
27b50 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20   not considered 
27b60 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a  a compatibility.
27b70 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73 65  ** break because
27b80 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e   any application
27b90 20 74 68 61 74 20 65 76 65 72 20 72 65 63 65 69   that ever recei
27ba0 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49  ves an SQLITE_MI
27bb0 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73  SUSE error.** is
27bc0 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e   broken by defin
27bd0 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c  ition.  The [SQL
27be0 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53  ITE_OMIT_AUTORES
27bf0 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  ET] compile-time
27c00 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62   option.** can b
27c10 65 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72  e used to restor
27c20 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 68  e the legacy beh
27c30 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  avior..**.** <b>
27c40 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20  Goofy Interface 
27c50 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68  Alert:</b> In th
27c60 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
27c70 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ce, the sqlite3_
27c80 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c  step().** API al
27c90 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 67  ways returns a g
27ca0 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64  eneric error cod
27cb0 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  e, [SQLITE_ERROR
27cc0 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79  ], following any
27cd0 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20  .** error other 
27ce0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  than [SQLITE_BUS
27cf0 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d  Y] and [SQLITE_M
27d00 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73  ISUSE].  You mus
27d10 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74  t call.** [sqlit
27d20 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b  e3_reset()] or [
27d30 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
27d40 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ()] in order to 
27d50 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a  find one of the.
27d60 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72 72  ** specific [err
27d70 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62  or codes] that b
27d80 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73 20  etter describes 
27d90 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65  the error..** We
27da0 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 73   admit that this
27db0 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69   is a goofy desi
27dc0 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d  gn.  The problem
27dd0 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a   has been fixed.
27de0 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 22  ** with the "v2"
27df0 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20   interface.  If 
27e00 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20  you prepare all 
27e10 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74  of your SQL stat
27e20 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20  ements.** using 
27e30 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f  either [sqlite3_
27e40 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
27e50 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
27e60 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61  e16_v2()] instea
27e70 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61  d.** of the lega
27e80 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  cy [sqlite3_prep
27e90 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  are()] and [sqli
27ea0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
27eb0 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20   interfaces,.** 
27ec0 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70  then the more sp
27ed0 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f  ecific [error co
27ee0 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65  des] are returne
27ef0 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79  d directly.** by
27f00 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
27f10 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65    The use of the
27f20 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20   "v2" interface 
27f30 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a  is recommended..
27f40 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
27f50 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  tep(sqlite3_stmt
27f60 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
27f70 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63  REF: Number of c
27f80 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75  olumns in a resu
27f90 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  lt set.**.** ^Th
27fa0 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
27fb0 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63  ount(P) interfac
27fc0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
27fd0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
27fe0 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  in the.** curren
27ff0 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  t row of the res
28000 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70  ult set of [prep
28010 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
28020 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72  P..** ^If prepar
28030 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64  ed statement P d
28040 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73  oes not have res
28050 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72 65  ults ready to re
28060 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c  turn.** (via cal
28070 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ls to the [sqlit
28080 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20  e3_column_int | 
28090 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a  sqlite3_column_*
280a0 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66  ()] of.** interf
280b0 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74  aces) then sqlit
280c0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
280d0 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e   returns 0..** ^
280e0 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
280f0 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e  _count(P) routin
28100 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30  e also returns 0
28110 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20   if P is a NULL 
28120 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65  pointer..** ^The
28130 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
28140 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 72  unt(P) routine r
28150 65 74 75 72 6e 73 20 30 20 69 66 20 74 68 65 20  eturns 0 if the 
28160 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
28170 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
28180 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 20 5b  p](P) returned [
28190 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e  SQLITE_DONE].  ^
281a0 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
281b0 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c  _count(P).** wil
281c0 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72  l return non-zer
281d0 6f 20 69 66 20 70 72 65 76 69 6f 75 73 20 63 61  o if previous ca
281e0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
281f0 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64  tep](P) returned
28200 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  .** [SQLITE_ROW]
28210 2c 20 65 78 63 65 70 74 20 69 6e 20 74 68 65 20  , except in the 
28220 63 61 73 65 20 6f 66 20 74 68 65 20 5b 50 52 41  case of the [PRA
28230 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f  GMA incremental_
28240 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65  vacuum].** where
28250 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72   it always retur
28260 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 61  ns zero since ea
28270 63 68 20 73 74 65 70 20 6f 66 20 74 68 61 74 20  ch step of that 
28280 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72  multi-step.** pr
28290 61 67 6d 61 20 72 65 74 75 72 6e 73 20 30 20 63  agma returns 0 c
282a0 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a  olumns of data..
282b0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
282c0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
282d0 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20  count()].*/.int 
282e0 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
282f0 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  nt(sqlite3_stmt 
28300 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
28310 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d  CAPI3REF: Fundam
28320 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a  ental Datatypes.
28330 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c  ** KEYWORDS: SQL
28340 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e  ITE_TEXT.**.** ^
28350 28 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20  (Every value in 
28360 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f  SQLite has one o
28370 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74  f five fundament
28380 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a  al datatypes:.**
28390 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
283a0 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
283b0 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36  nteger.** <li> 6
283c0 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74  4-bit IEEE float
283d0 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72  ing point number
283e0 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a  .** <li> string.
283f0 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20  ** <li> BLOB.** 
28400 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75  <li> NULL.** </u
28410 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  l>)^.**.** These
28420 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63   constants are c
28430 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66  odes for each of
28440 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a   those types..**
28450 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68  .** Note that th
28460 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f  e SQLITE_TEXT co
28470 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20  nstant was also 
28480 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76  used in SQLite v
28490 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20  ersion 2.** for 
284a0 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66  a completely dif
284b0 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20  ferent meaning. 
284c0 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c   Software that l
284d0 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74  inks against bot
284e0 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73  h.** SQLite vers
284f0 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65  ion 2 and SQLite
28500 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c   version 3 shoul
28510 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45  d use SQLITE3_TE
28520 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54  XT, not.** SQLIT
28530 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69  E_TEXT..*/.#defi
28540 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  ne SQLITE_INTEGE
28550 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  R  1.#define SQL
28560 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23  ITE_FLOAT    2.#
28570 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c  define SQLITE_BL
28580 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65  OB     4.#define
28590 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20   SQLITE_NULL    
285a0 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45   5.#ifdef SQLITE
285b0 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51  _TEXT.# undef SQ
285c0 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a  LITE_TEXT.#else.
285d0 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
285e0 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69  TEXT     3.#endi
285f0 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  f.#define SQLITE
28600 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a  3_TEXT     3../*
28610 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
28620 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d  sult Values From
28630 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57   A Query.** KEYW
28640 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63  ORDS: {column ac
28650 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a  cess functions}.
28660 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
28670 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22 72  ines form the "r
28680 65 73 75 6c 74 20 73 65 74 22 20 69 6e 74 65 72  esult set" inter
28690 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  face..**.** ^The
286a0 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
286b0 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  rn information a
286c0 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f  bout a single co
286d0 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72  lumn of the curr
286e0 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f  ent.** result ro
286f0 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e  w of a query.  ^
28700 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 74 68  In every case th
28710 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
28720 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a   is a pointer.**
28730 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65   to the [prepare
28740 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
28750 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75  t is being evalu
28760 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74  ated (the [sqlit
28770 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61  e3_stmt*].** tha
28780 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 66  t was returned f
28790 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  rom [sqlite3_pre
287a0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e  pare_v2()] or on
287b0 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74  e of its variant
287c0 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65  s).** and the se
287d0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
287e0 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
287f0 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69  e column for whi
28800 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ch information.*
28810 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75  * should be retu
28820 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d  rned. ^The leftm
28830 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  ost column of th
28840 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 61 73  e result set has
28850 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a   the index 0..**
28860 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20   ^The number of 
28870 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
28880 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74  esult can be det
28890 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a  ermined using.**
288a0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
288b0 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _count()]..**.**
288c0 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74   If the SQL stat
288d0 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63  ement does not c
288e0 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74  urrently point t
288f0 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f  o a valid row, o
28900 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75  r if the.** colu
28910 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20  mn index is out 
28920 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65  of range, the re
28930 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65  sult is undefine
28940 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  d..** These rout
28950 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ines may only be
28960 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65   called when the
28970 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
28980 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
28990 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74  _step()] has ret
289a0 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f  urned [SQLITE_RO
289b0 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a  W] and neither.*
289c0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
289d0 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33  ()] nor [sqlite3
289e0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76  _finalize()] hav
289f0 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75  e been called su
28a00 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49  bsequently..** I
28a10 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72  f any of these r
28a20 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
28a30 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  ed after [sqlite
28a40 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
28a50 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
28a60 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b  ze()] or after [
28a70 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
28a80 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  has returned.** 
28a90 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20  something other 
28aa0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  than [SQLITE_ROW
28ab0 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  ], the results a
28ac0 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
28ad0 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   If [sqlite3_ste
28ae0 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  p()] or [sqlite3
28af0 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
28b00 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
28b10 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20  ].** are called 
28b20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74  from a different
28b30 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e   thread while an
28b40 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  y of these routi
28b50 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69  nes.** are pendi
28b60 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73  ng, then the res
28b70 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
28b80 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
28b90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
28ba0 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  pe() routine ret
28bb0 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  urns the.** [SQL
28bc0 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61  ITE_INTEGER | da
28bd0 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72  tatype code] for
28be0 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74   the initial dat
28bf0 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65  a type.** of the
28c00 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20   result column. 
28c10 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 76   ^The returned v
28c20 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b  alue is one of [
28c30 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c  SQLITE_INTEGER],
28c40 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41  .** [SQLITE_FLOA
28c50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54  T], [SQLITE_TEXT
28c60 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d  ], [SQLITE_BLOB]
28c70 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c  , or [SQLITE_NUL
28c80 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a  L].  The value.*
28c90 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  * returned by sq
28ca0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
28cb0 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e  e() is only mean
28cc0 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70  ingful if no typ
28cd0 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73  e.** conversions
28ce0 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 61   have occurred a
28cf0 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f  s described belo
28d00 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 65  w.  After a type
28d10 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20   conversion,.** 
28d20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
28d30 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
28d40 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75  lumn_type() is u
28d50 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72  ndefined.  Futur
28d60 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66  e.** versions of
28d70 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e   SQLite may chan
28d80 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  ge the behavior 
28d90 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  of sqlite3_colum
28da0 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c  n_type().** foll
28db0 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e  owing a type con
28dc0 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  version..**.** ^
28dd0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
28de0 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38   a BLOB or UTF-8
28df0 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65   string then the
28e00 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
28e10 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69  bytes().** routi
28e20 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
28e30 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
28e40 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73  n that BLOB or s
28e50 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
28e60 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54  e result is a UT
28e70 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65  F-16 string, the
28e80 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
28e90 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74  _bytes() convert
28ea0 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  s.** the string 
28eb0 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65  to UTF-8 and the
28ec0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
28ed0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a  mber of bytes..*
28ee0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
28ef0 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61   is a numeric va
28f00 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  lue then sqlite3
28f10 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
28f20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  uses.** [sqlite3
28f30 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20  _snprintf()] to 
28f40 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c  convert that val
28f50 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74  ue to a UTF-8 st
28f60 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
28f70 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
28f80 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
28f90 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
28fa0 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c  he result is NUL
28fb0 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  L, then sqlite3_
28fc0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72  column_bytes() r
28fd0 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a  eturns zero..**.
28fe0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
28ff0 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55  t is a BLOB or U
29000 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65  TF-16 string the
29010 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  n the sqlite3_co
29020 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a  lumn_bytes16().*
29030 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
29040 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
29050 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c  bytes in that BL
29060 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a  OB or string..**
29070 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
29080 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  is a UTF-8 strin
29090 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  g, then sqlite3_
290a0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
290b0 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65   converts.** the
290c0 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31   string to UTF-1
290d0 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72  6 and then retur
290e0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
290f0 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74   bytes..** ^If t
29100 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e  he result is a n
29110 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65  umeric value the
29120 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
29130 5f 62 79 74 65 73 31 36 28 29 20 75 73 65 73 0a  _bytes16() uses.
29140 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ** [sqlite3_snpr
29150 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65  intf()] to conve
29160 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f  rt that value to
29170 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
29180 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20   and returns.** 
29190 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
291a0 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69  tes in that stri
291b0 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
291c0 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74  esult is NULL, t
291d0 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
291e0 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65 74  mn_bytes16() ret
291f0 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  urns zero..**.**
29200 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74   ^The values ret
29210 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
29220 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
29230 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74  ] and .** [sqlit
29240 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
29250 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c  6()] do not incl
29260 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72  ude the zero ter
29270 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20  minators at the 
29280 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74  end.** of the st
29290 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72  ring.  ^For clar
292a0 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20  ity: the values 
292b0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
292c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
292d0 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c  ytes()] and [sql
292e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
292f0 73 31 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e  s16()] are the n
29300 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65  umber of.** byte
29310 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c  s in the string,
29320 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20   not the number 
29330 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  of characters..*
29340 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65  *.** ^Strings re
29350 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
29360 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
29370 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
29380 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20  mn_text16(),.** 
29390 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  even empty strin
293a0 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a  gs, are always z
293b0 65 72 6f 20 74 65 72 6d 69 6e 61 74 65 64 2e 20  ero terminated. 
293c0 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20   ^The return.** 
293d0 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
293e0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
293f0 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67   for a zero-leng
29400 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c  th BLOB is a NUL
29410 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
29420 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74   ^The object ret
29430 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
29440 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
29450 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72  ] is an.** [unpr
29460 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
29470 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20  value] object.  
29480 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  An unprotected s
29490 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
294a0 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20  ect.** may only 
294b0 62 65 20 75 73 65 64 20 77 69 74 68 20 5b 73 71  be used with [sq
294c0 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
294d0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
294e0 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d  _result_value()]
294f0 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70  ..** If the [unp
29500 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
29510 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72  _value] object r
29520 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
29530 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
29540 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 69  lue()] is used i
29550 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c  n any other way,
29560 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73   including calls
29570 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20  .** to routines 
29580 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61  like [sqlite3_va
29590 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c  lue_int()], [sql
295a0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
295b0 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  )],.** or [sqlit
295c0 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29  e3_value_bytes()
295d0 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ], then the beha
295e0 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
295f0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  d..**.** These r
29600 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20  outines attempt 
29610 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76  to convert the v
29620 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 6f  alue where appro
29630 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a  priate.  ^For.**
29640 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65   example, if the
29650 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73   internal repres
29660 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41  entation is FLOA
29670 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73  T and a text res
29680 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73  ult.** is reques
29690 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e  ted, [sqlite3_sn
296a0 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65  printf()] is use
296b0 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20  d internally to 
296c0 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63  perform the.** c
296d0 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61  onversion automa
296e0 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20  tically.  ^(The 
296f0 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20  following table 
29700 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76  details the conv
29710 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20  ersions.** that 
29720 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a  are applied:.**.
29730 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  ** <blockquote>.
29740 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72  ** <table border
29750 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68  ="1">.** <tr><th
29760 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79  > Internal<br>Ty
29770 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65  pe <th> Requeste
29780 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20  d<br>Type <th>  
29790 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a  Conversion.**.**
297a0 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
297b0 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
297c0 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
297d0 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20   0.** <tr><td>  
297e0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c  NULL    <td>  FL
297f0 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75  OAT    <td> Resu
29800 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72  lt is 0.0.** <tr
29810 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
29820 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
29830 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c  d> Result is NUL
29840 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72  L pointer.** <tr
29850 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
29860 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
29870 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c  d> Result is NUL
29880 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72  L pointer.** <tr
29890 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
298a0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
298b0 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20  d> Convert from 
298c0 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74  integer to float
298d0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
298e0 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58  EGER  <td>   TEX
298f0 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20  T    <td> ASCII 
29900 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
29910 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e   integer.** <tr>
29920 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
29930 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
29940 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45  > Same as INTEGE
29950 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c  R->TEXT.** <tr><
29960 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
29970 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
29980 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c   Convert from fl
29990 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a  oat to integer.*
299a0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
299b0 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  T   <td>   TEXT 
299c0 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
299d0 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66  ndering of the f
299e0 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  loat.** <tr><td>
299f0 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20    FLOAT   <td>  
29a00 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61   BLOB    <td> Sa
29a10 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58  me as FLOAT->TEX
29a20 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  T.** <tr><td>  T
29a30 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  EXT    <td> INTE
29a40 47 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20 61  GER   <td> Use a
29a50 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  toi().** <tr><td
29a60 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
29a70 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 55   FLOAT    <td> U
29a80 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72  se atof().** <tr
29a90 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
29aa0 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
29ab0 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20  d> No change.** 
29ac0 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
29ad0 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
29ae0 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f   <td> Convert to
29af0 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61   TEXT then use a
29b00 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  toi().** <tr><td
29b10 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
29b20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43   FLOAT    <td> C
29b30 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74  onvert to TEXT t
29b40 68 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a 2a  hen use atof().*
29b50 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
29b60 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
29b70 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65     <td> Add a ze
29b80 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66  ro terminator if
29b90 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62   needed.** </tab
29ba0 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75  le>.** </blockqu
29bb0 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ote>)^.**.** The
29bc0 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b   table above mak
29bd0 65 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20  es reference to 
29be0 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
29bf0 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f  ry functions ato
29c00 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28  i().** and atof(
29c10 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20  ).  SQLite does 
29c20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74  not really use t
29c30 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20  hese functions. 
29c40 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f   It has its.** o
29c50 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e  wn equivalent in
29c60 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e  ternal routines.
29c70 20 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64    The atoi() and
29c80 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72   atof() names ar
29c90 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65  e.** used in the
29ca0 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69   table for brevi
29cb0 74 79 20 61 6e 64 20 62 65 63 61 75 73 65 20 74  ty and because t
29cc0 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72  hey are familiar
29cd0 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72   to most.** C pr
29ce0 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a  ogrammers..**.**
29cf0 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20   Note that when 
29d00 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73  type conversions
29d10 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73   occur, pointers
29d20 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69   returned by pri
29d30 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73  or.** calls to s
29d40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
29d50 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f  ob(), sqlite3_co
29d60 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64  lumn_text(), and
29d70 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  /or.** sqlite3_c
29d80 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d  olumn_text16() m
29d90 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65  ay be invalidate
29da0 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65  d..** Type conve
29db0 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74  rsions and point
29dc0 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73  er invalidations
29dd0 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20   might occur.** 
29de0 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  in the following
29df0 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75   cases:.**.** <u
29e00 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  l>.** <li> The i
29e10 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
29e20 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c  s a BLOB and sql
29e30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
29e40 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
29e50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
29e60 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  t16() is called.
29e70 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61    A zero-termina
29e80 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20  tor might.**    
29e90 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64    need to be add
29ea0 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67  ed to the string
29eb0 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  .</li>.** <li> T
29ec0 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
29ed0 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74  nt is UTF-8 text
29ee0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
29ef0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72  umn_bytes16() or
29f00 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
29f10 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
29f20 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65   is called.  The
29f30 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65   content must be
29f40 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20   converted.**   
29f50 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c     to UTF-16.</l
29f60 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  i>.** <li> The i
29f70 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
29f80 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e  s UTF-16 text an
29f90 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
29fa0 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20  _bytes() or.**  
29fb0 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
29fc0 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c  mn_text() is cal
29fd0 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e  led.  The conten
29fe0 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  t must be conver
29ff0 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55  ted.**      to U
2a000 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  TF-8.</li>.** </
2a010 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65  ul>.**.** ^Conve
2a020 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55  rsions between U
2a030 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d  TF-16be and UTF-
2a040 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20  16le are always 
2a050 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e  done in place an
2a060 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61  d do.** not inva
2a070 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70  lidate a prior p
2a080 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f  ointer, though o
2a090 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e  f course the con
2a0a0 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66  tent of the buff
2a0b0 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70  er.** that the p
2a0c0 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66  rior pointer ref
2a0d0 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76  erences will hav
2a0e0 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e  e been modified.
2a0f0 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a    Other kinds.**
2a100 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61   of conversion a
2a110 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  re done in place
2a120 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73   when it is poss
2a130 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69  ible, but someti
2a140 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20  mes they.** are 
2a150 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64  not possible and
2a160 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20   in those cases 
2a170 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61  prior pointers a
2a180 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a  re invalidated..
2a190 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74  **.** The safest
2a1a0 20 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20   and easiest to 
2a1b0 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20  remember policy 
2a1c0 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65  is to invoke the
2a1d0 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69  se routines.** i
2a1e0 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  n one of the fol
2a1f0 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a  lowing ways:.**.
2a200 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e  ** <ul>.**  <li>
2a210 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2a220 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  ext() followed b
2a230 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
2a240 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a  _bytes()</li>.**
2a250 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
2a260 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c  lumn_blob() foll
2a270 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
2a280 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f  column_bytes()</
2a290 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  li>.**  <li>sqli
2a2a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2a2b0 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  6() followed by 
2a2c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2a2d0 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a  ytes16()</li>.**
2a2e0 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20   </ul>.**.** In 
2a2f0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75  other words, you
2a300 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c   should call sql
2a310 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2a320 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  (),.** sqlite3_c
2a330 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72  olumn_blob(), or
2a340 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2a350 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74  text16() first t
2a360 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75  o force the resu
2a370 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64  lt.** into the d
2a380 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74  esired format, t
2a390 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  hen invoke sqlit
2a3a0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2a3b0 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
2a3c0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2a3d0 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a   to find the siz
2a3e0 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e  e of the result.
2a3f0 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c    Do not mix cal
2a400 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  ls.** to sqlite3
2a410 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f  _column_text() o
2a420 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
2a430 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c  _blob() with cal
2a440 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ls to.** sqlite3
2a450 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2a460 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69  ), and do not mi
2a470 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  x calls to sqlit
2a480 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2a490 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73  ().** with calls
2a4a0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
2a4b0 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a  mn_bytes()..**.*
2a4c0 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20  * ^The pointers 
2a4d0 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c  returned are val
2a4e0 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20  id until a type 
2a4f0 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72  conversion occur
2a500 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65  s as.** describe
2a510 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69  d above, or unti
2a520 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  l [sqlite3_step(
2a530 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
2a540 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
2a550 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2a560 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e  )] is called.  ^
2a570 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65  The memory space
2a580 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74   used to hold st
2a590 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f  rings.** and BLO
2a5a0 42 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f  Bs is freed auto
2a5b0 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c  matically.  Do <
2a5c0 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74  b>not</b> pass t
2a5d0 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  he pointers retu
2a5e0 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  rned.** [sqlite3
2a5f0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c  _column_blob()],
2a600 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2a610 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69  _text()], etc. i
2a620 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nto.** [sqlite3_
2a630 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  free()]..**.** ^
2a640 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  (If a memory all
2a650 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63  ocation error oc
2a660 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20  curs during the 
2a670 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e  evaluation of an
2a680 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f  y.** of these ro
2a690 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c  utines, a defaul
2a6a0 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72  t value is retur
2a6b0 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c  ned.  The defaul
2a6c0 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69  t value.** is ei
2a6d0 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72  ther the integer
2a6e0 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67   0, the floating
2a6f0 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e   point number 0.
2a700 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20  0, or a NULL.** 
2a710 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71  pointer.  Subseq
2a720 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73  uent calls to [s
2a730 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
2a740 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a  ] will return.**
2a750 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e   [SQLITE_NOMEM].
2a760 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64  )^.*/.const void
2a770 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2a780 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  _blob(sqlite3_st
2a790 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2a7a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
2a7b0 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33  mn_bytes(sqlite3
2a7c0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2a7d0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
2a7e0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71  olumn_bytes16(sq
2a7f0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2a800 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73   iCol);.double s
2a810 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f  qlite3_column_do
2a820 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
2a830 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
2a840 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
2a850 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  n_int(sqlite3_st
2a860 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2a870 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
2a880 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
2a890 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
2a8a0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e  , int iCol);.con
2a8b0 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  st unsigned char
2a8c0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2a8d0 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74  _text(sqlite3_st
2a8e0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2a8f0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2a900 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2a910 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2a920 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
2a930 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2a940 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ype(sqlite3_stmt
2a950 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71  *, int iCol);.sq
2a960 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c  lite3_value *sql
2a970 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
2a980 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2a990 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a   int iCol);../*.
2a9a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73  ** CAPI3REF: Des
2a9b0 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20  troy A Prepared 
2a9c0 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
2a9d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2a9e0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66  te3_finalize() f
2a9f0 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65  unction is calle
2aa00 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70  d to delete a [p
2aa10 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2aa20 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  t]..** ^If the m
2aa30 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75  ost recent evalu
2aa40 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61  ation of the sta
2aa50 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72  tement encounter
2aa60 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20  ed no errors.** 
2aa70 6f 72 20 69 66 20 74 68 65 20 73 74 61 74 65 6d  or if the statem
2aa80 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62 65 65  ent is never bee
2aa90 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65  n evaluated, the
2aaa0 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  n sqlite3_finali
2aab0 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  ze() returns.** 
2aac0 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20  SQLITE_OK.  ^If 
2aad0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
2aae0 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74  evaluation of st
2aaf0 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64  atement S failed
2ab00 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  , then.** sqlite
2ab10 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65  3_finalize(S) re
2ab20 74 75 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70  turns the approp
2ab30 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
2ab40 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64  e] or.** [extend
2ab50 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  ed error code]..
2ab60 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2ab70 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72  e3_finalize(S) r
2ab80 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61  outine can be ca
2ab90 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e  lled at any poin
2aba0 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20  t during.** the 
2abb0 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70  life cycle of [p
2abc0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2abd0 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20  t] S:.** before 
2abe0 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65  statement S is e
2abf0 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61  ver evaluated, a
2ac00 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d  fter.** one or m
2ac10 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ore calls to [sq
2ac20 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20  lite3_reset()], 
2ac30 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c  or after any cal
2ac40 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33  l.** to [sqlite3
2ac50 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c  _step()] regardl
2ac60 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
2ac70 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d  r not the statem
2ac80 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c  ent has.** compl
2ac90 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a  eted execution..
2aca0 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20  **.** ^Invoking 
2acb0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2acc0 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69  () on a NULL poi
2acd0 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65  nter is a harmle
2ace0 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20  ss no-op..**.** 
2acf0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
2ad00 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76  must finalize ev
2ad10 65 72 79 20 5b 70 72 65 70 61 72 65 64 20 73 74  ery [prepared st
2ad20 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65  atement] in orde
2ad30 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65  r to avoid.** re
2ad40 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49  source leaks.  I
2ad50 74 20 69 73 20 61 20 67 72 69 65 76 6f 75 73 20  t is a grievous 
2ad60 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70  error for the ap
2ad70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79  plication to try
2ad80 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65   to use.** a pre
2ad90 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2ada0 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65  after it has bee
2adb0 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e  n finalized.  An
2adc0 79 20 75 73 65 20 6f 66 20 61 20 70 72 65 70 61  y use of a prepa
2add0 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  red.** statement
2ade0 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65   after it has be
2adf0 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e  en finalized can
2ae00 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66   result in undef
2ae10 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65  ined and.** unde
2ae20 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72  sirable behavior
2ae30 20 73 75 63 68 20 61 73 20 73 65 67 66 61 75 6c   such as segfaul
2ae40 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72  ts and heap corr
2ae50 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73  uption..*/.int s
2ae60 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2ae70 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2ae80 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2ae90 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 50  I3REF: Reset A P
2aea0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
2aeb0 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54  t Object.**.** T
2aec0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74  he sqlite3_reset
2aed0 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
2aee0 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61  alled to reset a
2aef0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2af00 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  ment].** object 
2af10 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
2af20 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79  ial state, ready
2af30 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74   to be re-execut
2af40 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20  ed..** ^Any SQL 
2af50 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62  statement variab
2af60 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61 6c  les that had val
2af70 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65  ues bound to the
2af80 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b  m using.** the [
2af90 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2afa0 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  b | sqlite3_bind
2afb0 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e  _*() API] retain
2afc0 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a   their values..*
2afd0 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63  * Use [sqlite3_c
2afe0 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d  lear_bindings()]
2aff0 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 69   to reset the bi
2b000 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ndings..**.** ^T
2b010 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
2b020 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
2b030 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 65 70  resets the [prep
2b040 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2b050 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65  S.** back to the
2b060 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74   beginning of it
2b070 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a  s program..**.**
2b080 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
2b090 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
2b0a0 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66  lite3_step(S)] f
2b0b0 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  or the.** [prepa
2b0c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2b0d0 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
2b0e0 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54  E_ROW] or [SQLIT
2b0f0 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69  E_DONE],.** or i
2b100 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  f [sqlite3_step(
2b110 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65  S)] has never be
2b120 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  fore been called
2b130 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b   on S,.** then [
2b140 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
2b150 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  ] returns [SQLIT
2b160 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  E_OK]..**.** ^If
2b170 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
2b180 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2b190 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74  3_step(S)] for t
2b1a0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
2b1b0 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64  statement] S ind
2b1c0 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c  icated an error,
2b1d0 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65   then.** [sqlite
2b1e0 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75  3_reset(S)] retu
2b1f0 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61  rns an appropria
2b200 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e  te [error code].
2b210 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  .**.** ^The [sql
2b220 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69  ite3_reset(S)] i
2b230 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f  nterface does no
2b240 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c  t change the val
2b250 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73  ues.** of any [s
2b260 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2b270 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68  |bindings] on th
2b280 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2b290 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74  ement] S..*/.int
2b2a0 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73   sqlite3_reset(s
2b2b0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
2b2c0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
2b2d0 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20  3REF: Create Or 
2b2e0 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e  Redefine SQL Fun
2b2f0 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52  ctions.** KEYWOR
2b300 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72  DS: {function cr
2b310 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d  eation routines}
2b320 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
2b330 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2b340 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d  ed SQL function}
2b350 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
2b360 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2b370 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
2b380 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66  }.**.** ^These f
2b390 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63  unctions (collec
2b3a0 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20  tively known as 
2b3b0 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69  "function creati
2b3c0 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a  on routines").**
2b3d0 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64   are used to add
2b3e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f   SQL functions o
2b3f0 72 20 61 67 67 72 65 67 61 74 65 73 20 6f 72 20  r aggregates or 
2b400 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65 20  to redefine the 
2b410 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65  behavior.** of e
2b420 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63  xisting SQL func
2b430 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61  tions or aggrega
2b440 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64  tes.  The only d
2b450 69 66 66 65 72 65 6e 63 65 73 20 62 65 74 77 65  ifferences betwe
2b460 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74  en.** these rout
2b470 69 6e 65 73 20 61 72 65 20 74 68 65 20 74 65 78  ines are the tex
2b480 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 63  t encoding expec
2b490 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73  ted for.** the s
2b4a0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
2b4b0 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65  (the name of the
2b4c0 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20   function being 
2b4d0 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20  created).** and 
2b4e0 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 72 20  the presence or 
2b4f0 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64 65 73  absence of a des
2b500 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b  tructor callback
2b510 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c   for.** the appl
2b520 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
2b530 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nter..**.** ^The
2b540 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
2b550 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 73   is the [databas
2b560 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f  e connection] to
2b570 20 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a   which the SQL.*
2b580 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f  * function is to
2b590 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20   be added.  ^If 
2b5a0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75  an application u
2b5b0 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  ses more than on
2b5c0 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
2b5d0 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70  nnection then ap
2b5e0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2b5f0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  d SQL functions 
2b600 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a  must be added.**
2b610 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73   to each databas
2b620 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70  e connection sep
2b630 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  arately..**.** ^
2b640 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
2b650 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65  eter is the name
2b660 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63   of the SQL func
2b670 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74  tion to be creat
2b680 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e  ed or.** redefin
2b690 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68  ed.  ^The length
2b6a0 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20   of the name is 
2b6b0 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62  limited to 255 b
2b6c0 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d 38 0a  ytes in a UTF-8.
2b6d0 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  ** representatio
2b6e0 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20  n, exclusive of 
2b6f0 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  the zero-termina
2b700 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74  tor.  ^Note that
2b710 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e   the name.** len
2b720 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20  gth limit is in 
2b730 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74  UTF-8 bytes, not
2b740 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f 72 20   characters nor 
2b750 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20 20 0a  UTF-16 bytes.  .
2b760 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20  ** ^Any attempt 
2b770 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e 63  to create a func
2b780 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67  tion with a long
2b790 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20  er name.** will 
2b7a0 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54  result in [SQLIT
2b7b0 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 20  E_MISUSE] being 
2b7c0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
2b7d0 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d  ^The third param
2b7e0 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69  eter (nArg).** i
2b7f0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
2b800 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74  arguments that t
2b810 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
2b820 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20  or.** aggregate 
2b830 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20  takes. ^If this 
2b840 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c  parameter is -1,
2b850 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75   then the SQL fu
2b860 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
2b870 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20  regate may take 
2b880 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  any number of ar
2b890 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20  guments between 
2b8a0 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a  0 and the limit.
2b8b0 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74  ** set by [sqlit
2b8c0 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54  e3_limit]([SQLIT
2b8d0 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
2b8e0 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20  _ARG]).  If the 
2b8f0 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74  third.** paramet
2b900 65 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  er is less than 
2b910 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 68  -1 or greater th
2b920 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65 20  an 127 then the 
2b930 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75  behavior is.** u
2b940 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
2b950 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61  ^The fourth para
2b960 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c  meter, eTextRep,
2b970 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74 0a   specifies what.
2b980 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20  ** [SQLITE_UTF8 
2b990 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d  | text encoding]
2b9a0 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69   this SQL functi
2b9b0 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a  on prefers for.*
2b9c0 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 73  * its parameters
2b9d0 2e 20 20 45 76 65 72 79 20 53 51 4c 20 66 75 6e  .  Every SQL fun
2b9e0 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
2b9f0 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 61 62 6c  tion must be abl
2ba00 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74  e to work.** wit
2ba10 68 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c  h UTF-8, UTF-16l
2ba20 65 2c 20 6f 72 20 55 54 46 2d 31 36 62 65 2e 20  e, or UTF-16be. 
2ba30 20 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d   But some implem
2ba40 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 62 65  entations may be
2ba50 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63 69 65  .** more efficie
2ba60 6e 74 20 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f  nt with one enco
2ba70 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68 65  ding than anothe
2ba80 72 2e 20 20 5e 41 6e 20 61 70 70 6c 69 63 61 74  r.  ^An applicat
2ba90 69 6f 6e 20 6d 61 79 0a 2a 2a 20 69 6e 76 6f 6b  ion may.** invok
2baa0 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
2bab0 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73  _function() or s
2bac0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2bad0 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69  nction16() multi
2bae0 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74  ple.** times wit
2baf0 68 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  h the same funct
2bb00 69 6f 6e 20 62 75 74 20 77 69 74 68 20 64 69 66  ion but with dif
2bb10 66 65 72 65 6e 74 20 76 61 6c 75 65 73 20 6f 66  ferent values of
2bb20 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20 5e 57   eTextRep..** ^W
2bb30 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  hen multiple imp
2bb40 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
2bb50 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
2bb60 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c  n are available,
2bb70 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20   SQLite.** will 
2bb80 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61  pick the one tha
2bb90 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c  t involves the l
2bba0 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64  east amount of d
2bbb0 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a  ata conversion..
2bbc0 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73 20 6f  ** If there is o
2bbd0 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 69 6d 70  nly a single imp
2bbe0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 63  lementation whic
2bbf0 68 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20  h does not care 
2bc00 77 68 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63  what text.** enc
2bc10 6f 64 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74  oding is used, t
2bc20 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61  hen the fourth a
2bc30 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62  rgument should b
2bc40 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a  e [SQLITE_ANY]..
2bc50 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74  **.** ^(The fift
2bc60 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  h parameter is a
2bc70 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e  n arbitrary poin
2bc80 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d  ter.  The implem
2bc90 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a  entation of the.
2bca0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20  ** function can 
2bcb0 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74  gain access to t
2bcc0 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e  his pointer usin
2bcd0 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  g [sqlite3_user_
2bce0 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a  data()].)^.**.**
2bcf0 20 5e 54 68 65 20 73 69 78 74 68 2c 20 73 65 76   ^The sixth, sev
2bd00 65 6e 74 68 20 61 6e 64 20 65 69 67 68 74 68 20  enth and eighth 
2bd10 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e  parameters, xFun
2bd20 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 69  c, xStep and xFi
2bd30 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e  nal, are.** poin
2bd40 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61  ters to C-langua
2bd50 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61  ge functions tha
2bd60 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20  t implement the 
2bd70 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
2bd80 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41  ** aggregate. ^A
2bd90 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63   scalar SQL func
2bda0 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e  tion requires an
2bdb0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2bdc0 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20  of the xFunc.** 
2bdd0 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e  callback only; N
2bde0 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73  ULL pointers mus
2bdf0 74 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  t be passed as t
2be00 68 65 20 78 53 74 65 70 20 61 6e 64 20 78 46 69  he xStep and xFi
2be10 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  nal.** parameter
2be20 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65  s. ^An aggregate
2be30 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65   SQL function re
2be40 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d  quires an implem
2be50 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65  entation of xSte
2be60 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20  p.** and xFinal 
2be70 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  and NULL pointer
2be80 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20   must be passed 
2be90 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64  for xFunc. ^To d
2bea0 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e  elete an existin
2beb0 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f  g.** SQL functio
2bec0 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20  n or aggregate, 
2bed0 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  pass NULL pointe
2bee0 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65  rs for all three
2bef0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c   function.** cal
2bf00 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  lbacks..**.** ^(
2bf10 49 66 20 74 68 65 20 6e 69 6e 74 68 20 70 61 72  If the ninth par
2bf20 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
2bf30 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2bf40 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 4e 55  n_v2() is not NU
2bf50 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69  LL,.** then it i
2bf60 73 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72  s destructor for
2bf70 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2bf80 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a   data pointer. .
2bf90 2a 2a 20 54 68 65 20 64 65 73 74 72 75 63 74 6f  ** The destructo
2bfa0 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65  r is invoked whe
2bfb0 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  n the function i
2bfc0 73 20 64 65 6c 65 74 65 64 2c 20 65 69 74 68 65  s deleted, eithe
2bfd0 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76  r by being.** ov
2bfe0 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 6e  erloaded or when
2bff0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2c000 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e  nnection closes.
2c010 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 72  )^.** ^The destr
2c020 75 63 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e  uctor is also in
2c030 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c  voked if the cal
2c040 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  l to.** sqlite3_
2c050 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
2c060 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e  v2() fails..** ^
2c070 57 68 65 6e 20 74 68 65 20 64 65 73 74 72 75 63  When the destruc
2c080 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20  tor callback of 
2c090 74 68 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65  the tenth parame
2c0a0 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20  ter is invoked, 
2c0b0 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20  it.** is passed 
2c0c0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
2c0d0 74 20 77 68 69 63 68 20 69 73 20 61 20 63 6f 70  t which is a cop
2c0e0 79 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  y of the applica
2c0f0 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f  tion data .** po
2c100 69 6e 74 65 72 20 77 68 69 63 68 20 77 61 73 20  inter which was 
2c110 74 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65  the fifth parame
2c120 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ter to sqlite3_c
2c130 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
2c140 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69  2()..**.** ^It i
2c150 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72  s permitted to r
2c160 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65  egister multiple
2c170 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
2c180 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20   of the same.** 
2c190 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74  functions with t
2c1a0 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74  he same name but
2c1b0 20 77 69 74 68 20 65 69 74 68 65 72 20 64 69 66   with either dif
2c1c0 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f  fering numbers o
2c1d0 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f  f.** arguments o
2c1e0 72 20 64 69 66 66 65 72 69 6e 67 20 70 72 65 66  r differing pref
2c1f0 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
2c200 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77  ings.  ^SQLite w
2c210 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69  ill use.** the i
2c220 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68  mplementation th
2c230 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20  at most closely 
2c240 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 79 20  matches the way 
2c250 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20  in which the.** 
2c260 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
2c270 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69  used.  ^A functi
2c280 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
2c290 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67  n with a non-neg
2c2a0 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61  ative.** nArg pa
2c2b0 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 65 74  rameter is a bet
2c2c0 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61  ter match than a
2c2d0 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
2c2e0 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a  entation with.**
2c2f0 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67   a negative nArg
2c300 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77  .  ^A function w
2c310 68 65 72 65 20 74 68 65 20 70 72 65 66 65 72 72  here the preferr
2c320 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ed text encoding
2c330 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20  .** matches the 
2c340 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e  database encodin
2c350 67 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a  g is a better.**
2c360 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75   match than a fu
2c370 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
2c380 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66   encoding is dif
2c390 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20  ferent.  .** ^A 
2c3a0 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
2c3b0 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66  he encoding diff
2c3c0 65 72 65 6e 63 65 20 69 73 20 62 65 74 77 65 65  erence is betwee
2c3d0 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54  n UTF16le and UT
2c3e0 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c  F16be.** is a cl
2c3f0 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20  oser match than 
2c400 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  a function where
2c410 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69   the encoding di
2c420 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62  fference is.** b
2c430 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20  etween UTF8 and 
2c440 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75  UTF16..**.** ^Bu
2c450 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73  ilt-in functions
2c460 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64   may be overload
2c470 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63  ed by new applic
2c480 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
2c490 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  nctions..**.** ^
2c4a0 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  An application-d
2c4b0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
2c4c0 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20  is permitted to 
2c4d0 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51  call other.** SQ
2c4e0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e  Lite interfaces.
2c4f0 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20    However, such 
2c500 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a  calls must not.*
2c510 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61  * close the data
2c520 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2c530 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20  nor finalize or 
2c540 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72  reset the prepar
2c550 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  ed.** statement 
2c560 69 6e 20 77 68 69 63 68 20 74 68 65 20 66 75 6e  in which the fun
2c570 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
2c580 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2c590 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2c5a0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
2c5b0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2c5c0 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
2c5d0 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
2c5e0 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
2c5f0 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
2c600 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
2c610 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
2c620 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
2c630 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
2c640 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2c650 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
2c660 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
2c670 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
2c680 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20  ontext*).);.int 
2c690 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2c6a0 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c  unction16(.  sql
2c6b0 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
2c6c0 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f  t void *zFunctio
2c6d0 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
2c6e0 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
2c6f0 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
2c700 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
2c710 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2c720 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
2c730 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
2c740 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
2c750 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
2c760 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
2c770 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
2c780 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2c790 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
2c7a0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2c7b0 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
2c7c0 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  db,.  const char
2c7d0 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
2c7e0 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
2c7f0 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
2c800 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
2c810 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
2c820 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
2c830 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
2c840 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
2c850 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
2c860 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
2c870 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
2c880 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
2c890 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76  3_context*),.  v
2c8a0 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76  oid(*xDestroy)(v
2c8b0 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid*).);../*.** 
2c8c0 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 45  CAPI3REF: Text E
2c8d0 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54  ncodings.**.** T
2c8e0 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65  hese constant de
2c8f0 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64  fine integer cod
2c900 65 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e  es that represen
2c910 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a  t the various.**
2c920 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20   text encodings 
2c930 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c  supported by SQL
2c940 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ite..*/.#define 
2c950 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20  SQLITE_UTF8     
2c960 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
2c970 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20  SQLITE_UTF16LE  
2c980 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
2c990 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20  SQLITE_UTF16BE  
2c9a0 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
2c9b0 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20  SQLITE_UTF16    
2c9c0 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73        4    /* Us
2c9d0 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
2c9e0 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  der */.#define S
2c9f0 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20  QLITE_ANY       
2ca00 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c       5    /* sql
2ca10 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2ca20 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65  tion only */.#de
2ca30 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
2ca40 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20  6_ALIGNED  8    
2ca50 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  /* sqlite3_creat
2ca60 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79  e_collation only
2ca70 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
2ca80 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 20  REF: Deprecated 
2ca90 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50  Functions.** DEP
2caa0 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68  RECATED.**.** Th
2cab0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  ese functions ar
2cac0 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20  e [deprecated]. 
2cad0 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69   In order to mai
2cae0 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72  ntain.** backwar
2caf0 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
2cb00 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65   with older code
2cb10 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  , these function
2cb20 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74  s continue .** t
2cb30 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20  o be supported. 
2cb40 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70   However, new ap
2cb50 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
2cb60 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75  d avoid.** the u
2cb70 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63  se of these func
2cb80 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20  tions.  To help 
2cb90 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65  encourage people
2cba0 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69   to avoid.** usi
2cbb0 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  ng these functio
2cbc0 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67  ns, we are not g
2cbd0 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75  oing to tell you
2cbe0 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a   what they do..*
2cbf0 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  /.#ifndef SQLITE
2cc00 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44  _OMIT_DEPRECATED
2cc10 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
2cc20 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61  ED int sqlite3_a
2cc30 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73  ggregate_count(s
2cc40 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
2cc50 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
2cc60 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
2cc70 65 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f  expired(sqlite3_
2cc80 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44  stmt*);.SQLITE_D
2cc90 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
2cca0 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62  lite3_transfer_b
2ccb0 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f  indings(sqlite3_
2ccc0 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73  stmt*, sqlite3_s
2ccd0 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45  tmt*);.SQLITE_DE
2cce0 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
2ccf0 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f  ite3_global_reco
2cd00 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  ver(void);.SQLIT
2cd10 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69  E_DEPRECATED voi
2cd20 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64  d sqlite3_thread
2cd30 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a  _cleanup(void);.
2cd40 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
2cd50 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65  D int sqlite3_me
2cd60 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28  mory_alarm(void(
2cd70 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
2cd80 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64  _int64,int),void
2cd90 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  *,sqlite3_int64)
2cda0 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  ;.#endif../*.** 
2cdb0 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
2cdc0 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  ing SQL Function
2cdd0 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65   Parameter Value
2cde0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61  s.**.** The C-la
2cdf0 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74  nguage implement
2ce00 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e  ation of SQL fun
2ce10 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
2ce20 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68  gates uses.** th
2ce30 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66  is set of interf
2ce40 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ace routines to 
2ce50 61 63 63 65 73 73 20 74 68 65 20 70 61 72 61 6d  access the param
2ce60 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a  eter values on.*
2ce70 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f  * the function o
2ce80 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a  r aggregate..**.
2ce90 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f  ** The xFunc (fo
2cea0 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f  r scalar functio
2ceb0 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f  ns) or xStep (fo
2cec0 72 20 61 67 67 72 65 67 61 74 65 73 29 20 70 61  r aggregates) pa
2ced0 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b  rameters.** to [
2cee0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2cef0 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  unction()] and [
2cf00 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2cf10 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20  unction16()].** 
2cf20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73  define callbacks
2cf30 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20   that implement 
2cf40 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2cf50 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
2cf60 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20 70 61 72  ..** The 3rd par
2cf70 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65 20  ameter to these 
2cf80 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20  callbacks is an 
2cf90 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
2cfa0 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74  s to.** [protect
2cfb0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2cfc0 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72  ] objects.  Ther
2cfd0 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65  e is one [sqlite
2cfe0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
2cff0 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61  for.** each para
2d000 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c  meter to the SQL
2d010 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73   function.  Thes
2d020 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75  e routines are u
2d030 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63  sed to.** extrac
2d040 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68  t values from th
2d050 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2d060 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a  ] objects..**.**
2d070 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2d080 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b  work only with [
2d090 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2d0a0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
2d0b0 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74  ..** Any attempt
2d0c0 20 74 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f   to use these ro
2d0d0 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e  utines on an [un
2d0e0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2d0f0 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65  3_value].** obje
2d100 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e  ct results in un
2d110 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72  defined behavior
2d120 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  ..**.** ^These r
2d130 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73  outines work jus
2d140 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65  t like the corre
2d150 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e  sponding [column
2d160 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
2d170 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61  s].** except tha
2d180 74 20 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  t  these routine
2d190 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20  s take a single 
2d1a0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
2d1b0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2d1c0 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74  .** pointer inst
2d1d0 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65  ead of a [sqlite
2d1e0 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72  3_stmt*] pointer
2d1f0 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20   and an integer 
2d200 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a  column number..*
2d210 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2d220 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
2d230 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 61   interface extra
2d240 63 74 73 20 61 20 55 54 46 2d 31 36 20 73 74 72  cts a UTF-16 str
2d250 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  ing.** in the na
2d260 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20  tive byte-order 
2d270 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68  of the host mach
2d280 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71  ine.  ^The.** sq
2d290 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2d2a0 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74  16be() and sqlit
2d2b0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
2d2c0 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  e() interfaces.*
2d2d0 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d 31 36  * extract UTF-16
2d2e0 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d   strings as big-
2d2f0 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c  endian and littl
2d300 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74  e-endian respect
2d310 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ively..**.** ^(T
2d320 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
2d330 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20  _numeric_type() 
2d340 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
2d350 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e  ts to apply.** n
2d360 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 20  umeric affinity 
2d370 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54  to the value.  T
2d380 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61  his means that a
2d390 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20  n attempt is.** 
2d3a0 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20  made to convert 
2d3b0 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20  the value to an 
2d3c0 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74  integer or float
2d3d0 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a  ing point.  If.*
2d3e0 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73  * such a convers
2d3f0 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20  ion is possible 
2d400 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20  without loss of 
2d410 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20  information (in 
2d420 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20  other.** words, 
2d430 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 73 20  if the value is 
2d440 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f  a string that lo
2d450 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65  oks like a numbe
2d460 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63  r).** then the c
2d470 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72  onversion is per
2d480 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69  formed.  Otherwi
2d490 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e  se no conversion
2d4a0 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20   occurs..** The 
2d4b0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20  [SQLITE_INTEGER 
2d4c0 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65  | datatype] afte
2d4d0 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  r conversion is 
2d4e0 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a  returned.)^.**.*
2d4f0 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 72  * Please pay par
2d500 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f  ticular attentio
2d510 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68  n to the fact th
2d520 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72  at the pointer r
2d530 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  eturned.** from 
2d540 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
2d550 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  lob()], [sqlite3
2d560 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20  _value_text()], 
2d570 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  or.** [sqlite3_v
2d580 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63  alue_text16()] c
2d590 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65  an be invalidate
2d5a0 64 20 62 79 20 61 20 73 75 62 73 65 71 75 65 6e  d by a subsequen
2d5b0 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  t call to.** [sq
2d5c0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
2d5d0 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  s()], [sqlite3_v
2d5e0 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c  alue_bytes16()],
2d5f0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2d600 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b  text()],.** or [
2d610 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2d620 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  xt16()]..**.** T
2d630 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75  hese routines mu
2d640 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
2d650 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
2d660 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20  d as.** the SQL 
2d670 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75  function that su
2d680 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69  pplied the [sqli
2d690 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61  te3_value*] para
2d6a0 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74  meters..*/.const
2d6b0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
2d6c0 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65  alue_blob(sqlite
2d6d0 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
2d6e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
2d6f0 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  es(sqlite3_value
2d700 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
2d710 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71  value_bytes16(sq
2d720 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64  lite3_value*);.d
2d730 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61  ouble sqlite3_va
2d740 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  lue_double(sqlit
2d750 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
2d760 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
2d770 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t(sqlite3_value*
2d780 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
2d790 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69   sqlite3_value_i
2d7a0 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c  nt64(sqlite3_val
2d7b0 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69  ue*);.const unsi
2d7c0 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74  gned char *sqlit
2d7d0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71  e3_value_text(sq
2d7e0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
2d7f0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2d800 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
2d810 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2d820 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
2d830 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2d840 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  6le(sqlite3_valu
2d850 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  e*);.const void 
2d860 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
2d870 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f  ext16be(sqlite3_
2d880 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
2d890 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28  ite3_value_type(
2d8a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2d8b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
2d8c0 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28  ue_numeric_type(
2d8d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2d8e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2d8f0 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61  : Obtain Aggrega
2d900 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74  te Function Cont
2d910 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d  ext.**.** Implem
2d920 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67  entations of agg
2d930 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
2d940 69 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a  ions use this.**
2d950 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f   routine to allo
2d960 63 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20  cate memory for 
2d970 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74  storing their st
2d980 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ate..**.** ^The 
2d990 66 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73  first time the s
2d9a0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
2d9b0 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f  _context(C,N) ro
2d9c0 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20  utine is called 
2d9d0 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63  .** for a partic
2d9e0 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 20 66  ular aggregate f
2d9f0 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a  unction, SQLite.
2da00 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f  ** allocates N o
2da10 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73  f memory, zeroes
2da20 20 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79   out that memory
2da30 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  , and returns a 
2da40 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68  pointer.** to th
2da50 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f  e new memory. ^O
2da60 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62  n second and sub
2da70 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
2da80 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72  .** sqlite3_aggr
2da90 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
2daa0 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 67  for the same agg
2dab0 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20  regate function 
2dac0 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65  instance,.** the
2dad0 20 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20   same buffer is 
2dae0 72 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74  returned.  Sqlit
2daf0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
2db00 74 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c  text() is normal
2db10 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63  ly.** called onc
2db20 65 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63  e for each invoc
2db30 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74  ation of the xSt
2db40 65 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20  ep callback and 
2db50 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74  then one.** last
2db60 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78   time when the x
2db70 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69  Final callback i
2db80 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68  s invoked.  ^(Wh
2db90 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68  en no rows match
2dba0 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65  .** an aggregate
2dbb0 20 71 75 65 72 79 2c 20 74 68 65 20 78 53 74 65   query, the xSte
2dbc0 70 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20  p() callback of 
2dbd0 74 68 65 20 61 67 67 72 65 67 61 74 65 20 66 75  the aggregate fu
2dbe0 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d  nction.** implem
2dbf0 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65  entation is neve
2dc00 72 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69  r called and xFi
2dc10 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20  nal() is called 
2dc20 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a  exactly once..**
2dc30 20 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c   In those cases,
2dc40 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
2dc50 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67  te_context() mig
2dc60 68 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72  ht be called for
2dc70 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69   the.** first ti
2dc80 6d 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78  me from within x
2dc90 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a  Final().)^.**.**
2dca0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67   ^The sqlite3_ag
2dcb0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
2dcc0 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74  C,N) routine ret
2dcd0 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
2dce0 74 65 72 20 69 66 20 4e 20 69 73 0a 2a 2a 20 6c  ter if N is.** l
2dcf0 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61  ess than or equa
2dd00 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20  l to zero or if 
2dd10 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
2dd20 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a  e error occurs..
2dd30 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75  **.** ^(The amou
2dd40 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f  nt of space allo
2dd50 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  cated by sqlite3
2dd60 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
2dd70 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65  xt(C,N) is.** de
2dd80 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20  termined by the 
2dd90 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66  N parameter on f
2dda0 69 72 73 74 20 73 75 63 63 65 73 73 66 75 6c 20  irst successful 
2ddb0 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20  call.  Changing 
2ddc0 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  the.** value of 
2ddd0 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20  N in subsequent 
2dde0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
2ddf0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
2de00 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68  t() within.** th
2de10 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65  e same aggregate
2de20 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e   function instan
2de30 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69  ce will not resi
2de40 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a  ze the memory.**
2de50 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 0a 2a   allocation.)^.*
2de60 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74  *.** ^SQLite aut
2de70 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73  omatically frees
2de80 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
2de90 63 61 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c  cated by .** sql
2dea0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
2deb0 6f 6e 74 65 78 74 28 29 20 77 68 65 6e 20 74 68  ontext() when th
2dec0 65 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72  e aggregate quer
2ded0 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a  y concludes..**.
2dee0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72  ** The first par
2def0 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 61  ameter must be a
2df00 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
2df10 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
2df20 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20   | SQL function 
2df30 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73  context] that is
2df40 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
2df50 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78  eter.** to the x
2df60 53 74 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63  Step or xFinal c
2df70 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20  allback routine 
2df80 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20  that implements 
2df90 74 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a  the aggregate.**
2dfa0 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
2dfb0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75   This routine mu
2dfc0 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
2dfd0 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
2dfe0 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68  d in which.** th
2dff0 65 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  e aggregate SQL 
2e000 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
2e010 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ing..*/.void *sq
2e020 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
2e030 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f  context(sqlite3_
2e040 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42  context*, int nB
2e050 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ytes);../*.** CA
2e060 50 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74  PI3REF: User Dat
2e070 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a  a For Functions.
2e080 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2e090 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69  e3_user_data() i
2e0a0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2e0b0 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
2e0c0 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77  e pointer that w
2e0d0 61 73 20 74 68 65 20 70 55 73 65 72 44 61 74 61  as the pUserData
2e0e0 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20   parameter (the 
2e0f0 35 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a  5th parameter).*
2e100 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
2e110 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2e120 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  n()].** and [sql
2e130 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2e140 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e  tion16()] routin
2e150 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c  es that original
2e160 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64  ly.** registered
2e170 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2e180 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f   defined functio
2e190 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  n..**.** This ro
2e1a0 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61  utine must be ca
2e1b0 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
2e1c0 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
2e1d0 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  ch.** the applic
2e1e0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
2e1f0 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
2e200 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  g..*/.void *sqli
2e210 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71  te3_user_data(sq
2e220 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
2e230 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2e240 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
2e250 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69  ction For Functi
2e260 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ons.**.** ^The s
2e270 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
2e280 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72  b_handle() inter
2e290 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63  face returns a c
2e2a0 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f  opy of.** the po
2e2b0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61  inter to the [da
2e2c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2e2d0 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61 72 61  n] (the 1st para
2e2e0 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65  meter).** of the
2e2f0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2e300 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20  _function()].** 
2e310 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
2e320 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
2e330 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  ] routines that 
2e340 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65  originally.** re
2e350 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70  gistered the app
2e360 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64  lication defined
2e370 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 71   function..*/.sq
2e380 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63  lite3 *sqlite3_c
2e390 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
2e3a0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2e3b0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2e3c0 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75  REF: Function Au
2e3d0 78 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a  xiliary Data.**.
2e3e0 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** The following
2e3f0 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d   two functions m
2e400 61 79 20 62 65 20 75 73 65 64 20 62 79 20 73 63  ay be used by sc
2e410 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f  alar SQL functio
2e420 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61  ns to.** associa
2e430 74 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68  te metadata with
2e440 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73   argument values
2e450 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61  . If the same va
2e460 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f  lue is passed to
2e470 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76  .** multiple inv
2e480 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
2e490 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  same SQL functio
2e4a0 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65  n during query e
2e4b0 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a  xecution, under.
2e4c0 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74  ** some circumst
2e4d0 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69  ances the associ
2e4e0 61 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61  ated metadata ma
2e4f0 79 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20  y be preserved. 
2e500 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75  This may.** be u
2e510 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  sed, for example
2e520 2c 20 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c  , to add a regul
2e530 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61  ar-expression ma
2e540 74 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a  tching scalar.**
2e550 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63   function. The c
2e560 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20  ompiled version 
2e570 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65  of the regular e
2e580 78 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f  xpression is sto
2e590 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61  red as.** metada
2e5a0 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ta associated wi
2e5b0 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65  th the SQL value
2e5c0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 72   passed as the r
2e5d0 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
2e5e0 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54  n.** pattern.  T
2e5f0 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75  he compiled regu
2e600 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63  lar expression c
2e610 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20  an be reused on 
2e620 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f  multiple.** invo
2e630 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
2e640 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20  ame function so 
2e650 74 68 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61  that the origina
2e660 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67  l pattern string
2e670 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  .** does not nee
2e680 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c  d to be recompil
2e690 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63  ed on each invoc
2e6a0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ation..**.** ^Th
2e6b0 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  e sqlite3_get_au
2e6c0 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  xdata() interfac
2e6d0 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
2e6e0 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64  ter to the metad
2e6f0 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ata.** associate
2e700 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33  d by the sqlite3
2e710 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 66  _set_auxdata() f
2e720 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65  unction with the
2e730 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a   Nth argument.**
2e740 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70   value to the ap
2e750 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2e760 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20  d function. ^If 
2e770 6e 6f 20 6d 65 74 61 64 61 74 61 20 68 61 73 20  no metadata has 
2e780 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65  been ever.** bee
2e790 6e 20 73 65 74 20 66 6f 72 20 74 68 65 20 4e 74  n set for the Nt
2e7a0 68 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68  h argument of th
2e7b0 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69  e function, or i
2e7c0 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  f the correspond
2e7d0 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ing.** function 
2e7e0 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 63 68  parameter has ch
2e7f0 61 6e 67 65 64 20 73 69 6e 63 65 20 74 68 65 20  anged since the 
2e800 6d 65 74 61 2d 64 61 74 61 20 77 61 73 20 73 65  meta-data was se
2e810 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74  t,.** then sqlit
2e820 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
2e830 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
2e840 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
2e850 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  The sqlite3_set_
2e860 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66  auxdata() interf
2e870 61 63 65 20 73 61 76 65 73 20 74 68 65 20 6d 65  ace saves the me
2e880 74 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65  tadata.** pointe
2e890 64 20 74 6f 20 62 79 20 69 74 73 20 33 72 64 20  d to by its 3rd 
2e8a0 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65  parameter as the
2e8b0 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68   metadata for th
2e8c0 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65  e N-th.** argume
2e8d0 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  nt of the applic
2e8e0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
2e8f0 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75  nction.  Subsequ
2e900 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ent.** calls to 
2e910 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
2e920 61 74 61 28 29 20 6d 69 67 68 74 20 72 65 74 75  ata() might retu
2e930 72 6e 20 74 68 69 73 20 64 61 74 61 2c 20 69 66  rn this data, if
2e940 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62   it has.** not b
2e950 65 65 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a  een destroyed..*
2e960 2a 20 5e 49 66 20 69 74 20 69 73 20 6e 6f 74 20  * ^If it is not 
2e970 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c  NULL, SQLite wil
2e980 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73  l invoke the des
2e990 74 72 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74  tructor.** funct
2e9a0 69 6f 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65  ion given by the
2e9b0 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
2e9c0 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  o sqlite3_set_au
2e9d0 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68  xdata() on.** th
2e9e0 65 20 6d 65 74 61 64 61 74 61 20 77 68 65 6e 20  e metadata when 
2e9f0 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
2ea00 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d  g function param
2ea10 65 74 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20  eter changes.** 
2ea20 6f 72 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20  or when the SQL 
2ea30 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65  statement comple
2ea40 74 65 73 2c 20 77 68 69 63 68 65 76 65 72 20 63  tes, whichever c
2ea50 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a  omes first..**.*
2ea60 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72 65 65  * SQLite is free
2ea70 20 74 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73   to call the des
2ea80 74 72 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70  tructor and drop
2ea90 20 6d 65 74 61 64 61 74 61 20 6f 6e 20 61 6e 79   metadata on any
2eaa0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 66  .** parameter of
2eab0 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74   any function at
2eac0 20 61 6e 79 20 74 69 6d 65 2e 20 20 5e 54 68 65   any time.  ^The
2ead0 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65 65 20   only guarantee 
2eae0 69 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 64  is that.** the d
2eaf0 65 73 74 72 75 63 74 6f 72 20 77 69 6c 6c 20 62  estructor will b
2eb00 65 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20  e called before 
2eb10 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20  the metadata is 
2eb20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  dropped..**.** ^
2eb30 28 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65  (In practice, me
2eb40 74 61 64 61 74 61 20 69 73 20 70 72 65 73 65 72  tadata is preser
2eb50 76 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63  ved between func
2eb60 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a  tion calls for.*
2eb70 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68  * expressions th
2eb80 61 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20  at are constant 
2eb90 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e  at compile time.
2eba0 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c   This includes l
2ebb0 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73  iteral.** values
2ebc0 20 61 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73   and [parameters
2ebd0 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ].)^.**.** These
2ebe0 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
2ebf0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
2ec00 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
2ec10 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51   which.** the SQ
2ec20 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  L function is ru
2ec30 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  nning..*/.void *
2ec40 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
2ec50 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
2ec60 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f  ext*, int N);.vo
2ec70 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  id sqlite3_set_a
2ec80 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  uxdata(sqlite3_c
2ec90 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20  ontext*, int N, 
2eca0 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28  void*, void (*)(
2ecb0 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  void*));.../*.**
2ecc0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74   CAPI3REF: Const
2ecd0 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70  ants Defining Sp
2ece0 65 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72  ecial Destructor
2ecf0 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20   Behavior.**.** 
2ed00 54 68 65 73 65 20 61 72 65 20 73 70 65 63 69 61  These are specia
2ed10 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65  l values for the
2ed20 20 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 74   destructor that
2ed30 20 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 73   is passed in as
2ed40 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72   the.** final ar
2ed50 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e  gument to routin
2ed60 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33  es like [sqlite3
2ed70 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e  _result_blob()].
2ed80 20 20 5e 49 66 20 74 68 65 20 64 65 73 74 72 75    ^If the destru
2ed90 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  ctor.** argument
2eda0 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49   is SQLITE_STATI
2edb0 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74  C, it means that
2edc0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69   the content poi
2edd0 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74  nter is constant
2ede0 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76  .** and will nev
2edf0 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64  er change.  It d
2ee00 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
2ee10 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20 5e  be destroyed.  ^
2ee20 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52  The.** SQLITE_TR
2ee30 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65  ANSIENT value me
2ee40 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e  ans that the con
2ee50 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79  tent will likely
2ee60 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68   change in.** th
2ee70 65 20 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e  e near future an
2ee80 64 20 74 68 61 74 20 53 51 4c 69 74 65 20 73 68  d that SQLite sh
2ee90 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77  ould make its ow
2eea0 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
2eeb0 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74  f.** the content
2eec0 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e   before returnin
2eed0 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70  g..**.** The typ
2eee0 65 64 65 66 20 69 73 20 6e 65 63 65 73 73 61 72  edef is necessar
2eef0 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64  y to work around
2ef00 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72   problems in cer
2ef10 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70  tain.** C++ comp
2ef20 69 6c 65 72 73 2e 20 20 53 65 65 20 74 69 63 6b  ilers.  See tick
2ef30 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70  et #2191..*/.typ
2ef40 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69  edef void (*sqli
2ef50 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
2ef60 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65  ype)(void*);.#de
2ef70 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54  fine SQLITE_STAT
2ef80 49 43 20 20 20 20 20 20 28 28 73 71 6c 69 74 65  IC      ((sqlite
2ef90 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
2efa0 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  e)0).#define SQL
2efb0 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20  ITE_TRANSIENT   
2efc0 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  ((sqlite3_destru
2efd0 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f  ctor_type)-1)../
2efe0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
2eff0 65 74 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c  etting The Resul
2f000 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63  t Of An SQL Func
2f010 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  tion.**.** These
2f020 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
2f030 65 64 20 62 79 20 74 68 65 20 78 46 75 6e 63 20  ed by the xFunc 
2f040 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61  or xFinal callba
2f050 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c  cks that.** impl
2f060 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69  ement SQL functi
2f070 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
2f080 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c  es.  See.** [sql
2f090 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2f0a0 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  tion()] and [sql
2f0b0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2f0c0 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72  tion16()].** for
2f0d0 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
2f0e0 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  rmation..**.** T
2f0f0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77  hese functions w
2f100 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69  ork very much li
2f110 6b 65 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65  ke the [paramete
2f120 72 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c  r binding] famil
2f130 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  y of.** function
2f140 73 20 75 73 65 64 20 74 6f 20 62 69 6e 64 20 76  s used to bind v
2f150 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61  alues to host pa
2f160 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70  rameters in prep
2f170 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e  ared statements.
2f180 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65  .** Refer to the
2f190 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d   [SQL parameter]
2f1a0 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66   documentation f
2f1b0 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  or additional in
2f1c0 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
2f1d0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
2f1e0 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65  sult_blob() inte
2f1f0 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
2f200 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e  esult from.** an
2f210 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2f220 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
2f230 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f   be the BLOB who
2f240 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f  se content is po
2f250 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74  inted.** to by t
2f260 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
2f270 74 65 72 20 61 6e 64 20 77 68 69 63 68 20 69 73  ter and which is
2f280 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68   N bytes long wh
2f290 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20  ere N is the.** 
2f2a0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e  third parameter.
2f2b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2f2c0 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62  te3_result_zerob
2f2d0 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 73  lob() interfaces
2f2e0 20 73 65 74 20 74 68 65 20 72 65 73 75 6c 74 20   set the result 
2f2f0 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
2f300 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
2f310 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 42  nction to be a B
2f320 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61  LOB containing a
2f330 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73  ll zero.** bytes
2f340 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20   and N bytes in 
2f350 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20 69 73  size, where N is
2f360 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
2f370 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  e 2nd parameter.
2f380 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2f390 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c  te3_result_doubl
2f3a0 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  e() interface se
2f3b0 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72  ts the result fr
2f3c0 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61  om.** an applica
2f3d0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
2f3e0 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c  ction to be a fl
2f3f0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
2f400 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20  ue specified.** 
2f410 62 79 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d  by its 2nd argum
2f420 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ent..**.** ^The 
2f430 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2f440 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74  rror() and sqlit
2f450 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
2f460 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a  6() functions.**
2f470 20 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65   cause the imple
2f480 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74  mented SQL funct
2f490 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20  ion to throw an 
2f4a0 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53  exception..** ^S
2f4b0 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73  QLite uses the s
2f4c0 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f  tring pointed to
2f4d0 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70   by the.** 2nd p
2f4e0 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69  arameter of sqli
2f4f0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2f500 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
2f510 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a  sult_error16().*
2f520 2a 20 61 73 20 74 68 65 20 74 65 78 74 20 6f 66  * as the text of
2f530 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
2f540 65 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e 74 65  e.  ^SQLite inte
2f550 72 70 72 65 74 73 20 74 68 65 20 65 72 72 6f 72  rprets the error
2f560 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69  .** message stri
2f570 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ng from sqlite3_
2f580 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61  result_error() a
2f590 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65  s UTF-8. ^SQLite
2f5a0 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74  .** interprets t
2f5b0 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73  he string from s
2f5c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2f5d0 72 6f 72 31 36 28 29 20 61 73 20 55 54 46 2d 31  ror16() as UTF-1
2f5e0 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62  6 in native.** b
2f5f0 79 74 65 20 6f 72 64 65 72 2e 20 20 5e 49 66 20  yte order.  ^If 
2f600 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
2f610 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
2f620 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a  esult_error().**
2f630 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
2f640 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20  lt_error16() is 
2f650 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51  negative then SQ
2f660 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20 74 68  Lite takes as th
2f670 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61  e error.** messa
2f680 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74  ge all text up t
2f690 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74  hrough the first
2f6a0 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e   zero character.
2f6b0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72  .** ^If the thir
2f6c0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
2f6d0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2f6e0 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  ror() or.** sqli
2f6f0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2f700 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  16() is non-nega
2f710 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65  tive then SQLite
2f720 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79   takes that many
2f730 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63  .** bytes (not c
2f740 68 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20  haracters) from 
2f750 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
2f760 72 20 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d  r as the error m
2f770 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20  essage..** ^The 
2f780 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2f790 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74  rror() and sqlit
2f7a0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
2f7b0 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  6().** routines 
2f7c0 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65 20 63  make a private c
2f7d0 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72  opy of the error
2f7e0 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 62 65   message text be
2f7f0 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74  fore.** they ret
2f800 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65  urn.  Hence, the
2f810 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f   calling functio
2f820 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65  n can deallocate
2f830 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68   or.** modify th
2f840 65 20 74 65 78 74 20 61 66 74 65 72 20 74 68 65  e text after the
2f850 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74  y return without
2f860 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73   harm..** ^The s
2f870 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2f880 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74  ror_code() funct
2f890 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20  ion changes the 
2f8a0 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65  error code.** re
2f8b0 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65  turned by SQLite
2f8c0 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20   as a result of 
2f8d0 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75  an error in a fu
2f8e0 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66  nction.  ^By def
2f8f0 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72  ault,.** the err
2f900 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54  or code is SQLIT
2f910 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20 73 75 62  E_ERROR.  ^A sub
2f920 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20  sequent call to 
2f930 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2f940 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  rror().** or sql
2f950 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2f960 72 31 36 28 29 20 72 65 73 65 74 73 20 74 68 65  r16() resets the
2f970 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53   error code to S
2f980 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a  QLITE_ERROR..**.
2f990 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2f9a0 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20  result_toobig() 
2f9b0 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
2f9c0 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77   SQLite to throw
2f9d0 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64   an error.** ind
2f9e0 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 73  icating that a s
2f9f0 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73  tring or BLOB is
2fa00 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70   too long to rep
2fa10 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  resent..**.** ^T
2fa20 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2fa30 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66  t_nomem() interf
2fa40 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74  ace causes SQLit
2fa50 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72  e to throw an er
2fa60 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e  ror.** indicatin
2fa70 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20  g that a memory 
2fa80 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65  allocation faile
2fa90 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
2faa0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
2fab0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
2fac0 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
2fad0 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
2fae0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2faf0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
2fb00 74 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65  the 32-bit signe
2fb10 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c  d integer.** val
2fb20 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20  ue given in the 
2fb30 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
2fb40 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
2fb50 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74  sult_int64() int
2fb60 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
2fb70 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
2fb80 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
2fb90 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2fba0 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34  ion to be the 64
2fbb0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
2fbc0 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76  ger.** value giv
2fbd0 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72  en in the 2nd ar
2fbe0 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gument..**.** ^T
2fbf0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2fc00 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61  t_null() interfa
2fc10 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
2fc20 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
2fc30 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
2fc40 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
2fc50 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  to be NULL..**.*
2fc60 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
2fc70 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71  esult_text(), sq
2fc80 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2fc90 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  t16(),.** sqlite
2fca0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c  3_result_text16l
2fcb0 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33  e(), and sqlite3
2fcc0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65  _result_text16be
2fcd0 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
2fce0 20 73 65 74 20 74 68 65 20 72 65 74 75 72 6e 20   set the return 
2fcf0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70  value of the app
2fd00 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2fd10 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a   function to be.
2fd20 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e 67  ** a text string
2fd30 20 77 68 69 63 68 20 69 73 20 72 65 70 72 65 73   which is repres
2fd40 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20  ented as UTF-8, 
2fd50 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79  UTF-16 native by
2fd60 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46  te order,.** UTF
2fd70 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61  -16 little endia
2fd80 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67  n, or UTF-16 big
2fd90 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74   endian, respect
2fda0 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  ively..** ^SQLit
2fdb0 65 20 74 61 6b 65 73 20 74 68 65 20 74 65 78 74  e takes the text
2fdc0 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65   result from the
2fdd0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f   application fro
2fde0 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72  m.** the 2nd par
2fdf0 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73 71  ameter of the sq
2fe00 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2fe10 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a  t* interfaces..*
2fe20 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61  * ^If the 3rd pa
2fe30 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
2fe40 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
2fe50 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
2fe60 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  * is negative, t
2fe70 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73  hen SQLite takes
2fe80 20 72 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f   result text fro
2fe90 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  m the 2nd parame
2fea0 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74  ter.** through t
2feb0 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68  he first zero ch
2fec0 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20  aracter..** ^If 
2fed0 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
2fee0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
2fef0 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
2ff00 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e  terfaces.** is n
2ff10 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
2ff20 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20  n as many bytes 
2ff30 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29  (not characters)
2ff40 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20   of the text.** 
2ff50 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
2ff60 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
2ff70 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65  are taken as the
2ff80 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2ff90 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ined.** function
2ffa0 20 72 65 73 75 6c 74 2e 20 20 49 66 20 74 68 65   result.  If the
2ffb0 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 69   3rd parameter i
2ffc0 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
2ffd0 74 68 65 6e 20 69 74 0a 2a 2a 20 6d 75 73 74 20  then it.** must 
2ffe0 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73  be the byte offs
2fff0 65 74 20 69 6e 74 6f 20 74 68 65 20 73 74 72 69  et into the stri
30000 6e 67 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c  ng where the NUL
30010 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c   terminator woul
30020 64 0a 2a 2a 20 61 70 70 65 61 72 20 69 66 20 74  d.** appear if t
30030 68 65 20 73 74 72 69 6e 67 20 77 68 65 72 65 20  he string where 
30040 4e 55 4c 20 74 65 72 6d 69 6e 61 74 65 64 2e 20  NUL terminated. 
30050 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72   If any NUL char
30060 61 63 74 65 72 73 20 6f 63 63 75 72 0a 2a 2a 20  acters occur.** 
30070 69 6e 20 74 68 65 20 73 74 72 69 6e 67 20 61 74  in the string at
30080 20 61 20 62 79 74 65 20 6f 66 66 73 65 74 20 74   a byte offset t
30090 68 61 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e  hat is less than
300a0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
300b0 65 20 33 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74  e 3rd.** paramet
300c0 65 72 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73  er, then the res
300d0 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 77 69  ulting string wi
300e0 6c 6c 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64  ll contain embed
300f0 64 65 64 20 4e 55 4c 73 20 61 6e 64 20 74 68 65  ded NULs and the
30100 0a 2a 2a 20 72 65 73 75 6c 74 20 6f 66 20 65 78  .** result of ex
30110 70 72 65 73 73 69 6f 6e 73 20 6f 70 65 72 61 74  pressions operat
30120 69 6e 67 20 6f 6e 20 73 74 72 69 6e 67 73 20 77  ing on strings w
30130 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ith embedded NUL
30140 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  s is undefined..
30150 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70  ** ^If the 4th p
30160 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
30170 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
30180 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
30190 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
301a0 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e  sult_blob is a n
301b0 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c  on-NULL pointer,
301c0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c   then SQLite cal
301d0 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74  ls that.** funct
301e0 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74 72  ion as the destr
301f0 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78  uctor on the tex
30200 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74  t or BLOB result
30210 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20   when it has.** 
30220 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
30230 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e  hat result..** ^
30240 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  If the 4th param
30250 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
30260 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
30270 20 69 6e 74 65 72 66 61 63 65 73 20 6f 72 20 74   interfaces or t
30280 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  o.** sqlite3_res
30290 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20  ult_blob is the 
302a0 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74  special constant
302b0 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20   SQLITE_STATIC, 
302c0 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61  then SQLite.** a
302d0 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20  ssumes that the 
302e0 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73  text or BLOB res
302f0 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61  ult is in consta
30300 6e 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65  nt space and doe
30310 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68  s not.** copy th
30320 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
30330 20 70 61 72 61 6d 65 74 65 72 20 6e 6f 72 20 63   parameter nor c
30340 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72  all a destructor
30350 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a   on the content.
30360 2a 2a 20 77 68 65 6e 20 69 74 20 68 61 73 20 66  ** when it has f
30370 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68  inished using th
30380 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49  at result..** ^I
30390 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
303a0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
303b0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
303c0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72  interfaces.** or
303d0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
303e0 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63  blob is the spec
303f0 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c  ial constant SQL
30400 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a  ITE_TRANSIENT.**
30410 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b   then SQLite mak
30420 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
30430 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61   result into spa
30440 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ce obtained from
30450 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
30460 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f  3_malloc()] befo
30470 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a  re it returns..*
30480 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
30490 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
304a0 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
304b0 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a  the result of.**
304c0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
304d0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
304e0 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74  n to be a copy t
304f0 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  he.** [unprotect
30500 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
30510 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69  ] object specifi
30520 65 64 20 62 79 20 74 68 65 20 32 6e 64 20 70 61  ed by the 2nd pa
30530 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a  rameter.  ^The.*
30540 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
30550 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61  _value() interfa
30560 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  ce makes a copy 
30570 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
30580 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61  value].** so tha
30590 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  t the [sqlite3_v
305a0 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64 20  alue] specified 
305b0 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  in the parameter
305c0 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a   may change or.*
305d0 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  * be deallocated
305e0 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72   after sqlite3_r
305f0 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65  esult_value() re
30600 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61  turns without ha
30610 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65  rm..** ^A [prote
30620 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
30630 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61  ue] object may a
30640 6c 77 61 79 73 20 62 65 20 75 73 65 64 20 77 68  lways be used wh
30650 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f  ere an.** [unpro
30660 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
30670 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20  alue] object is 
30680 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74  required, so eit
30690 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b  her.** kind of [
306a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
306b0 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73 65  bject can be use
306c0 64 20 77 69 74 68 20 74 68 69 73 20 69 6e 74 65  d with this inte
306d0 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  rface..**.** If 
306e0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
306f0 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77  re called from w
30700 69 74 68 69 6e 20 74 68 65 20 64 69 66 66 65 72  ithin the differ
30710 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68  ent thread.** th
30720 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61  an the one conta
30730 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63  ining the applic
30740 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
30750 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65  nction that rece
30760 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  ived.** the [sql
30770 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f  ite3_context] po
30780 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c  inter, the resul
30790 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
307a0 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
307b0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71  3_result_blob(sq
307c0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
307d0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
307e0 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
307f0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
30800 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71  result_double(sq
30810 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
30820 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71  double);.void sq
30830 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
30840 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  or(sqlite3_conte
30850 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  xt*, const char*
30860 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
30870 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
30880 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  r16(sqlite3_cont
30890 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
308a0 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
308b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
308c0 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65  or_toobig(sqlite
308d0 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69  3_context*);.voi
308e0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
308f0 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c  _error_nomem(sql
30900 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
30910 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
30920 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73  ult_error_code(s
30930 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
30940 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
30950 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73  te3_result_int(s
30960 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
30970 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
30980 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34  te3_result_int64
30990 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
309a0 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
309b0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
309c0 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69  result_null(sqli
309d0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76  te3_context*);.v
309e0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
309f0 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  lt_text(sqlite3_
30a00 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
30a10 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  char*, int, void
30a20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
30a30 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
30a40 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
30a50 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
30a60 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
30a70 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
30a80 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
30a90 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65  _text16le(sqlite
30aa0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
30ab0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69  t void*, int,voi
30ac0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
30ad0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
30ae0 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74  t_text16be(sqlit
30af0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
30b00 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f  st void*, int,vo
30b10 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
30b20 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
30b30 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  lt_value(sqlite3
30b40 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74  _context*, sqlit
30b50 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64  e3_value*);.void
30b60 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
30b70 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33  zeroblob(sqlite3
30b80 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e  _context*, int n
30b90 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
30ba0 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43  EF: Define New C
30bb0 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63  ollating Sequenc
30bc0 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  es.**.** ^These 
30bd0 66 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c 20 72  functions add, r
30be0 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 66 79  emove, or modify
30bf0 20 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61   a [collation] a
30c00 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74  ssociated.** wit
30c10 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
30c20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63  connection] spec
30c30 69 66 69 65 64 20 61 73 20 74 68 65 20 66 69 72  ified as the fir
30c40 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  st argument..**.
30c50 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
30c60 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73  the collation is
30c70 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a   a UTF-8 string.
30c80 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63  ** for sqlite3_c
30c90 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
30ca0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72  ) and sqlite3_cr
30cb0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
30cc0 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46  2().** and a UTF
30cd0 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61  -16 string in na
30ce0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
30cf0 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61  for sqlite3_crea
30d00 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29  te_collation16()
30d10 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20  ..** ^Collation 
30d20 6e 61 6d 65 73 20 74 68 61 74 20 63 6f 6d 70 61  names that compa
30d30 72 65 20 65 71 75 61 6c 20 61 63 63 6f 72 64 69  re equal accordi
30d40 6e 67 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ng to [sqlite3_s
30d50 74 72 6e 69 63 6d 70 28 29 5d 20 61 72 65 0a 2a  trnicmp()] are.*
30d60 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 20  * considered to 
30d70 62 65 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  be the same name
30d80 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 74 68  ..**.** ^(The th
30d90 69 72 64 20 61 72 67 75 6d 65 6e 74 20 28 65 54  ird argument (eT
30da0 65 78 74 52 65 70 29 20 6d 75 73 74 20 62 65 20  extRep) must be 
30db0 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74  one of the const
30dc0 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  ants:.** <ul>.**
30dd0 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54   <li> [SQLITE_UT
30de0 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  F8],.** <li> [SQ
30df0 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a  LITE_UTF16LE],.*
30e00 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55  * <li> [SQLITE_U
30e10 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e  TF16BE],.** <li>
30e20 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c   [SQLITE_UTF16],
30e30 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c   or.** <li> [SQL
30e40 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45  ITE_UTF16_ALIGNE
30e50 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a  D]..** </ul>)^.*
30e60 2a 20 5e 54 68 65 20 65 54 65 78 74 52 65 70 20  * ^The eTextRep 
30e70 61 72 67 75 6d 65 6e 74 20 64 65 74 65 72 6d 69  argument determi
30e80 6e 65 73 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  nes the encoding
30e90 20 6f 66 20 73 74 72 69 6e 67 73 20 70 61 73 73   of strings pass
30ea0 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6c  ed.** to the col
30eb0 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
30ec0 63 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c 6c 62  callback, xCallb
30ed0 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ack..** ^The [SQ
30ee0 4c 49 54 45 5f 55 54 46 31 36 5d 20 61 6e 64 20  LITE_UTF16] and 
30ef0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c  [SQLITE_UTF16_AL
30f00 49 47 4e 45 44 5d 20 76 61 6c 75 65 73 20 66 6f  IGNED] values fo
30f10 72 20 65 54 65 78 74 52 65 70 0a 2a 2a 20 66 6f  r eTextRep.** fo
30f20 72 63 65 20 73 74 72 69 6e 67 73 20 74 6f 20 62  rce strings to b
30f30 65 20 55 54 46 31 36 20 77 69 74 68 20 6e 61 74  e UTF16 with nat
30f40 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
30f50 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
30f60 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76  UTF16_ALIGNED] v
30f70 61 6c 75 65 20 66 6f 72 20 65 54 65 78 74 52 65  alue for eTextRe
30f80 70 20 66 6f 72 63 65 73 20 73 74 72 69 6e 67 73  p forces strings
30f90 20 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20   to begin.** on 
30fa0 61 6e 20 65 76 65 6e 20 62 79 74 65 20 61 64 64  an even byte add
30fb0 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ress..**.** ^The
30fc0 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
30fd0 2c 20 70 41 72 67 2c 20 69 73 20 61 6e 20 61 70  , pArg, is an ap
30fe0 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
30ff0 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 70  ointer that is p
31000 61 73 73 65 64 0a 2a 2a 20 74 68 72 6f 75 67 68  assed.** through
31010 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
31020 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 6f  gument to the co
31030 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
31040 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
31050 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75   ^The fifth argu
31060 6d 65 6e 74 2c 20 78 43 61 6c 6c 62 61 63 6b 2c  ment, xCallback,
31070 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
31080 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   the collating f
31090 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c  unction..** ^Mul
310a0 74 69 70 6c 65 20 63 6f 6c 6c 61 74 69 6e 67 20  tiple collating 
310b0 66 75 6e 63 74 69 6f 6e 73 20 63 61 6e 20 62 65  functions can be
310c0 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e   registered usin
310d0 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20  g the same name 
310e0 62 75 74 0a 2a 2a 20 77 69 74 68 20 64 69 66 66  but.** with diff
310f0 65 72 65 6e 74 20 65 54 65 78 74 52 65 70 20 70  erent eTextRep p
31100 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 53 51  arameters and SQ
31110 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 77 68  Lite will use wh
31120 69 63 68 65 76 65 72 0a 2a 2a 20 66 75 6e 63 74  ichever.** funct
31130 69 6f 6e 20 72 65 71 75 69 72 65 73 20 74 68 65  ion requires the
31140 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66   least amount of
31150 20 64 61 74 61 20 74 72 61 6e 73 66 6f 72 6d 61   data transforma
31160 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  tion..** ^If the
31170 20 78 43 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d   xCallback argum
31180 65 6e 74 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e  ent is NULL then
31190 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   the collating f
311a0 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65  unction is.** de
311b0 6c 65 74 65 64 2e 20 20 5e 57 68 65 6e 20 61 6c  leted.  ^When al
311c0 6c 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  l collating func
311d0 74 69 6f 6e 73 20 68 61 76 69 6e 67 20 74 68 65  tions having the
311e0 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 64   same name are d
311f0 65 6c 65 74 65 64 2c 0a 2a 2a 20 74 68 61 74 20  eleted,.** that 
31200 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 20  collation is no 
31210 6c 6f 6e 67 65 72 20 75 73 61 62 6c 65 2e 0a 2a  longer usable..*
31220 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c 61 74  *.** ^The collat
31230 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c  ing function cal
31240 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
31250 20 77 69 74 68 20 61 20 63 6f 70 79 20 6f 66 20   with a copy of 
31260 74 68 65 20 70 41 72 67 20 0a 2a 2a 20 61 70 70  the pArg .** app
31270 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
31280 69 6e 74 65 72 20 61 6e 64 20 77 69 74 68 20 74  inter and with t
31290 77 6f 20 73 74 72 69 6e 67 73 20 69 6e 20 74 68  wo strings in th
312a0 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69  e encoding speci
312b0 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 65  fied.** by the e
312c0 54 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74  TextRep argument
312d0 2e 20 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67  .  The collating
312e0 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 72   function must r
312f0 65 74 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65  eturn an.** inte
31300 67 65 72 20 74 68 61 74 20 69 73 20 6e 65 67 61  ger that is nega
31310 74 69 76 65 2c 20 7a 65 72 6f 2c 20 6f 72 20 70  tive, zero, or p
31320 6f 73 69 74 69 76 65 0a 2a 2a 20 69 66 20 74 68  ositive.** if th
31330 65 20 66 69 72 73 74 20 73 74 72 69 6e 67 20 69  e first string i
31340 73 20 6c 65 73 73 20 74 68 61 6e 2c 20 65 71 75  s less than, equ
31350 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65  al to, or greate
31360 72 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e  r than the secon
31370 64 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65  d,.** respective
31380 6c 79 2e 20 20 41 20 63 6f 6c 6c 61 74 69 6e 67  ly.  A collating
31390 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 61   function must a
313a0 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74 68 65  lways return the
313b0 20 73 61 6d 65 20 61 6e 73 77 65 72 0a 2a 2a 20   same answer.** 
313c0 67 69 76 65 6e 20 74 68 65 20 73 61 6d 65 20 69  given the same i
313d0 6e 70 75 74 73 2e 20 20 49 66 20 74 77 6f 20 6f  nputs.  If two o
313e0 72 20 6d 6f 72 65 20 63 6f 6c 6c 61 74 69 6e 67  r more collating
313f0 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 72   functions are r
31400 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 74 6f 20  egistered.** to 
31410 74 68 65 20 73 61 6d 65 20 63 6f 6c 6c 61 74 69  the same collati
31420 6f 6e 20 6e 61 6d 65 20 28 75 73 69 6e 67 20 64  on name (using d
31430 69 66 66 65 72 65 6e 74 20 65 54 65 78 74 52 65  ifferent eTextRe
31440 70 20 76 61 6c 75 65 73 29 20 74 68 65 6e 20 61  p values) then a
31450 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67 69 76 65 20  ll.** must give 
31460 61 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e  an equivalent an
31470 73 77 65 72 20 77 68 65 6e 20 69 6e 76 6f 6b 65  swer when invoke
31480 64 20 77 69 74 68 20 65 71 75 69 76 61 6c 65 6e  d with equivalen
31490 74 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68  t strings..** Th
314a0 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
314b0 74 69 6f 6e 20 6d 75 73 74 20 6f 62 65 79 20 74  tion must obey t
314c0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f  he following pro
314d0 70 65 72 74 69 65 73 20 66 6f 72 20 61 6c 6c 0a  perties for all.
314e0 2a 2a 20 73 74 72 69 6e 67 73 20 41 2c 20 42 2c  ** strings A, B,
314f0 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f   and C:.**.** <o
31500 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d  l>.** <li> If A=
31510 3d 42 20 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a  =B then B==A..**
31520 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 61 6e   <li> If A==B an
31530 64 20 42 3d 3d 43 20 74 68 65 6e 20 41 3d 3d 43  d B==C then A==C
31540 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c  ..** <li> If A&l
31550 74 3b 42 20 54 48 45 4e 20 42 26 67 74 3b 41 2e  t;B THEN B&gt;A.
31560 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74  .** <li> If A&lt
31570 3b 42 20 61 6e 64 20 42 26 6c 74 3b 43 20 74 68  ;B and B&lt;C th
31580 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f  en A&lt;C..** </
31590 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63  ol>.**.** If a c
315a0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
315b0 6e 20 66 61 69 6c 73 20 61 6e 79 20 6f 66 20 74  n fails any of t
315c0 68 65 20 61 62 6f 76 65 20 63 6f 6e 73 74 72 61  he above constra
315d0 69 6e 74 73 20 61 6e 64 20 74 68 61 74 0a 2a 2a  ints and that.**
315e0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
315f0 69 6f 6e 20 69 73 20 20 72 65 67 69 73 74 65 72  ion is  register
31600 65 64 20 61 6e 64 20 75 73 65 64 2c 20 74 68 65  ed and used, the
31610 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  n the behavior o
31620 66 20 53 51 4c 69 74 65 0a 2a 2a 20 69 73 20 75  f SQLite.** is u
31630 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
31640 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65  ^The sqlite3_cre
31650 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
31660 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71  () works like sq
31670 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
31680 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 77 69 74 68  lation().** with
31690 20 74 68 65 20 61 64 64 69 74 69 6f 6e 20 74 68   the addition th
316a0 61 74 20 74 68 65 20 78 44 65 73 74 72 6f 79 20  at the xDestroy 
316b0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
316c0 6b 65 64 20 6f 6e 20 70 41 72 67 20 77 68 65 6e  ked on pArg when
316d0 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e  .** the collatin
316e0 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65  g function is de
316f0 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61  leted..** ^Colla
31700 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61  ting functions a
31710 72 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  re deleted when 
31720 74 68 65 79 20 61 72 65 20 6f 76 65 72 72 69 64  they are overrid
31730 64 65 6e 20 62 79 20 6c 61 74 65 72 0a 2a 2a 20  den by later.** 
31740 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c  calls to the col
31750 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  lation creation 
31760 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65  functions or whe
31770 6e 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61  n the.** [databa
31780 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69  se connection] i
31790 73 20 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b  s closed using [
317a0 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
317b0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 44 65  ..**.** ^The xDe
317c0 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69  stroy callback i
317d0 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c  s <u>not</u> cal
317e0 6c 65 64 20 69 66 20 74 68 65 20 0a 2a 2a 20 73  led if the .** s
317f0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
31800 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 66 75 6e  llation_v2() fun
31810 63 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 41 70  ction fails.  Ap
31820 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
31830 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
31840 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
31850 6f 6e 5f 76 32 28 29 20 77 69 74 68 20 61 20 6e  on_v2() with a n
31860 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73 74 72 6f 79  on-NULL xDestroy
31870 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
31880 20 0a 2a 2a 20 63 68 65 63 6b 20 74 68 65 20 72   .** check the r
31890 65 74 75 72 6e 20 63 6f 64 65 20 61 6e 64 20 64  eturn code and d
318a0 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 61 70  ispose of the ap
318b0 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
318c0 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6d 73 65  ointer.** themse
318d0 6c 76 65 73 20 72 61 74 68 65 72 20 74 68 61 6e  lves rather than
318e0 20 65 78 70 65 63 74 69 6e 67 20 53 51 4c 69 74   expecting SQLit
318f0 65 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20 69  e to deal with i
31900 74 20 66 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20 54  t for them..** T
31910 68 69 73 20 69 73 20 64 69 66 66 65 72 65 6e 74  his is different
31920 20 66 72 6f 6d 20 65 76 65 72 79 20 6f 74 68 65   from every othe
31930 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
31940 63 65 2e 20 20 54 68 65 20 69 6e 63 6f 6e 73 69  ce.  The inconsi
31950 73 74 65 6e 63 79 20 0a 2a 2a 20 69 73 20 75 6e  stency .** is un
31960 66 6f 72 74 75 6e 61 74 65 20 62 75 74 20 63 61  fortunate but ca
31970 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20  nnot be changed 
31980 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67  without breaking
31990 20 62 61 63 6b 77 61 72 64 73 20 0a 2a 2a 20 63   backwards .** c
319a0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
319b0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b  .** See also:  [
319c0 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
319d0 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 20  n_needed()] and 
319e0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69  [sqlite3_collati
319f0 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a  on_needed16()]..
31a00 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
31a10 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
31a20 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
31a30 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
31a40 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52  e, .  int eTextR
31a50 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72  ep, .  void *pAr
31a60 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61  g,.  int(*xCompa
31a70 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  re)(void*,int,co
31a80 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  nst void*,int,co
31a90 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e  nst void*).);.in
31aa0 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
31ab0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20  _collation_v2(. 
31ac0 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f   sqlite3*, .  co
31ad0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
31ae0 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70   .  int eTextRep
31af0 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c  , .  void *pArg,
31b00 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65  .  int(*xCompare
31b10 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
31b20 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  t void*,int,cons
31b30 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64  t void*),.  void
31b40 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64  (*xDestroy)(void
31b50 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
31b60 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
31b70 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a  on16(.  sqlite3*
31b80 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  , .  const void 
31b90 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54  *zName,.  int eT
31ba0 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20  extRep, .  void 
31bb0 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43  *pArg,.  int(*xC
31bc0 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e  ompare)(void*,in
31bd0 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e  t,const void*,in
31be0 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29  t,const void*).)
31bf0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
31c00 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65  F: Collation Nee
31c10 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ded Callbacks.**
31c20 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69 64 20 68 61  .** ^To avoid ha
31c30 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74 65 72  ving to register
31c40 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73   all collation s
31c50 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72 65 20  equences before 
31c60 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 61  a database.** ca
31c70 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73 69 6e  n be used, a sin
31c80 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  gle callback fun
31c90 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67  ction may be reg
31ca0 69 73 74 65 72 65 64 20 77 69 74 68 20 74 68 65  istered with the
31cb0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
31cc0 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20  nnection] to be 
31cd0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
31ce0 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 6f   an undefined co
31cf0 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65  llation.** seque
31d00 6e 63 65 20 69 73 20 72 65 71 75 69 72 65 64 2e  nce is required.
31d10 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .**.** ^If the f
31d20 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73  unction is regis
31d30 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  tered using the 
31d40 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
31d50 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a  n_needed() API,.
31d60 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70 61  ** then it is pa
31d70 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f  ssed the names o
31d80 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c  f undefined coll
31d90 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
31da0 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e  as strings.** en
31db0 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20  coded in UTF-8. 
31dc0 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  ^If sqlite3_coll
31dd0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29  ation_needed16()
31de0 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65   is used,.** the
31df0 20 6e 61 6d 65 73 20 61 72 65 20 70 61 73 73 65   names are passe
31e00 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d  d as UTF-16 in m
31e10 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79  achine native by
31e20 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41 20  te order..** ^A 
31e30 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 66  call to either f
31e40 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73  unction replaces
31e50 20 74 68 65 20 65 78 69 73 74 69 6e 67 20 63 6f   the existing co
31e60 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64 65 64 20 63  llation-needed c
31e70 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e  allback..**.** ^
31e80 28 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61  (When the callba
31e90 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74  ck is invoked, t
31ea0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
31eb0 74 20 70 61 73 73 65 64 20 69 73 20 61 20 63 6f  t passed is a co
31ec0 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63  py.** of the sec
31ed0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
31ee0 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
31ef0 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a  n_needed() or.**
31f00 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
31f10 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 20  on_needed16().  
31f20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
31f30 65 6e 74 20 69 73 20 74 68 65 20 64 61 74 61 62  ent is the datab
31f40 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
31f50 6e 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72  n.  The third ar
31f60 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66  gument is one of
31f70 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20   [SQLITE_UTF8], 
31f80 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
31f90 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ,.** or [SQLITE_
31fa0 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61  UTF16LE], indica
31fb0 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 65  ting the most de
31fc0 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20  sirable form of 
31fd0 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a  the collation.**
31fe0 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69   sequence functi
31ff0 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 20 54 68  on required.  Th
32000 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
32010 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  er is the name o
32020 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65  f the.** require
32030 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  d collation sequ
32040 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  ence.)^.**.** Th
32050 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
32060 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73  ion should regis
32070 74 65 72 20 74 68 65 20 64 65 73 69 72 65 64 20  ter the desired 
32080 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a  collation using.
32090 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ** [sqlite3_crea
320a0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c  te_collation()],
320b0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
320c0 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c  _collation16()],
320d0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
320e0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
320f0 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  _v2()]..*/.int s
32100 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
32110 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74  _needed(.  sqlit
32120 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a  e3*, .  void*, .
32130 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c    void(*)(void*,
32140 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65  sqlite3*,int eTe
32150 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72  xtRep,const char
32160 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
32170 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
32180 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a  ed16(.  sqlite3*
32190 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f  , .  void*,.  vo
321a0 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
321b0 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65  te3*,int eTextRe
321c0 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29  p,const void*).)
321d0 3b 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  ;..#ifdef SQLITE
321e0 5f 48 41 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a  _HAS_CODEC./*.**
321f0 20 53 70 65 63 69 66 79 20 74 68 65 20 6b 65 79   Specify the key
32200 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74 65   for an encrypte
32210 64 20 64 61 74 61 62 61 73 65 2e 20 20 54 68 69  d database.  Thi
32220 73 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64  s routine should
32230 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69   be.** called ri
32240 67 68 74 20 61 66 74 65 72 20 73 71 6c 69 74 65  ght after sqlite
32250 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20  3_open()..**.** 
32260 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c  The code to impl
32270 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69  ement this API i
32280 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20  s not available 
32290 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65  in the public re
322a0 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69  lease.** of SQLi
322b0 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  te..*/.int sqlit
322c0 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 65  e3_key(.  sqlite
322d0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
322e0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
322f0 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79  base to be rekey
32300 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  ed */.  const vo
32310 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b  id *pKey, int nK
32320 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65  ey     /* The ke
32330 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  y */.);../*.** C
32340 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f 6e  hange the key on
32350 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   an open databas
32360 65 2e 20 20 49 66 20 74 68 65 20 63 75 72 72 65  e.  If the curre
32370 6e 74 20 64 61 74 61 62 61 73 65 20 69 73 20 6e  nt database is n
32380 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c  ot.** encrypted,
32390 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
323a0 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20 20  ll encrypt it.  
323b0 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e  If pNew==0 or nN
323c0 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61  ew==0, the.** da
323d0 74 61 62 61 73 65 20 69 73 20 64 65 63 72 79 70  tabase is decryp
323e0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ted..**.** The c
323f0 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  ode to implement
32400 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74   this API is not
32410 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68   available in th
32420 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65  e public release
32430 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  .** of SQLite..*
32440 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  /.int sqlite3_re
32450 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  key(.  sqlite3 *
32460 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
32470 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
32480 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20  e to be rekeyed 
32490 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
324a0 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20  *pKey, int nKey 
324b0 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b      /* The new k
324c0 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ey */.);../*.** 
324d0 53 70 65 63 69 66 79 20 74 68 65 20 61 63 74 69  Specify the acti
324e0 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61  vation key for a
324f0 20 53 45 45 20 64 61 74 61 62 61 73 65 2e 20 20   SEE database.  
32500 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76  Unless .** activ
32510 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68  ated, none of th
32520 65 20 53 45 45 20 72 6f 75 74 69 6e 65 73 20 77  e SEE routines w
32530 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69  ill work..*/.voi
32540 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61  d sqlite3_activa
32550 74 65 5f 73 65 65 28 0a 20 20 63 6f 6e 73 74 20  te_see(.  const 
32560 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73  char *zPassPhras
32570 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69  e        /* Acti
32580 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f  vation phrase */
32590 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64  .);.#endif..#ifd
325a0 65 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  ef SQLITE_ENABLE
325b0 5f 43 45 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65  _CEROD./*.** Spe
325c0 63 69 66 79 20 74 68 65 20 61 63 74 69 76 61 74  cify the activat
325d0 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 43 45  ion key for a CE
325e0 52 4f 44 20 64 61 74 61 62 61 73 65 2e 20 20 55  ROD database.  U
325f0 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61  nless .** activa
32600 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65  ted, none of the
32610 20 43 45 52 4f 44 20 72 6f 75 74 69 6e 65 73 20   CEROD routines 
32620 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f  will work..*/.vo
32630 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76  id sqlite3_activ
32640 61 74 65 5f 63 65 72 6f 64 28 0a 20 20 63 6f 6e  ate_cerod(.  con
32650 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68  st char *zPassPh
32660 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41  rase        /* A
32670 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65  ctivation phrase
32680 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f   */.);.#endif../
32690 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
326a0 75 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e  uspend Execution
326b0 20 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d   For A Short Tim
326c0 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  e.**.** The sqli
326d0 74 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e 63  te3_sleep() func
326e0 74 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65 20  tion causes the 
326f0 63 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 74  current thread t
32700 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74  o suspend execut
32710 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65  ion.** for at le
32720 61 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20  ast a number of 
32730 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65  milliseconds spe
32740 63 69 66 69 65 64 20 69 6e 20 69 74 73 20 70 61  cified in its pa
32750 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49  rameter..**.** I
32760 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  f the operating 
32770 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20  system does not 
32780 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65  support sleep re
32790 71 75 65 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d  quests with.** m
327a0 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20  illisecond time 
327b0 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e  resolution, then
327c0 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62   the time will b
327d0 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a  e rounded up to.
327e0 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20 73  ** the nearest s
327f0 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65  econd. The numbe
32800 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
32810 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61  s of sleep actua
32820 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74 65 64  lly.** requested
32830 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74   from the operat
32840 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72 65  ing system is re
32850 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53  turned..**.** ^S
32860 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73  QLite implements
32870 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
32880 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78  by calling the x
32890 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f  Sleep().** metho
328a0 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74  d of the default
328b0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
328c0 62 6a 65 63 74 2e 20 20 49 66 20 74 68 65 20 78  bject.  If the x
328d0 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 0a 2a  Sleep() method.*
328e0 2a 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74  * of the default
328f0 20 56 46 53 20 69 73 20 6e 6f 74 20 69 6d 70 6c   VFS is not impl
32900 65 6d 65 6e 74 65 64 20 63 6f 72 72 65 63 74 6c  emented correctl
32910 79 2c 20 6f 72 20 6e 6f 74 20 69 6d 70 6c 65 6d  y, or not implem
32920 65 6e 74 65 64 20 61 74 0a 2a 2a 20 61 6c 6c 2c  ented at.** all,
32930 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
32940 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6c  or of sqlite3_sl
32950 65 65 70 28 29 20 6d 61 79 20 64 65 76 69 61 74  eep() may deviat
32960 65 20 66 72 6f 6d 20 74 68 65 20 64 65 73 63 72  e from the descr
32970 69 70 74 69 6f 6e 0a 2a 2a 20 69 6e 20 74 68 65  iption.** in the
32980 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72   previous paragr
32990 61 70 68 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  aphs..*/.int sql
329a0 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b  ite3_sleep(int);
329b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
329c0 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f  : Name Of The Fo
329d0 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d  lder Holding Tem
329e0 70 6f 72 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a  porary Files.**.
329f0 2a 2a 20 5e 28 49 66 20 74 68 69 73 20 67 6c 6f  ** ^(If this glo
32a00 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20  bal variable is 
32a10 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f  made to point to
32a20 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 20   a string which 
32a30 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f  is.** the name o
32a40 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e  f a folder (a.k.
32a50 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74  a. directory), t
32a60 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72  hen all temporar
32a70 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74  y files.** creat
32a80 65 64 20 62 79 20 53 51 4c 69 74 65 20 77 68 65  ed by SQLite whe
32a90 6e 20 75 73 69 6e 67 20 61 20 62 75 69 6c 74 2d  n using a built-
32aa0 69 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20  in [sqlite3_vfs 
32ab0 7c 20 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62  | VFS].** will b
32ac0 65 20 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74  e placed in that
32ad0 20 64 69 72 65 63 74 6f 72 79 2e 29 5e 20 20 5e   directory.)^  ^
32ae0 49 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  If this variable
32af0 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  .** is a NULL po
32b00 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69  inter, then SQLi
32b10 74 65 20 70 65 72 66 6f 72 6d 73 20 61 20 73 65  te performs a se
32b20 61 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72  arch for an appr
32b30 6f 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f  opriate.** tempo
32b40 72 61 72 79 20 66 69 6c 65 20 64 69 72 65 63 74  rary file direct
32b50 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73  ory..**.** It is
32b60 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61   not safe to rea
32b70 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73  d or modify this
32b80 20 76 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72   variable in mor
32b90 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68  e than one.** th
32ba0 72 65 61 64 20 61 74 20 61 20 74 69 6d 65 2e 20  read at a time. 
32bb0 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20   It is not safe 
32bc0 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66  to read or modif
32bd0 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a  y this variable.
32be0 2a 2a 20 69 66 20 61 20 5b 64 61 74 61 62 61 73  ** if a [databas
32bf0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73  e connection] is
32c00 20 62 65 69 6e 67 20 75 73 65 64 20 61 74 20 74   being used at t
32c10 68 65 20 73 61 6d 65 20 74 69 6d 65 20 69 6e 20  he same time in 
32c20 61 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 74 68  a separate.** th
32c30 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69  read..** It is i
32c40 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74 68 69  ntended that thi
32c50 73 20 76 61 72 69 61 62 6c 65 20 62 65 20 73 65  s variable be se
32c60 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72  t once.** as par
32c70 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69  t of process ini
32c80 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20  tialization and 
32c90 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74  before any SQLit
32ca0 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72  e interface.** r
32cb0 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62 65 65  outines have bee
32cc0 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20 74 68 61  n called and tha
32cd0 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  t this variable 
32ce0 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64  remain unchanged
32cf0 0a 2a 2a 20 74 68 65 72 65 61 66 74 65 72 2e 0a  .** thereafter..
32d00 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74 65 6d 70  **.** ^The [temp
32d10 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
32d20 20 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64   pragma] may mod
32d30 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c  ify this variabl
32d40 65 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69  e and cause.** i
32d50 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65  t to point to me
32d60 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
32d70 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
32d80 6f 63 5d 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f  oc].  ^Furthermo
32d90 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70  re,.** the [temp
32da0 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
32db0 20 70 72 61 67 6d 61 5d 20 61 6c 77 61 79 73 20   pragma] always 
32dc0 61 73 73 75 6d 65 73 20 74 68 61 74 20 61 6e 79  assumes that any
32dd0 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20   string.** that 
32de0 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 70 6f  this variable po
32df0 69 6e 74 73 20 74 6f 20 69 73 20 68 65 6c 64 20  ints to is held 
32e00 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  in memory obtain
32e10 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c  ed from .** [sql
32e20 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64  ite3_malloc] and
32e30 20 74 68 65 20 70 72 61 67 6d 61 20 6d 61 79 20   the pragma may 
32e40 61 74 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20  attempt to free 
32e50 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75  that memory.** u
32e60 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72  sing [sqlite3_fr
32e70 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69  ee]..** Hence, i
32e80 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  f this variable 
32e90 69 73 20 6d 6f 64 69 66 69 65 64 20 64 69 72 65  is modified dire
32ea0 63 74 6c 79 2c 20 65 69 74 68 65 72 20 69 74 20  ctly, either it 
32eb0 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64  should be.** mad
32ec0 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74  e NULL or made t
32ed0 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72  o point to memor
32ee0 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
32ef0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d  [sqlite3_malloc]
32f00 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74 68 65 20  .** or else the 
32f10 75 73 65 20 6f 66 20 74 68 65 20 5b 74 65 6d 70  use of the [temp
32f20 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
32f30 20 70 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20   pragma] should 
32f40 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53  be avoided..*/.S
32f50 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61  QLITE_EXTERN cha
32f60 72 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f  r *sqlite3_temp_
32f70 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a  directory;../*.*
32f80 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 74  * CAPI3REF: Test
32f90 20 46 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74   For Auto-Commit
32fa0 20 4d 6f 64 65 0a 2a 2a 20 4b 45 59 57 4f 52 44   Mode.** KEYWORD
32fb0 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d  S: {autocommit m
32fc0 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ode}.**.** ^The 
32fd0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f  sqlite3_get_auto
32fe0 63 6f 6d 6d 69 74 28 29 20 69 6e 74 65 72 66 61  commit() interfa
32ff0 63 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ce returns non-z
33000 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69  ero or.** zero i
33010 66 20 74 68 65 20 67 69 76 65 6e 20 64 61 74 61  f the given data
33020 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
33030 69 73 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20  is or is not in 
33040 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c  autocommit mode,
33050 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79  .** respectively
33060 2e 20 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d  .  ^Autocommit m
33070 6f 64 65 20 69 73 20 6f 6e 20 62 79 20 64 65 66  ode is on by def
33080 61 75 6c 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f  ault..** ^Autoco
33090 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73  mmit mode is dis
330a0 61 62 6c 65 64 20 62 79 20 61 20 5b 42 45 47 49  abled by a [BEGI
330b0 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  N] statement..**
330c0 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64   ^Autocommit mod
330d0 65 20 69 73 20 72 65 2d 65 6e 61 62 6c 65 64 20  e is re-enabled 
330e0 62 79 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72  by a [COMMIT] or
330f0 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a   [ROLLBACK]..**.
33100 2a 2a 20 49 66 20 63 65 72 74 61 69 6e 20 6b 69  ** If certain ki
33110 6e 64 73 20 6f 66 20 65 72 72 6f 72 73 20 6f 63  nds of errors oc
33120 63 75 72 20 6f 6e 20 61 20 73 74 61 74 65 6d 65  cur on a stateme
33130 6e 74 20 77 69 74 68 69 6e 20 61 20 6d 75 6c 74  nt within a mult
33140 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74  i-statement.** t
33150 72 61 6e 73 61 63 74 69 6f 6e 20 28 65 72 72 6f  ransaction (erro
33160 72 73 20 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51  rs including [SQ
33170 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c  LITE_FULL], [SQL
33180 49 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b  ITE_IOERR],.** [
33190 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b  SQLITE_NOMEM], [
331a0 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e  SQLITE_BUSY], an
331b0 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  d [SQLITE_INTERR
331c0 55 50 54 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a  UPT]) then the.*
331d0 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69  * transaction mi
331e0 67 68 74 20 62 65 20 72 6f 6c 6c 65 64 20 62 61  ght be rolled ba
331f0 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ck automatically
33200 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77 61 79 20  .  The only way 
33210 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77  to.** find out w
33220 68 65 74 68 65 72 20 53 51 4c 69 74 65 20 61 75  hether SQLite au
33230 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c  tomatically roll
33240 65 64 20 62 61 63 6b 20 74 68 65 20 74 72 61 6e  ed back the tran
33250 73 61 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a  saction after.**
33260 20 61 6e 20 65 72 72 6f 72 20 69 73 20 74 6f 20   an error is to 
33270 75 73 65 20 74 68 69 73 20 66 75 6e 63 74 69 6f  use this functio
33280 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74  n..**.** If anot
33290 68 65 72 20 74 68 72 65 61 64 20 63 68 61 6e 67  her thread chang
332a0 65 73 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69  es the autocommi
332b0 74 20 73 74 61 74 75 73 20 6f 66 20 74 68 65 20  t status of the 
332c0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
332d0 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 69  ection while thi
332e0 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e  s routine is run
332f0 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72  ning, then the r
33300 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69  eturn value.** i
33310 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  s undefined..*/.
33320 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  int sqlite3_get_
33330 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74  autocommit(sqlit
33340 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
33350 49 33 52 45 46 3a 20 46 69 6e 64 20 54 68 65 20  I3REF: Find The 
33360 44 61 74 61 62 61 73 65 20 48 61 6e 64 6c 65 20  Database Handle 
33370 4f 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74  Of A Prepared St
33380 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54  atement.**.** ^T
33390 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  he sqlite3_db_ha
333a0 6e 64 6c 65 20 69 6e 74 65 72 66 61 63 65 20 72  ndle interface r
333b0 65 74 75 72 6e 73 20 74 68 65 20 5b 64 61 74 61  eturns the [data
333c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
333d0 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 68   handle.** to wh
333e0 69 63 68 20 61 20 5b 70 72 65 70 61 72 65 64 20  ich a [prepared 
333f0 73 74 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e  statement] belon
33400 67 73 2e 20 20 5e 54 68 65 20 5b 64 61 74 61 62  gs.  ^The [datab
33410 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a  ase connection].
33420 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ** returned by s
33430 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65  qlite3_db_handle
33440 20 69 73 20 74 68 65 20 73 61 6d 65 20 5b 64 61   is the same [da
33450 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
33460 6e 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 74  n].** that was t
33470 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
33480 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c  t.** to the [sql
33490 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
334a0 29 5d 20 63 61 6c 6c 20 28 6f 72 20 69 74 73 20  )] call (or its 
334b0 76 61 72 69 61 6e 74 73 29 20 74 68 61 74 20 77  variants) that w
334c0 61 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72  as used to.** cr
334d0 65 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65  eate the stateme
334e0 6e 74 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  nt in the first 
334f0 70 6c 61 63 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65  place..*/.sqlite
33500 33 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  3 *sqlite3_db_ha
33510 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  ndle(sqlite3_stm
33520 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
33530 33 52 45 46 3a 20 46 69 6e 64 20 74 68 65 20 6e  3REF: Find the n
33540 65 78 74 20 70 72 65 70 61 72 65 64 20 73 74 61  ext prepared sta
33550 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  tement.**.** ^Th
33560 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  is interface ret
33570 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
33580 6f 20 74 68 65 20 6e 65 78 74 20 5b 70 72 65 70  o the next [prep
33590 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
335a0 61 66 74 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61  after.** pStmt a
335b0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
335c0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
335d0 6e 65 63 74 69 6f 6e 5d 20 70 44 62 2e 20 20 5e  nection] pDb.  ^
335e0 49 66 20 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c  If pStmt is NULL
335f0 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 69 6e  .** then this in
33600 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
33610 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
33620 20 66 69 72 73 74 20 70 72 65 70 61 72 65 64 20   first prepared 
33630 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73  statement.** ass
33640 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
33650 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
33660 74 69 6f 6e 20 70 44 62 2e 20 20 5e 49 66 20 6e  tion pDb.  ^If n
33670 6f 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  o prepared state
33680 6d 65 6e 74 0a 2a 2a 20 73 61 74 69 73 66 69 65  ment.** satisfie
33690 73 20 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73  s the conditions
336a0 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
336b0 2c 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c  , it returns NUL
336c0 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64 61  L..**.** The [da
336d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
336e0 6e 5d 20 70 6f 69 6e 74 65 72 20 44 20 69 6e 20  n] pointer D in 
336f0 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  a call to.** [sq
33700 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
33710 44 2c 53 29 5d 20 6d 75 73 74 20 72 65 66 65 72  D,S)] must refer
33720 20 74 6f 20 61 6e 20 6f 70 65 6e 20 64 61 74 61   to an open data
33730 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
33740 6f 6e 20 61 6e 64 20 69 6e 20 70 61 72 74 69 63  on and in partic
33750 75 6c 61 72 20 6d 75 73 74 20 6e 6f 74 20 62 65  ular must not be
33760 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
33770 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 73 74 6d 74  .*/.sqlite3_stmt
33780 20 2a 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   *sqlite3_next_s
33790 74 6d 74 28 73 71 6c 69 74 65 33 20 2a 70 44 62  tmt(sqlite3 *pDb
337a0 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  , sqlite3_stmt *
337b0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
337c0 41 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20  API3REF: Commit 
337d0 41 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74  And Rollback Not
337e0 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61  ification Callba
337f0 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  cks.**.** ^The s
33800 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
33810 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ok() interface r
33820 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62  egisters a callb
33830 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ack.** function 
33840 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68  to be invoked wh
33850 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61 63  enever a transac
33860 74 69 6f 6e 20 69 73 20 5b 43 4f 4d 4d 49 54 20  tion is [COMMIT 
33870 7c 20 63 6f 6d 6d 69 74 74 65 64 5d 2e 0a 2a 2a  | committed]..**
33880 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73   ^Any callback s
33890 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73  et by a previous
338a0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
338b0 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a  _commit_hook().*
338c0 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64  * for the same d
338d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
338e0 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e  on is overridden
338f0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
33900 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28  3_rollback_hook(
33910 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ) interface regi
33920 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
33930 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  .** function to 
33940 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
33950 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ver a transactio
33960 6e 20 69 73 20 5b 52 4f 4c 4c 42 41 43 4b 20 7c  n is [ROLLBACK |
33970 20 72 6f 6c 6c 65 64 20 62 61 63 6b 5d 2e 0a 2a   rolled back]..*
33980 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20  * ^Any callback 
33990 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75  set by a previou
339a0 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  s call to sqlite
339b0 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28  3_rollback_hook(
339c0 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d  ).** for the sam
339d0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
339e0 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64  ction is overrid
339f0 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20 70 41 72  den..** ^The pAr
33a00 67 20 61 72 67 75 6d 65 6e 74 20 69 73 20 70 61  g argument is pa
33a10 73 73 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20  ssed through to 
33a20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  the callback..**
33a30 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
33a40 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f  k on a commit ho
33a50 6f 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  ok function retu
33a60 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a  rns non-zero,.**
33a70 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74   then the commit
33a80 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e   is converted in
33a90 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a  to a rollback..*
33aa0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
33ab0 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c  3_commit_hook(D,
33ac0 43 2c 50 29 20 61 6e 64 20 73 71 6c 69 74 65 33  C,P) and sqlite3
33ad0 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44  _rollback_hook(D
33ae0 2c 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e 73 0a  ,C,P) functions.
33af0 2a 2a 20 72 65 74 75 72 6e 20 74 68 65 20 50 20  ** return the P 
33b00 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68  argument from th
33b10 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  e previous call 
33b20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
33b30 74 69 6f 6e 0a 2a 2a 20 6f 6e 20 74 68 65 20 73  tion.** on the s
33b40 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
33b50 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20  nnection] D, or 
33b60 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 20  NULL for.** the 
33b70 66 69 72 73 74 20 63 61 6c 6c 20 66 6f 72 20 65  first call for e
33b80 61 63 68 20 66 75 6e 63 74 69 6f 6e 20 6f 6e 20  ach function on 
33b90 44 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c  D..**.** The cal
33ba0 6c 62 61 63 6b 20 69 6d 70 6c 65 6d 65 6e 74 61  lback implementa
33bb0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f  tion must not do
33bc0 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77   anything that w
33bd0 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68  ill modify.** th
33be0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
33bf0 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
33c00 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e  ed the callback.
33c10 20 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a    Any actions.**
33c20 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64   to modify the d
33c30 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
33c40 6f 6e 20 6d 75 73 74 20 62 65 20 64 65 66 65 72  on must be defer
33c50 72 65 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20  red until after 
33c60 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f  the.** completio
33c70 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  n of the [sqlite
33c80 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74  3_step()] call t
33c90 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68  hat triggered th
33ca0 65 20 63 6f 6d 6d 69 74 0a 2a 2a 20 6f 72 20 72  e commit.** or r
33cb0 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 6e 20  ollback hook in 
33cc0 74 68 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e  the first place.
33cd0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73  .** Note that [s
33ce0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
33cf0 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
33d00 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d  3_step()] both m
33d10 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64  odify their.** d
33d20 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
33d30 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
33d40 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
33d50 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
33d60 68 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 69 73 74  h..**.** ^Regist
33d70 65 72 69 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e  ering a NULL fun
33d80 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 74  ction disables t
33d90 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  he callback..**.
33da0 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 63 6f 6d  ** ^When the com
33db0 6d 69 74 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63  mit hook callbac
33dc0 6b 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  k routine return
33dd0 73 20 7a 65 72 6f 2c 20 74 68 65 20 5b 43 4f 4d  s zero, the [COM
33de0 4d 49 54 5d 0a 2a 2a 20 6f 70 65 72 61 74 69 6f  MIT].** operatio
33df0 6e 20 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 20  n is allowed to 
33e00 63 6f 6e 74 69 6e 75 65 20 6e 6f 72 6d 61 6c 6c  continue normall
33e10 79 2e 20 20 5e 49 66 20 74 68 65 20 63 6f 6d 6d  y.  ^If the comm
33e20 69 74 20 68 6f 6f 6b 0a 2a 2a 20 72 65 74 75 72  it hook.** retur
33e30 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
33e40 6e 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 20 69  n the [COMMIT] i
33e50 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f  s converted into
33e60 20 61 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a   a [ROLLBACK]..*
33e70 2a 20 5e 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20  * ^The rollback 
33e80 68 6f 6f 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  hook is invoked 
33e90 6f 6e 20 61 20 72 6f 6c 6c 62 61 63 6b 20 74 68  on a rollback th
33ea0 61 74 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20  at results from 
33eb0 61 20 63 6f 6d 6d 69 74 0a 2a 2a 20 68 6f 6f 6b  a commit.** hook
33ec0 20 72 65 74 75 72 6e 69 6e 67 20 6e 6f 6e 2d 7a   returning non-z
33ed0 65 72 6f 2c 20 6a 75 73 74 20 61 73 20 69 74 20  ero, just as it 
33ee0 77 6f 75 6c 64 20 62 65 20 77 69 74 68 20 61 6e  would be with an
33ef0 79 20 6f 74 68 65 72 20 72 6f 6c 6c 62 61 63 6b  y other rollback
33f00 2e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65  ..**.** ^For the
33f10 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69   purposes of thi
33f20 73 20 41 50 49 2c 20 61 20 74 72 61 6e 73 61 63  s API, a transac
33f30 74 69 6f 6e 20 69 73 20 73 61 69 64 20 74 6f 20  tion is said to 
33f40 68 61 76 65 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c  have been.** rol
33f50 6c 65 64 20 62 61 63 6b 20 69 66 20 61 6e 20 65  led back if an e
33f60 78 70 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41 43  xplicit "ROLLBAC
33f70 4b 22 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  K" statement is 
33f80 65 78 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20  executed, or.** 
33f90 61 6e 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73  an error or cons
33fa0 74 72 61 69 6e 74 20 63 61 75 73 65 73 20 61 6e  traint causes an
33fb0 20 69 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61   implicit rollba
33fc0 63 6b 20 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20  ck to occur..** 
33fd0 5e 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61  ^The rollback ca
33fe0 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e  llback is not in
33ff0 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61 6e 73  voked if a trans
34000 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 74  action is.** aut
34010 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65  omatically rolle
34020 64 20 62 61 63 6b 20 62 65 63 61 75 73 65 20 74  d back because t
34030 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
34040 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
34050 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
34060 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 70   the [sqlite3_up
34070 64 61 74 65 5f 68 6f 6f 6b 28 29 5d 20 69 6e 74  date_hook()] int
34080 65 72 66 61 63 65 2e 0a 2a 2f 0a 76 6f 69 64 20  erface..*/.void 
34090 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f  *sqlite3_commit_
340a0 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69  hook(sqlite3*, i
340b0 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f  nt(*)(void*), vo
340c0 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69  id*);.void *sqli
340d0 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f  te3_rollback_hoo
340e0 6b 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64  k(sqlite3*, void
340f0 28 2a 29 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69  (*)(void *), voi
34100 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
34110 33 52 45 46 3a 20 44 61 74 61 20 43 68 61 6e 67  3REF: Data Chang
34120 65 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43  e Notification C
34130 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e  allbacks.**.** ^
34140 54 68 65 20 73 71 6c 69 74 65 33 5f 75 70 64 61  The sqlite3_upda
34150 74 65 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66  te_hook() interf
34160 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
34170 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
34180 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64  n.** with the [d
34190 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
341a0 6f 6e 5d 20 69 64 65 6e 74 69 66 69 65 64 20 62  on] identified b
341b0 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  y the first argu
341c0 6d 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 69 6e  ment.** to be in
341d0 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
341e0 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c   row is updated,
341f0 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c   inserted or del
34200 65 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61  eted..** ^Any ca
34210 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20  llback set by a 
34220 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
34230 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a   this function.*
34240 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64  * for the same d
34250 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
34260 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e  on is overridden
34270 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63  ..**.** ^The sec
34280 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
34290 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
342a0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76   function to inv
342b0 6f 6b 65 20 77 68 65 6e 20 61 0a 2a 2a 20 72 6f  oke when a.** ro
342c0 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e  w is updated, in
342d0 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65  serted or delete
342e0 64 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  d..** ^The first
342f0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
34300 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63   callback is a c
34310 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64  opy of the third
34320 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
34330 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
34340 6f 6f 6b 28 29 2e 0a 2a 2a 20 5e 54 68 65 20 73  ook()..** ^The s
34350 65 63 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20 61  econd callback a
34360 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f  rgument is one o
34370 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52 54  f [SQLITE_INSERT
34380 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54  ], [SQLITE_DELET
34390 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54  E],.** or [SQLIT
343a0 45 5f 55 50 44 41 54 45 5d 2c 20 64 65 70 65 6e  E_UPDATE], depen
343b0 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65 72  ding on the oper
343c0 61 74 69 6f 6e 20 74 68 61 74 20 63 61 75 73 65  ation that cause
343d0 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  d the callback.*
343e0 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e  * to be invoked.
343f0 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61  .** ^The third a
34400 6e 64 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  nd fourth argume
34410 6e 74 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  nts to the callb
34420 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e  ack contain poin
34430 74 65 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64  ters to the.** d
34440 61 74 61 62 61 73 65 20 61 6e 64 20 74 61 62 6c  atabase and tabl
34450 65 20 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e  e name containin
34460 67 20 74 68 65 20 61 66 66 65 63 74 65 64 20 72  g the affected r
34470 6f 77 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 6e 61  ow..** ^The fina
34480 6c 20 63 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d  l callback param
34490 65 74 65 72 20 69 73 20 74 68 65 20 5b 72 6f 77  eter is the [row
344a0 69 64 5d 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a  id] of the row..
344b0 2a 2a 20 5e 49 6e 20 74 68 65 20 63 61 73 65 20  ** ^In the case 
344c0 6f 66 20 61 6e 20 75 70 64 61 74 65 2c 20 74 68  of an update, th
344d0 69 73 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64  is is the [rowid
344e0 5d 20 61 66 74 65 72 20 74 68 65 20 75 70 64 61  ] after the upda
344f0 74 65 20 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a  te takes place..
34500 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 75 70 64 61  **.** ^(The upda
34510 74 65 20 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69  te hook is not i
34520 6e 76 6f 6b 65 64 20 77 68 65 6e 20 69 6e 74 65  nvoked when inte
34530 72 6e 61 6c 20 73 79 73 74 65 6d 20 74 61 62 6c  rnal system tabl
34540 65 73 20 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69  es are.** modifi
34550 65 64 20 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f  ed (i.e. sqlite_
34560 6d 61 73 74 65 72 20 61 6e 64 20 73 71 6c 69 74  master and sqlit
34570 65 5f 73 65 71 75 65 6e 63 65 29 2e 29 5e 0a 2a  e_sequence).)^.*
34580 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 63 75 72  *.** ^In the cur
34590 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74  rent implementat
345a0 69 6f 6e 2c 20 74 68 65 20 75 70 64 61 74 65 20  ion, the update 
345b0 68 6f 6f 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 69  hook.** is not i
345c0 6e 76 6f 6b 65 64 20 77 68 65 6e 20 64 75 70 6c  nvoked when dupl
345d0 69 63 61 74 69 6f 6e 20 72 6f 77 73 20 61 72 65  ication rows are
345e0 20 64 65 6c 65 74 65 64 20 62 65 63 61 75 73 65   deleted because
345f0 20 6f 66 20 61 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f   of an.** [ON CO
34600 4e 46 4c 49 43 54 20 7c 20 4f 4e 20 43 4f 4e 46  NFLICT | ON CONF
34610 4c 49 43 54 20 52 45 50 4c 41 43 45 5d 20 63 6c  LICT REPLACE] cl
34620 61 75 73 65 2e 20 20 5e 4e 6f 72 20 69 73 20 74  ause.  ^Nor is t
34630 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a  he update hook.*
34640 2a 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 72  * invoked when r
34650 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20  ows are deleted 
34660 75 73 69 6e 67 20 74 68 65 20 5b 74 72 75 6e 63  using the [trunc
34670 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  ate optimization
34680 5d 2e 0a 2a 2a 20 54 68 65 20 65 78 63 65 70 74  ]..** The except
34690 69 6f 6e 73 20 64 65 66 69 6e 65 64 20 69 6e 20  ions defined in 
346a0 74 68 69 73 20 70 61 72 61 67 72 61 70 68 20 6d  this paragraph m
346b0 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20 61  ight change in a
346c0 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61   future.** relea
346d0 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  se of SQLite..**
346e0 0a 2a 2a 20 54 68 65 20 75 70 64 61 74 65 20 68  .** The update h
346f0 6f 6f 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ook implementati
34700 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61  on must not do a
34710 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c  nything that wil
34720 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20  l modify.** the 
34730 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
34740 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
34750 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b   the update hook
34760 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a  .  Any actions.*
34770 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20  * to modify the 
34780 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
34790 69 6f 6e 20 6d 75 73 74 20 62 65 20 64 65 66 65  ion must be defe
347a0 72 72 65 64 20 75 6e 74 69 6c 20 61 66 74 65 72  rred until after
347b0 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69   the.** completi
347c0 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  on of the [sqlit
347d0 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20  e3_step()] call 
347e0 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74  that triggered t
347f0 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 0a  he update hook..
34800 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71  ** Note that [sq
34810 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
34820 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
34830 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f  _step()] both mo
34840 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61  dify their.** da
34850 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
34860 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69  ns for the meani
34870 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69  ng of "modify" i
34880 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68  n this paragraph
34890 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
348a0 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
348b0 28 44 2c 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e  (D,C,P) function
348c0 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20  .** returns the 
348d0 50 20 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20  P argument from 
348e0 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c  the previous cal
348f0 6c 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65  l.** on the same
34900 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
34910 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c  ction] D, or NUL
34920 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72  L for.** the fir
34930 73 74 20 63 61 6c 6c 20 6f 6e 20 44 2e 0a 2a 2a  st call on D..**
34940 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65  .** See also the
34950 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74   [sqlite3_commit
34960 5f 68 6f 6f 6b 28 29 5d 2c 20 5b 73 71 6c 69 74  _hook()], [sqlit
34970 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
34980 28 29 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  ()],.** and [sql
34990 69 74 65 33 5f 70 72 65 75 70 64 61 74 65 5f 68  ite3_preupdate_h
349a0 6f 6f 6b 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ook()] interface
349b0 73 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  s..*/.void *sqli
349c0 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
349d0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
349e0 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69  void(*)(void *,i
349f0 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a  nt ,char const *
34a00 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71  ,char const *,sq
34a10 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20  lite3_int64),.  
34a20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  void*.);../*.** 
34a30 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65  CAPI3REF: Enable
34a40 20 4f 72 20 44 69 73 61 62 6c 65 20 53 68 61 72   Or Disable Shar
34a50 65 64 20 50 61 67 65 72 20 43 61 63 68 65 0a 2a  ed Pager Cache.*
34a60 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 73 68 61  * KEYWORDS: {sha
34a70 72 65 64 20 63 61 63 68 65 7d 0a 2a 2a 0a 2a 2a  red cache}.**.**
34a80 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20   ^(This routine 
34a90 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
34aa0 6c 65 73 20 74 68 65 20 73 68 61 72 69 6e 67 20  les the sharing 
34ab0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
34ac0 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68  cache.** and sch
34ad0 65 6d 61 20 64 61 74 61 20 73 74 72 75 63 74 75  ema data structu
34ae0 72 65 73 20 62 65 74 77 65 65 6e 20 5b 64 61 74  res between [dat
34af0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
34b00 20 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a   | connections].
34b10 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64  ** to the same d
34b20 61 74 61 62 61 73 65 2e 20 53 68 61 72 69 6e 67  atabase. Sharing
34b30 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74   is enabled if t
34b40 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  he argument is t
34b50 72 75 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62  rue.** and disab
34b60 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d  led if the argum
34b70 65 6e 74 20 69 73 20 66 61 6c 73 65 2e 29 5e 0a  ent is false.)^.
34b80 2a 2a 0a 2a 2a 20 5e 43 61 63 68 65 20 73 68 61  **.** ^Cache sha
34b90 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20  ring is enabled 
34ba0 61 6e 64 20 64 69 73 61 62 6c 65 64 20 66 6f 72  and disabled for
34bb0 20 61 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 65   an entire proce
34bc0 73 73 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 61  ss..** This is a
34bd0 20 63 68 61 6e 67 65 20 61 73 20 6f 66 20 53 51   change as of SQ
34be0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
34bf0 2e 30 2e 20 49 6e 20 70 72 69 6f 72 20 76 65 72  .0. In prior ver
34c00 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c  sions of SQLite,
34c10 0a 2a 2a 20 73 68 61 72 69 6e 67 20 77 61 73 20  .** sharing was 
34c20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62  enabled or disab
34c30 6c 65 64 20 66 6f 72 20 65 61 63 68 20 74 68 72  led for each thr
34c40 65 61 64 20 73 65 70 61 72 61 74 65 6c 79 2e 0a  ead separately..
34c50 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 63 61 63 68  **.** ^(The cach
34c60 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 73  e sharing mode s
34c70 65 74 20 62 79 20 74 68 69 73 20 69 6e 74 65 72  et by this inter
34c80 66 61 63 65 20 65 66 66 65 63 74 73 20 61 6c 6c  face effects all
34c90 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63   subsequent.** c
34ca0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
34cb0 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
34cc0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61  e3_open_v2()], a
34cd0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  nd [sqlite3_open
34ce0 31 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69  16()]..** Existi
34cf0 6e 67 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ng database conn
34d00 65 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65  ections continue
34d10 20 75 73 65 20 74 68 65 20 73 68 61 72 69 6e 67   use the sharing
34d20 20 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77 61   mode.** that wa
34d30 73 20 69 6e 20 65 66 66 65 63 74 20 61 74 20 74  s in effect at t
34d40 68 65 20 74 69 6d 65 20 74 68 65 79 20 77 65 72  he time they wer
34d50 65 20 6f 70 65 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a  e opened.)^.**.*
34d60 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65  * ^(This routine
34d70 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
34d80 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63  _OK] if shared c
34d90 61 63 68 65 20 77 61 73 20 65 6e 61 62 6c 65 64  ache was enabled
34da0 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20   or disabled.** 
34db0 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 41  successfully.  A
34dc0 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
34dd0 73 20 72 65 74 75 72 6e 65 64 20 6f 74 68 65 72  s returned other
34de0 77 69 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53  wise.)^.**.** ^S
34df0 68 61 72 65 64 20 63 61 63 68 65 20 69 73 20 64  hared cache is d
34e00 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
34e10 6c 74 2e 20 42 75 74 20 74 68 69 73 20 6d 69 67  lt. But this mig
34e20 68 74 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20  ht change in.** 
34e30 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
34e40 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 70 70 6c  of SQLite.  Appl
34e50 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 63 61  ications that ca
34e60 72 65 20 61 62 6f 75 74 20 73 68 61 72 65 64 0a  re about shared.
34e70 2a 2a 20 63 61 63 68 65 20 73 65 74 74 69 6e 67  ** cache setting
34e80 20 73 68 6f 75 6c 64 20 73 65 74 20 69 74 20 65   should set it e
34e90 78 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a  xplicitly..**.**
34ea0 20 53 65 65 20 41 6c 73 6f 3a 20 20 5b 53 51 4c   See Also:  [SQL
34eb0 69 74 65 20 53 68 61 72 65 64 2d 43 61 63 68 65  ite Shared-Cache
34ec0 20 4d 6f 64 65 5d 0a 2a 2f 0a 69 6e 74 20 73 71   Mode].*/.int sq
34ed0 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61  lite3_enable_sha
34ee0 72 65 64 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a  red_cache(int);.
34ef0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
34f00 20 41 74 74 65 6d 70 74 20 54 6f 20 46 72 65 65   Attempt To Free
34f10 20 48 65 61 70 20 4d 65 6d 6f 72 79 0a 2a 2a 0a   Heap Memory.**.
34f20 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
34f30 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
34f40 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
34f50 70 74 73 20 74 6f 20 66 72 65 65 20 4e 20 62 79  pts to free N by
34f60 74 65 73 0a 2a 2a 20 6f 66 20 68 65 61 70 20 6d  tes.** of heap m
34f70 65 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63  emory by dealloc
34f80 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74  ating non-essent
34f90 69 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ial memory alloc
34fa0 61 74 69 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20 62  ations.** held b
34fb0 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6c  y the database l
34fc0 69 62 72 61 72 79 2e 20 20 20 4d 65 6d 6f 72 79  ibrary.   Memory
34fd0 20 75 73 65 64 20 74 6f 20 63 61 63 68 65 20 64   used to cache d
34fe0 61 74 61 62 61 73 65 0a 2a 2a 20 70 61 67 65 73  atabase.** pages
34ff0 20 74 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 66   to improve perf
35000 6f 72 6d 61 6e 63 65 20 69 73 20 61 6e 20 65 78  ormance is an ex
35010 61 6d 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 73  ample of non-ess
35020 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a  ential memory..*
35030 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  * ^sqlite3_relea
35040 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 65 74 75  se_memory() retu
35050 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
35060 66 20 62 79 74 65 73 20 61 63 74 75 61 6c 6c 79  f bytes actually
35070 20 66 72 65 65 64 2c 0a 2a 2a 20 77 68 69 63 68   freed,.** which
35080 20 6d 69 67 68 74 20 62 65 20 6d 6f 72 65 20 6f   might be more o
35090 72 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20  r less than the 
350a0 61 6d 6f 75 6e 74 20 72 65 71 75 65 73 74 65 64  amount requested
350b0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
350c0 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  3_release_memory
350d0 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20  () routine is a 
350e0 6e 6f 2d 6f 70 20 72 65 74 75 72 6e 69 6e 67 20  no-op returning 
350f0 7a 65 72 6f 0a 2a 2a 20 69 66 20 53 51 4c 69 74  zero.** if SQLit
35100 65 20 69 73 20 6e 6f 74 20 63 6f 6d 70 69 6c 65  e is not compile
35110 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 45  d with [SQLITE_E
35120 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e  NABLE_MEMORY_MAN
35130 41 47 45 4d 45 4e 54 5d 2e 0a 2a 2f 0a 69 6e 74  AGEMENT]..*/.int
35140 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65   sqlite3_release
35150 5f 6d 65 6d 6f 72 79 28 69 6e 74 29 3b 0a 0a 2f  _memory(int);../
35160 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
35170 6d 70 6f 73 65 20 41 20 4c 69 6d 69 74 20 4f 6e  mpose A Limit On
35180 20 48 65 61 70 20 53 69 7a 65 0a 2a 2a 0a 2a 2a   Heap Size.**.**
35190 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f   ^The sqlite3_so
351a0 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28  ft_heap_limit64(
351b0 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
351c0 20 61 6e 64 2f 6f 72 20 71 75 65 72 69 65 73 20   and/or queries 
351d0 74 68 65 0a 2a 2a 20 73 6f 66 74 20 6c 69 6d 69  the.** soft limi
351e0 74 20 6f 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20  t on the amount 
351f0 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 74  of heap memory t
35200 68 61 74 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63  hat may be alloc
35210 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a  ated by SQLite..
35220 2a 2a 20 5e 53 51 4c 69 74 65 20 73 74 72 69 76  ** ^SQLite striv
35230 65 73 20 74 6f 20 6b 65 65 70 20 68 65 61 70 20  es to keep heap 
35240 6d 65 6d 6f 72 79 20 75 74 69 6c 69 7a 61 74 69  memory utilizati
35250 6f 6e 20 62 65 6c 6f 77 20 74 68 65 20 73 6f 66  on below the sof
35260 74 20 68 65 61 70 0a 2a 2a 20 6c 69 6d 69 74 20  t heap.** limit 
35270 62 79 20 72 65 64 75 63 69 6e 67 20 74 68 65 20  by reducing the 
35280 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20  number of pages 
35290 68 65 6c 64 20 69 6e 20 74 68 65 20 70 61 67 65  held in the page
352a0 20 63 61 63 68 65 0a 2a 2a 20 61 73 20 68 65 61   cache.** as hea
352b0 70 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 73 20  p memory usages 
352c0 61 70 70 72 6f 61 63 68 65 73 20 74 68 65 20 6c  approaches the l
352d0 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 6f  imit..** ^The so
352e0 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73  ft heap limit is
352f0 20 22 73 6f 66 74 22 20 62 65 63 61 75 73 65 20   "soft" because 
35300 65 76 65 6e 20 74 68 6f 75 67 68 20 53 51 4c 69  even though SQLi
35310 74 65 20 73 74 72 69 76 65 73 20 74 6f 20 73 74  te strives to st
35320 61 79 0a 2a 2a 20 62 65 6c 6f 77 20 74 68 65 20  ay.** below the 
35330 6c 69 6d 69 74 2c 20 69 74 20 77 69 6c 6c 20 65  limit, it will e
35340 78 63 65 65 64 20 74 68 65 20 6c 69 6d 69 74 20  xceed the limit 
35350 72 61 74 68 65 72 20 74 68 61 6e 20 67 65 6e 65  rather than gene
35360 72 61 74 65 0a 2a 2a 20 61 6e 20 5b 53 51 4c 49  rate.** an [SQLI
35370 54 45 5f 4e 4f 4d 45 4d 5d 20 65 72 72 6f 72 2e  TE_NOMEM] error.
35380 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
35390 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  , the soft heap 
353a0 6c 69 6d 69 74 20 0a 2a 2a 20 69 73 20 61 64 76  limit .** is adv
353b0 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a  isory only..**.*
353c0 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 20 76 61  * ^The return va
353d0 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
353e0 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
353f0 36 34 28 29 20 69 73 20 74 68 65 20 73 69 7a 65  64() is the size
35400 20 6f 66 0a 2a 2a 20 74 68 65 20 73 6f 66 74 20   of.** the soft 
35410 68 65 61 70 20 6c 69 6d 69 74 20 70 72 69 6f 72  heap limit prior
35420 20 74 6f 20 74 68 65 20 63 61 6c 6c 2e 20 20 5e   to the call.  ^
35430 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  If the argument 
35440 4e 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a  N is negative.**
35450 20 74 68 65 6e 20 6e 6f 20 63 68 61 6e 67 65 20   then no change 
35460 69 73 20 6d 61 64 65 20 74 6f 20 74 68 65 20 73  is made to the s
35470 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2e 20  oft heap limit. 
35480 20 48 65 6e 63 65 2c 20 74 68 65 20 63 75 72 72   Hence, the curr
35490 65 6e 74 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 74  ent.** size of t
354a0 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
354b0 69 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d  it can be determ
354c0 69 6e 65 64 20 62 79 20 69 6e 76 6f 6b 69 6e 67  ined by invoking
354d0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 6f 66 74  .** sqlite3_soft
354e0 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 20  _heap_limit64() 
354f0 77 69 74 68 20 61 20 6e 65 67 61 74 69 76 65 20  with a negative 
35500 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
35510 5e 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74  ^If the argument
35520 20 4e 20 69 73 20 7a 65 72 6f 20 74 68 65 6e 20   N is zero then 
35530 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
35540 6d 69 74 20 69 73 20 64 69 73 61 62 6c 65 64 2e  mit is disabled.
35550 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 6f 66  .**.** ^(The sof
35560 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20  t heap limit is 
35570 6e 6f 74 20 65 6e 66 6f 72 63 65 64 20 69 6e 20  not enforced in 
35580 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c  the current impl
35590 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 66  ementation.** if
355a0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20   one or more of 
355b0 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e 64 69 74  following condit
355c0 69 6f 6e 73 20 61 72 65 20 74 72 75 65 3a 0a 2a  ions are true:.*
355d0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
355e0 3e 20 54 68 65 20 73 6f 66 74 20 68 65 61 70 20  > The soft heap 
355f0 6c 69 6d 69 74 20 69 73 20 73 65 74 20 74 6f 20  limit is set to 
35600 7a 65 72 6f 2e 0a 2a 2a 20 3c 6c 69 3e 20 4d 65  zero..** <li> Me
35610 6d 6f 72 79 20 61 63 63 6f 75 6e 74 69 6e 67 20  mory accounting 
35620 69 73 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e  is disabled usin
35630 67 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  g a combination 
35640 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 5b  of the.**      [
35650 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
35660 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
35670 45 4d 53 54 41 54 55 53 5d 2c 2e 2e 2e 29 20 73  EMSTATUS],...) s
35680 74 61 72 74 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  tart-time option
35690 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 74 68 65   and.**      the
356a0 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54   [SQLITE_DEFAULT
356b0 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6d 70  _MEMSTATUS] comp
356c0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e  ile-time option.
356d0 0a 2a 2a 20 3c 6c 69 3e 20 41 6e 20 61 6c 74 65  .** <li> An alte
356e0 72 6e 61 74 69 76 65 20 70 61 67 65 20 63 61 63  rnative page cac
356f0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
35700 6e 20 69 73 20 73 70 65 63 69 66 69 65 64 20 75  n is specified u
35710 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 5b 73 71  sing.**      [sq
35720 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53  lite3_config]([S
35730 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
35740 43 48 45 5d 2c 2e 2e 2e 29 2e 0a 2a 2a 20 3c 6c  CHE],...)..** <l
35750 69 3e 20 54 68 65 20 70 61 67 65 20 63 61 63 68  i> The page cach
35760 65 20 61 6c 6c 6f 63 61 74 65 73 20 66 72 6f 6d  e allocates from
35770 20 69 74 73 20 6f 77 6e 20 6d 65 6d 6f 72 79 20   its own memory 
35780 70 6f 6f 6c 20 73 75 70 70 6c 69 65 64 0a 2a 2a  pool supplied.**
35790 20 20 20 20 20 20 62 79 20 5b 73 71 6c 69 74 65        by [sqlite
357a0 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54  3_config]([SQLIT
357b0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
357c0 48 45 5d 2c 2e 2e 2e 29 20 72 61 74 68 65 72 20  HE],...) rather 
357d0 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 66 72 6f  than.**      fro
357e0 6d 20 74 68 65 20 68 65 61 70 2e 0a 2a 2a 20 3c  m the heap..** <
357f0 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 42 65 67  /ul>)^.**.** Beg
35800 69 6e 6e 69 6e 67 20 77 69 74 68 20 53 51 4c 69  inning with SQLi
35810 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 33  te version 3.7.3
35820 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  , the soft heap 
35830 6c 69 6d 69 74 20 69 73 20 65 6e 66 6f 72 63 65  limit is enforce
35840 64 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20  d.** regardless 
35850 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
35860 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e  t the [SQLITE_EN
35870 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41  ABLE_MEMORY_MANA
35880 47 45 4d 45 4e 54 5d 0a 2a 2a 20 63 6f 6d 70 69  GEMENT].** compi
35890 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69  le-time option i
358a0 73 20 69 6e 76 6f 6b 65 64 2e 20 20 57 69 74 68  s invoked.  With
358b0 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
358c0 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e  MEMORY_MANAGEMEN
358d0 54 5d 2c 0a 2a 2a 20 74 68 65 20 73 6f 66 74 20  T],.** the soft 
358e0 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 65 6e  heap limit is en
358f0 66 6f 72 63 65 64 20 6f 6e 20 65 76 65 72 79 20  forced on every 
35900 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
35910 6e 2e 20 20 57 69 74 68 6f 75 74 0a 2a 2a 20 5b  n.  Without.** [
35920 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45  SQLITE_ENABLE_ME
35930 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d  MORY_MANAGEMENT]
35940 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  , the soft heap 
35950 6c 69 6d 69 74 20 69 73 20 6f 6e 6c 79 20 65 6e  limit is only en
35960 66 6f 72 63 65 64 0a 2a 2a 20 77 68 65 6e 20 6d  forced.** when m
35970 65 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61 74  emory is allocat
35980 65 64 20 62 79 20 74 68 65 20 70 61 67 65 20 63  ed by the page c
35990 61 63 68 65 2e 20 20 54 65 73 74 69 6e 67 20 73  ache.  Testing s
359a0 75 67 67 65 73 74 73 20 74 68 61 74 20 62 65 63  uggests that bec
359b0 61 75 73 65 0a 2a 2a 20 74 68 65 20 70 61 67 65  ause.** the page
359c0 20 63 61 63 68 65 20 69 73 20 74 68 65 20 70 72   cache is the pr
359d0 65 64 6f 6d 69 6e 61 74 65 20 6d 65 6d 6f 72 79  edominate memory
359e0 20 75 73 65 72 20 69 6e 20 53 51 4c 69 74 65 2c   user in SQLite,
359f0 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61   most.** applica
35a00 74 69 6f 6e 73 20 77 69 6c 6c 20 61 63 68 69 65  tions will achie
35a10 76 65 20 61 64 65 71 75 61 74 65 20 73 6f 66 74  ve adequate soft
35a20 20 68 65 61 70 20 6c 69 6d 69 74 20 65 6e 66 6f   heap limit enfo
35a30 72 63 65 6d 65 6e 74 20 77 69 74 68 6f 75 74 0a  rcement without.
35a40 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 5b 53  ** the use of [S
35a50 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
35a60 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2e  ORY_MANAGEMENT].
35a70 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 69 72 63 75  .**.** The circu
35a80 6d 73 74 61 6e 63 65 73 20 75 6e 64 65 72 20 77  mstances under w
35a90 68 69 63 68 20 53 51 4c 69 74 65 20 77 69 6c 6c  hich SQLite will
35aa0 20 65 6e 66 6f 72 63 65 20 74 68 65 20 73 6f 66   enforce the sof
35ab0 74 20 68 65 61 70 20 6c 69 6d 69 74 20 6d 61 79  t heap limit may
35ac0 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 66  .** changes in f
35ad0 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
35ae0 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 73 71 6c  f SQLite..*/.sql
35af0 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
35b00 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d  e3_soft_heap_lim
35b10 69 74 36 34 28 73 71 6c 69 74 65 33 5f 69 6e 74  it64(sqlite3_int
35b20 36 34 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  64 N);../*.** CA
35b30 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74  PI3REF: Deprecat
35b40 65 64 20 53 6f 66 74 20 48 65 61 70 20 4c 69 6d  ed Soft Heap Lim
35b50 69 74 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 20  it Interface.** 
35b60 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a  DEPRECATED.**.**
35b70 20 54 68 69 73 20 69 73 20 61 20 64 65 70 72 65   This is a depre
35b80 63 61 74 65 64 20 76 65 72 73 69 6f 6e 20 6f 66  cated version of
35b90 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6f   the [sqlite3_so
35ba0 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28  ft_heap_limit64(
35bb0 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e  )].** interface.
35bc0 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69    This routine i
35bd0 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20 68  s provided for h
35be0 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74  istorical compat
35bf0 69 62 69 6c 69 74 79 0a 2a 2a 20 6f 6e 6c 79 2e  ibility.** only.
35c00 20 20 41 6c 6c 20 6e 65 77 20 61 70 70 6c 69 63    All new applic
35c10 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 75 73  ations should us
35c20 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  e the.** [sqlite
35c30 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
35c40 74 36 34 28 29 5d 20 69 6e 74 65 72 66 61 63 65  t64()] interface
35c50 20 72 61 74 68 65 72 20 74 68 61 6e 20 74 68 69   rather than thi
35c60 73 20 6f 6e 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45  s one..*/.SQLITE
35c70 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64  _DEPRECATED void
35c80 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65   sqlite3_soft_he
35c90 61 70 5f 6c 69 6d 69 74 28 69 6e 74 20 4e 29 3b  ap_limit(int N);
35ca0 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
35cb0 46 3a 20 45 78 74 72 61 63 74 20 4d 65 74 61 64  F: Extract Metad
35cc0 61 74 61 20 41 62 6f 75 74 20 41 20 43 6f 6c 75  ata About A Colu
35cd0 6d 6e 20 4f 66 20 41 20 54 61 62 6c 65 0a 2a 2a  mn Of A Table.**
35ce0 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
35cf0 65 20 72 65 74 75 72 6e 73 20 6d 65 74 61 64 61  e returns metada
35d00 74 61 20 61 62 6f 75 74 20 61 20 73 70 65 63 69  ta about a speci
35d10 66 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20  fic column of a 
35d20 73 70 65 63 69 66 69 63 0a 2a 2a 20 64 61 74 61  specific.** data
35d30 62 61 73 65 20 74 61 62 6c 65 20 61 63 63 65 73  base table acces
35d40 73 69 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20  sible using the 
35d50 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
35d60 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20  tion] handle.** 
35d70 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69  passed as the fi
35d80 72 73 74 20 66 75 6e 63 74 69 6f 6e 20 61 72 67  rst function arg
35d90 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ument..**.** ^Th
35da0 65 20 63 6f 6c 75 6d 6e 20 69 73 20 69 64 65 6e  e column is iden
35db0 74 69 66 69 65 64 20 62 79 20 74 68 65 20 73 65  tified by the se
35dc0 63 6f 6e 64 2c 20 74 68 69 72 64 20 61 6e 64 20  cond, third and 
35dd0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
35de0 73 20 74 6f 0a 2a 2a 20 74 68 69 73 20 66 75 6e  s to.** this fun
35df0 63 74 69 6f 6e 2e 20 5e 54 68 65 20 73 65 63 6f  ction. ^The seco
35e00 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
35e10 65 69 74 68 65 72 20 74 68 65 20 6e 61 6d 65 20  either the name 
35e20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  of the database.
35e30 2a 2a 20 28 69 2e 65 2e 20 22 6d 61 69 6e 22 2c  ** (i.e. "main",
35e40 20 22 74 65 6d 70 22 2c 20 6f 72 20 61 6e 20 61   "temp", or an a
35e50 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
35e60 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  ) containing the
35e70 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 74 61   specified.** ta
35e80 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20 5e 49 66  ble or NULL. ^If
35e90 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65   it is NULL, the
35ea0 6e 20 61 6c 6c 20 61 74 74 61 63 68 65 64 20 64  n all attached d
35eb0 61 74 61 62 61 73 65 73 20 61 72 65 20 73 65 61  atabases are sea
35ec0 72 63 68 65 64 0a 2a 2a 20 66 6f 72 20 74 68 65  rched.** for the
35ed0 20 74 61 62 6c 65 20 75 73 69 6e 67 20 74 68 65   table using the
35ee0 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20   same algorithm 
35ef0 75 73 65 64 20 62 79 20 74 68 65 20 64 61 74 61  used by the data
35f00 62 61 73 65 20 65 6e 67 69 6e 65 20 74 6f 0a 2a  base engine to.*
35f10 2a 20 72 65 73 6f 6c 76 65 20 75 6e 71 75 61 6c  * resolve unqual
35f20 69 66 69 65 64 20 74 61 62 6c 65 20 72 65 66 65  ified table refe
35f30 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  rences..**.** ^T
35f40 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75  he third and fou
35f50 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  rth parameters t
35f60 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  o this function 
35f70 61 72 65 20 74 68 65 20 74 61 62 6c 65 20 61 6e  are the table an
35f80 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6e 61 6d 65  d column.** name
35f90 20 6f 66 20 74 68 65 20 64 65 73 69 72 65 64 20   of the desired 
35fa0 63 6f 6c 75 6d 6e 2c 20 72 65 73 70 65 63 74 69  column, respecti
35fb0 76 65 6c 79 2e 20 4e 65 69 74 68 65 72 20 6f 66  vely. Neither of
35fc0 20 74 68 65 73 65 20 70 61 72 61 6d 65 74 65 72   these parameter
35fd0 73 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c  s.** may be NULL
35fe0 2e 0a 2a 2a 0a 2a 2a 20 5e 4d 65 74 61 64 61 74  ..**.** ^Metadat
35ff0 61 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 79  a is returned by
36000 20 77 72 69 74 69 6e 67 20 74 6f 20 74 68 65 20   writing to the 
36010 6d 65 6d 6f 72 79 20 6c 6f 63 61 74 69 6f 6e 73  memory locations
36020 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 35   passed as the 5
36030 74 68 0a 2a 2a 20 61 6e 64 20 73 75 62 73 65 71  th.** and subseq
36040 75 65 6e 74 20 70 61 72 61 6d 65 74 65 72 73 20  uent parameters 
36050 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  to this function
36060 2e 20 5e 41 6e 79 20 6f 66 20 74 68 65 73 65 20  . ^Any of these 
36070 61 72 67 75 6d 65 6e 74 73 20 6d 61 79 20 62 65  arguments may be
36080 0a 2a 2a 20 4e 55 4c 4c 2c 20 69 6e 20 77 68 69  .** NULL, in whi
36090 63 68 20 63 61 73 65 20 74 68 65 20 63 6f 72 72  ch case the corr
360a0 65 73 70 6f 6e 64 69 6e 67 20 65 6c 65 6d 65 6e  esponding elemen
360b0 74 20 6f 66 20 6d 65 74 61 64 61 74 61 20 69 73  t of metadata is
360c0 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20   omitted..**.** 
360d0 5e 28 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ^(<blockquote>.*
360e0 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d  * <table border=
360f0 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e  "1">.** <tr><th>
36100 20 50 61 72 61 6d 65 74 65 72 20 3c 74 68 3e 20   Parameter <th> 
36110 4f 75 74 70 75 74 3c 62 72 3e 54 79 70 65 20 3c  Output<br>Type <
36120 74 68 3e 20 20 44 65 73 63 72 69 70 74 69 6f 6e  th>  Description
36130 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  .**.** <tr><td> 
36140 35 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63  5th <td> const c
36150 68 61 72 2a 20 3c 74 64 3e 20 44 61 74 61 20 74  har* <td> Data t
36160 79 70 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ype.** <tr><td> 
36170 36 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63  6th <td> const c
36180 68 61 72 2a 20 3c 74 64 3e 20 4e 61 6d 65 20 6f  har* <td> Name o
36190 66 20 64 65 66 61 75 6c 74 20 63 6f 6c 6c 61 74  f default collat
361a0 69 6f 6e 20 73 65 71 75 65 6e 63 65 0a 2a 2a 20  ion sequence.** 
361b0 3c 74 72 3e 3c 74 64 3e 20 37 74 68 20 3c 74 64  <tr><td> 7th <td
361c0 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74  > int         <t
361d0 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d  d> True if colum
361e0 6e 20 68 61 73 20 61 20 4e 4f 54 20 4e 55 4c 4c  n has a NOT NULL
361f0 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 3c   constraint.** <
36200 74 72 3e 3c 74 64 3e 20 38 74 68 20 3c 74 64 3e  tr><td> 8th <td>
36210 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64   int         <td
36220 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e  > True if column
36230 20 69 73 20 70 61 72 74 20 6f 66 20 74 68 65 20   is part of the 
36240 50 52 49 4d 41 52 59 20 4b 45 59 0a 2a 2a 20 3c  PRIMARY KEY.** <
36250 74 72 3e 3c 74 64 3e 20 39 74 68 20 3c 74 64 3e  tr><td> 9th <td>
36260 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64   int         <td
36270 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e  > True if column
36280 20 69 73 20 5b 41 55 54 4f 49 4e 43 52 45 4d 45   is [AUTOINCREME
36290 4e 54 5d 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a  NT].** </table>.
362a0 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  ** </blockquote>
362b0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65  )^.**.** ^The me
362c0 6d 6f 72 79 20 70 6f 69 6e 74 65 64 20 74 6f 20  mory pointed to 
362d0 62 79 20 74 68 65 20 63 68 61 72 61 63 74 65 72  by the character
362e0 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
362f0 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 64 65  ed for the.** de
36300 63 6c 61 72 61 74 69 6f 6e 20 74 79 70 65 20 61  claration type a
36310 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  nd collation seq
36320 75 65 6e 63 65 20 69 73 20 76 61 6c 69 64 20 6f  uence is valid o
36330 6e 6c 79 20 75 6e 74 69 6c 20 74 68 65 20 6e 65  nly until the ne
36340 78 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 61 6e  xt.** call to an
36350 79 20 53 51 4c 69 74 65 20 41 50 49 20 66 75 6e  y SQLite API fun
36360 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  ction..**.** ^If
36370 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20 74   the specified t
36380 61 62 6c 65 20 69 73 20 61 63 74 75 61 6c 6c 79  able is actually
36390 20 61 20 76 69 65 77 2c 20 61 6e 20 5b 65 72 72   a view, an [err
363a0 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
363b0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  rned..**.** ^If 
363c0 74 68 65 20 73 70 65 63 69 66 69 65 64 20 63 6f  the specified co
363d0 6c 75 6d 6e 20 69 73 20 22 72 6f 77 69 64 22 2c  lumn is "rowid",
363e0 20 22 6f 69 64 22 20 6f 72 20 22 5f 72 6f 77 69   "oid" or "_rowi
363f0 64 5f 22 20 61 6e 64 20 61 6e 0a 2a 2a 20 5b 49  d_" and an.** [I
36400 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b  NTEGER PRIMARY K
36410 45 59 5d 20 63 6f 6c 75 6d 6e 20 68 61 73 20 62  EY] column has b
36420 65 65 6e 20 65 78 70 6c 69 63 69 74 6c 79 20 64  een explicitly d
36430 65 63 6c 61 72 65 64 2c 20 74 68 65 6e 20 74 68  eclared, then th
36440 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72 61  e output.** para
36450 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20 66  meters are set f
36460 6f 72 20 74 68 65 20 65 78 70 6c 69 63 69 74 6c  or the explicitl
36470 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  y declared colum
36480 6e 2e 20 5e 28 49 66 20 74 68 65 72 65 20 69 73  n. ^(If there is
36490 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63 69 74 6c   no.** explicitl
364a0 79 20 64 65 63 6c 61 72 65 64 20 5b 49 4e 54 45  y declared [INTE
364b0 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d  GER PRIMARY KEY]
364c0 20 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20 74 68   column, then th
364d0 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72 61  e output.** para
364e0 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20 61  meters are set a
364f0 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
36500 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 64 61   <pre>.**     da
36510 74 61 20 74 79 70 65 3a 20 22 49 4e 54 45 47 45  ta type: "INTEGE
36520 52 22 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c 61 74  R".**     collat
36530 69 6f 6e 20 73 65 71 75 65 6e 63 65 3a 20 22 42  ion sequence: "B
36540 49 4e 41 52 59 22 0a 2a 2a 20 20 20 20 20 6e 6f  INARY".**     no
36550 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20 20  t null: 0.**    
36560 20 70 72 69 6d 61 72 79 20 6b 65 79 3a 20 31 0a   primary key: 1.
36570 2a 2a 20 20 20 20 20 61 75 74 6f 20 69 6e 63 72  **     auto incr
36580 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70 72  ement: 0.** </pr
36590 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69  e>)^.**.** ^(Thi
365a0 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6c  s function may l
365b0 6f 61 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  oad one or more 
365c0 73 63 68 65 6d 61 73 20 66 72 6f 6d 20 64 61 74  schemas from dat
365d0 61 62 61 73 65 20 66 69 6c 65 73 2e 20 49 66 20  abase files. If 
365e0 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f 63 63 75  an.** error occu
365f0 72 73 20 64 75 72 69 6e 67 20 74 68 69 73 20 70  rs during this p
36600 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 74 68  rocess, or if th
36610 65 20 72 65 71 75 65 73 74 65 64 20 74 61 62 6c  e requested tabl
36620 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 63  e or column.** c
36630 61 6e 6e 6f 74 20 62 65 20 66 6f 75 6e 64 2c 20  annot be found, 
36640 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
36650 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20  is returned and 
36660 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
36670 20 6c 65 66 74 0a 2a 2a 20 69 6e 20 74 68 65 20   left.** in the 
36680 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
36690 74 69 6f 6e 5d 20 28 74 6f 20 62 65 20 72 65 74  tion] (to be ret
366a0 72 69 65 76 65 64 20 75 73 69 6e 67 20 73 71 6c  rieved using sql
366b0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 29 2e 29  ite3_errmsg()).)
366c0 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 41 50  ^.**.** ^This AP
366d0 49 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61  I is only availa
366e0 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61  ble if the libra
366f0 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  ry was compiled 
36700 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
36710 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d  ITE_ENABLE_COLUM
36720 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72  N_METADATA] C-pr
36730 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f  eprocessor symbo
36740 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e  l defined..*/.in
36750 74 20 73 71 6c 69 74 65 33 5f 74 61 62 6c 65 5f  t sqlite3_table_
36760 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61 74 61 28  column_metadata(
36770 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
36780 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
36790 2a 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e  * Connection han
367a0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
367b0 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20  har *zDbName,   
367c0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
367d0 20 6e 61 6d 65 20 6f 72 20 4e 55 4c 4c 20 2a 2f   name or NULL */
367e0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
367f0 54 61 62 6c 65 4e 61 6d 65 2c 20 20 20 20 20 2f  TableName,     /
36800 2a 20 54 61 62 6c 65 20 6e 61 6d 65 20 2a 2f 0a  * Table name */.
36810 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43    const char *zC
36820 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 20 20 20 2f 2a  olumnName,    /*
36830 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65 20 2a 2f 0a   Column name */.
36840 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70    char const **p
36850 7a 44 61 74 61 54 79 70 65 2c 20 20 20 20 2f 2a  zDataType,    /*
36860 20 4f 55 54 50 55 54 3a 20 44 65 63 6c 61 72 65   OUTPUT: Declare
36870 64 20 64 61 74 61 20 74 79 70 65 20 2a 2f 0a 20  d data type */. 
36880 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a   char const **pz
36890 43 6f 6c 6c 53 65 71 2c 20 20 20 20 20 2f 2a 20  CollSeq,     /* 
368a0 4f 55 54 50 55 54 3a 20 43 6f 6c 6c 61 74 69 6f  OUTPUT: Collatio
368b0 6e 20 73 65 71 75 65 6e 63 65 20 6e 61 6d 65 20  n sequence name 
368c0 2a 2f 0a 20 20 69 6e 74 20 2a 70 4e 6f 74 4e 75  */.  int *pNotNu
368d0 6c 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  ll,             
368e0 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65   /* OUTPUT: True
368f0 20 69 66 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e   if NOT NULL con
36900 73 74 72 61 69 6e 74 20 65 78 69 73 74 73 20 2a  straint exists *
36910 2f 0a 20 20 69 6e 74 20 2a 70 50 72 69 6d 61 72  /.  int *pPrimar
36920 79 4b 65 79 2c 20 20 20 20 20 20 20 20 20 20 20  yKey,           
36930 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20  /* OUTPUT: True 
36940 69 66 20 63 6f 6c 75 6d 6e 20 70 61 72 74 20 6f  if column part o
36950 66 20 50 4b 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  f PK */.  int *p
36960 41 75 74 6f 69 6e 63 20 20 20 20 20 20 20 20 20  Autoinc         
36970 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a        /* OUTPUT:
36980 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20   True if column 
36990 69 73 20 61 75 74 6f 2d 69 6e 63 72 65 6d 65 6e  is auto-incremen
369a0 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  t */.);../*.** C
369b0 41 50 49 33 52 45 46 3a 20 4c 6f 61 64 20 41 6e  API3REF: Load An
369c0 20 45 78 74 65 6e 73 69 6f 6e 0a 2a 2a 0a 2a 2a   Extension.**.**
369d0 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65   ^This interface
369e0 20 6c 6f 61 64 73 20 61 6e 20 53 51 4c 69 74 65   loads an SQLite
369f0 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61   extension libra
36a00 72 79 20 66 72 6f 6d 20 74 68 65 20 6e 61 6d 65  ry from the name
36a10 64 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  d file..**.** ^T
36a20 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f  he sqlite3_load_
36a30 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65  extension() inte
36a40 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
36a50 6f 20 6c 6f 61 64 20 61 6e 0a 2a 2a 20 53 51 4c  o load an.** SQL
36a60 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69  ite extension li
36a70 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 65 64 20  brary contained 
36a80 69 6e 20 74 68 65 20 66 69 6c 65 20 7a 46 69 6c  in the file zFil
36a90 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 65 6e  e..**.** ^The en
36aa0 74 72 79 20 70 6f 69 6e 74 20 69 73 20 7a 50 72  try point is zPr
36ab0 6f 63 2e 0a 2a 2a 20 5e 7a 50 72 6f 63 20 6d 61  oc..** ^zProc ma
36ac0 79 20 62 65 20 30 2c 20 69 6e 20 77 68 69 63 68  y be 0, in which
36ad0 20 63 61 73 65 20 74 68 65 20 6e 61 6d 65 20 6f   case the name o
36ae0 66 20 74 68 65 20 65 6e 74 72 79 20 70 6f 69 6e  f the entry poin
36af0 74 0a 2a 2a 20 64 65 66 61 75 6c 74 73 20 74 6f  t.** defaults to
36b00 20 22 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 73   "sqlite3_extens
36b10 69 6f 6e 5f 69 6e 69 74 22 2e 0a 2a 2a 20 5e 54  ion_init"..** ^T
36b20 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f  he sqlite3_load_
36b30 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65  extension() inte
36b40 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a  rface returns.**
36b50 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
36b60 73 75 63 63 65 73 73 20 61 6e 64 20 5b 53 51 4c  success and [SQL
36b70 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 73 6f  ITE_ERROR] if so
36b80 6d 65 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f  mething goes wro
36b90 6e 67 2e 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72  ng..** ^If an er
36ba0 72 6f 72 20 6f 63 63 75 72 73 20 61 6e 64 20 70  ror occurs and p
36bb0 7a 45 72 72 4d 73 67 20 69 73 20 6e 6f 74 20 30  zErrMsg is not 0
36bc0 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 73  , then the.** [s
36bd0 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
36be0 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65 72 66 61  nsion()] interfa
36bf0 63 65 20 73 68 61 6c 6c 20 61 74 74 65 6d 70 74  ce shall attempt
36c00 20 74 6f 0a 2a 2a 20 66 69 6c 6c 20 2a 70 7a 45   to.** fill *pzE
36c10 72 72 4d 73 67 20 77 69 74 68 20 65 72 72 6f 72  rrMsg with error
36c20 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 73 74   message text st
36c30 6f 72 65 64 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a  ored in memory.*
36c40 2a 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  * obtained from 
36c50 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
36c60 29 5d 2e 20 54 68 65 20 63 61 6c 6c 69 6e 67 20  )]. The calling 
36c70 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75  function.** shou
36c80 6c 64 20 66 72 65 65 20 74 68 69 73 20 6d 65 6d  ld free this mem
36c90 6f 72 79 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  ory by calling [
36ca0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
36cb0 0a 2a 2a 0a 2a 2a 20 5e 45 78 74 65 6e 73 69 6f  .**.** ^Extensio
36cc0 6e 20 6c 6f 61 64 69 6e 67 20 6d 75 73 74 20 62  n loading must b
36cd0 65 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 0a  e enabled using.
36ce0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62  ** [sqlite3_enab
36cf0 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  le_load_extensio
36d00 6e 28 29 5d 20 70 72 69 6f 72 20 74 6f 20 63 61  n()] prior to ca
36d10 6c 6c 69 6e 67 20 74 68 69 73 20 41 50 49 2c 0a  lling this API,.
36d20 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  ** otherwise an 
36d30 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65  error will be re
36d40 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65  turned..**.** Se
36d50 65 20 61 6c 73 6f 20 74 68 65 20 5b 6c 6f 61 64  e also the [load
36d60 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 53 51 4c  _extension() SQL
36d70 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2f 0a 69   function]..*/.i
36d80 6e 74 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f  nt sqlite3_load_
36d90 65 78 74 65 6e 73 69 6f 6e 28 0a 20 20 73 71 6c  extension(.  sql
36da0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
36db0 20 20 20 2f 2a 20 4c 6f 61 64 20 74 68 65 20 65     /* Load the e
36dc0 78 74 65 6e 73 69 6f 6e 20 69 6e 74 6f 20 74 68  xtension into th
36dd0 69 73 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  is database conn
36de0 65 63 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73  ection */.  cons
36df0 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 20  t char *zFile,  
36e00 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65    /* Name of the
36e10 20 73 68 61 72 65 64 20 6c 69 62 72 61 72 79 20   shared library 
36e20 63 6f 6e 74 61 69 6e 69 6e 67 20 65 78 74 65 6e  containing exten
36e30 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  sion */.  const 
36e40 63 68 61 72 20 2a 7a 50 72 6f 63 2c 20 20 20 20  char *zProc,    
36e50 2f 2a 20 45 6e 74 72 79 20 70 6f 69 6e 74 2e 20  /* Entry point. 
36e60 20 44 65 72 69 76 65 64 20 66 72 6f 6d 20 7a 46   Derived from zF
36e70 69 6c 65 20 69 66 20 30 20 2a 2f 0a 20 20 63 68  ile if 0 */.  ch
36e80 61 72 20 2a 2a 70 7a 45 72 72 4d 73 67 20 20 20  ar **pzErrMsg   
36e90 20 20 20 20 2f 2a 20 50 75 74 20 65 72 72 6f 72      /* Put error
36ea0 20 6d 65 73 73 61 67 65 20 68 65 72 65 20 69 66   message here if
36eb0 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a   not 0 */.);../*
36ec0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e  .** CAPI3REF: En
36ed0 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20  able Or Disable 
36ee0 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e  Extension Loadin
36ef0 67 0a 2a 2a 0a 2a 2a 20 5e 53 6f 20 61 73 20 6e  g.**.** ^So as n
36f00 6f 74 20 74 6f 20 6f 70 65 6e 20 73 65 63 75 72  ot to open secur
36f10 69 74 79 20 68 6f 6c 65 73 20 69 6e 20 6f 6c 64  ity holes in old
36f20 65 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  er applications 
36f30 74 68 61 74 20 61 72 65 0a 2a 2a 20 75 6e 70 72  that are.** unpr
36f40 65 70 61 72 65 64 20 74 6f 20 64 65 61 6c 20 77  epared to deal w
36f50 69 74 68 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f  ith extension lo
36f60 61 64 69 6e 67 2c 20 61 6e 64 20 61 73 20 61 20  ading, and as a 
36f70 6d 65 61 6e 73 20 6f 66 20 64 69 73 61 62 6c 69  means of disabli
36f80 6e 67 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 20  ng.** extension 
36f90 6c 6f 61 64 69 6e 67 20 77 68 69 6c 65 20 65 76  loading while ev
36fa0 61 6c 75 61 74 69 6e 67 20 75 73 65 72 2d 65 6e  aluating user-en
36fb0 74 65 72 65 64 20 53 51 4c 2c 20 74 68 65 20 66  tered SQL, the f
36fc0 6f 6c 6c 6f 77 69 6e 67 20 41 50 49 0a 2a 2a 20  ollowing API.** 
36fd0 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 74  is provided to t
36fe0 75 72 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33  urn the [sqlite3
36ff0 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
37000 29 5d 20 6d 65 63 68 61 6e 69 73 6d 20 6f 6e 20  )] mechanism on 
37010 61 6e 64 20 6f 66 66 2e 0a 2a 2a 0a 2a 2a 20 5e  and off..**.** ^
37020 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e  Extension loadin
37030 67 20 69 73 20 6f 66 66 20 62 79 20 64 65 66 61  g is off by defa
37040 75 6c 74 2e 20 53 65 65 20 74 69 63 6b 65 74 20  ult. See ticket 
37050 23 31 38 36 33 2e 0a 2a 2a 20 5e 43 61 6c 6c 20  #1863..** ^Call 
37060 74 68 65 20 73 71 6c 69 74 65 33 5f 65 6e 61 62  the sqlite3_enab
37070 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  le_load_extensio
37080 6e 28 29 20 72 6f 75 74 69 6e 65 20 77 69 74 68  n() routine with
37090 20 6f 6e 6f 66 66 3d 3d 31 0a 2a 2a 20 74 6f 20   onoff==1.** to 
370a0 74 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e 20 6c  turn extension l
370b0 6f 61 64 69 6e 67 20 6f 6e 20 61 6e 64 20 63 61  oading on and ca
370c0 6c 6c 20 69 74 20 77 69 74 68 20 6f 6e 6f 66 66  ll it with onoff
370d0 3d 3d 30 20 74 6f 20 74 75 72 6e 0a 2a 2a 20 69  ==0 to turn.** i
370e0 74 20 62 61 63 6b 20 6f 66 66 20 61 67 61 69 6e  t back off again
370f0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
37100 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74  _enable_load_ext
37110 65 6e 73 69 6f 6e 28 73 71 6c 69 74 65 33 20 2a  ension(sqlite3 *
37120 64 62 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a  db, int onoff);.
37130 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
37140 20 41 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 4c   Automatically L
37150 6f 61 64 20 53 74 61 74 69 63 61 6c 6c 79 20 4c  oad Statically L
37160 69 6e 6b 65 64 20 45 78 74 65 6e 73 69 6f 6e 73  inked Extensions
37170 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74  .**.** ^This int
37180 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74 68  erface causes th
37190 65 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20  e xEntryPoint() 
371a0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69  function to be i
371b0 6e 76 6f 6b 65 64 20 66 6f 72 0a 2a 2a 20 65 61  nvoked for.** ea
371c0 63 68 20 6e 65 77 20 5b 64 61 74 61 62 61 73 65  ch new [database
371d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61   connection] tha
371e0 74 20 69 73 20 63 72 65 61 74 65 64 2e 20 20 54  t is created.  T
371f0 68 65 20 69 64 65 61 20 68 65 72 65 20 69 73 20  he idea here is 
37200 74 68 61 74 0a 2a 2a 20 78 45 6e 74 72 79 50 6f  that.** xEntryPo
37210 69 6e 74 28 29 20 69 73 20 74 68 65 20 65 6e 74  int() is the ent
37220 72 79 20 70 6f 69 6e 74 20 66 6f 72 20 61 20 73  ry point for a s
37230 74 61 74 69 63 61 6c 6c 79 20 6c 69 6e 6b 65 64  tatically linked
37240 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f   SQLite extensio
37250 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 74 6f 20  n.** that is to 
37260 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  be automatically
37270 20 6c 6f 61 64 65 64 20 69 6e 74 6f 20 61 6c 6c   loaded into all
37280 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f   new database co
37290 6e 6e 65 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  nnections..**.**
372a0 20 5e 28 45 76 65 6e 20 74 68 6f 75 67 68 20 74   ^(Even though t
372b0 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 72 6f 74  he function prot
372c0 6f 74 79 70 65 20 73 68 6f 77 73 20 74 68 61 74  otype shows that
372d0 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20 74   xEntryPoint() t
372e0 61 6b 65 73 0a 2a 2a 20 6e 6f 20 61 72 67 75 6d  akes.** no argum
372f0 65 6e 74 73 20 61 6e 64 20 72 65 74 75 72 6e 73  ents and returns
37300 20 76 6f 69 64 2c 20 53 51 4c 69 74 65 20 69 6e   void, SQLite in
37310 76 6f 6b 65 73 20 78 45 6e 74 72 79 50 6f 69 6e  vokes xEntryPoin
37320 74 28 29 20 77 69 74 68 20 74 68 72 65 65 0a 2a  t() with three.*
37330 2a 20 61 72 67 75 6d 65 6e 74 73 20 61 6e 64 20  * arguments and 
37340 65 78 70 65 63 74 73 20 61 6e 64 20 69 6e 74 65  expects and inte
37350 67 65 72 20 72 65 73 75 6c 74 20 61 73 20 69 66  ger result as if
37360 20 74 68 65 20 73 69 67 6e 61 74 75 72 65 20 6f   the signature o
37370 66 20 74 68 65 0a 2a 2a 20 65 6e 74 72 79 20 70  f the.** entry p
37380 6f 69 6e 74 20 77 68 65 72 65 20 61 73 20 66 6f  oint where as fo
37390 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
373a0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
373b0 2a 20 26 6e 62 73 70 3b 20 20 69 6e 74 20 78 45  * &nbsp;  int xE
373c0 6e 74 72 79 50 6f 69 6e 74 28 0a 2a 2a 20 26 6e  ntryPoint(.** &n
373d0 62 73 70 3b 20 20 20 20 73 71 6c 69 74 65 33 20  bsp;    sqlite3 
373e0 2a 64 62 2c 0a 2a 2a 20 26 6e 62 73 70 3b 20 20  *db,.** &nbsp;  
373f0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70    const char **p
37400 7a 45 72 72 4d 73 67 2c 0a 2a 2a 20 26 6e 62 73  zErrMsg,.** &nbs
37410 70 3b 20 20 20 20 63 6f 6e 73 74 20 73 74 72 75  p;    const stru
37420 63 74 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72  ct sqlite3_api_r
37430 6f 75 74 69 6e 65 73 20 2a 70 54 68 75 6e 6b 0a  outines *pThunk.
37440 2a 2a 20 26 6e 62 73 70 3b 20 20 29 3b 0a 2a 2a  ** &nbsp;  );.**
37450 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
37460 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 49 66 20  ote>)^.**.** If 
37470 74 68 65 20 78 45 6e 74 72 79 50 6f 69 6e 74 20  the xEntryPoint 
37480 72 6f 75 74 69 6e 65 20 65 6e 63 6f 75 6e 74 65  routine encounte
37490 72 73 20 61 6e 20 65 72 72 6f 72 2c 20 69 74 20  rs an error, it 
374a0 73 68 6f 75 6c 64 20 6d 61 6b 65 20 2a 70 7a 45  should make *pzE
374b0 72 72 4d 73 67 0a 2a 2a 20 70 6f 69 6e 74 20 74  rrMsg.** point t
374c0 6f 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  o an appropriate
374d0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 28   error message (
374e0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
374f0 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
37500 5d 29 0a 2a 2a 20 61 6e 64 20 72 65 74 75 72 6e  ]).** and return
37510 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
37520 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 20 20 5e  [error code].  ^
37530 53 51 4c 69 74 65 20 65 6e 73 75 72 65 73 20 74  SQLite ensures t
37540 68 61 74 20 2a 70 7a 45 72 72 4d 73 67 0a 2a 2a  hat *pzErrMsg.**
37550 20 69 73 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20   is NULL before 
37560 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 45 6e 74  calling the xEnt
37570 72 79 50 6f 69 6e 74 28 29 2e 20 20 5e 53 51 4c  ryPoint().  ^SQL
37580 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a  ite will invoke.
37590 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
375a0 28 29 5d 20 6f 6e 20 2a 70 7a 45 72 72 4d 73 67  ()] on *pzErrMsg
375b0 20 61 66 74 65 72 20 78 45 6e 74 72 79 50 6f 69   after xEntryPoi
375c0 6e 74 28 29 20 72 65 74 75 72 6e 73 2e 20 20 5e  nt() returns.  ^
375d0 49 66 20 61 6e 79 0a 2a 2a 20 78 45 6e 74 72 79  If any.** xEntry
375e0 50 6f 69 6e 74 28 29 20 72 65 74 75 72 6e 73 20  Point() returns 
375f0 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 20 5b 73  an error, the [s
37600 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
37610 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
37620 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  )],.** or [sqlit
37630 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 63 61  e3_open_v2()] ca
37640 6c 6c 20 74 68 61 74 20 70 72 6f 76 6f 6b 65 64  ll that provoked
37650 20 74 68 65 20 78 45 6e 74 72 79 50 6f 69 6e 74   the xEntryPoint
37660 28 29 20 77 69 6c 6c 20 66 61 69 6c 2e 0a 2a 2a  () will fail..**
37670 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c  .** ^Calling sql
37680 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73  ite3_auto_extens
37690 69 6f 6e 28 58 29 20 77 69 74 68 20 61 6e 20 65  ion(X) with an e
376a0 6e 74 72 79 20 70 6f 69 6e 74 20 58 20 74 68 61  ntry point X tha
376b0 74 20 69 73 20 61 6c 72 65 61 64 79 0a 2a 2a 20  t is already.** 
376c0 6f 6e 20 74 68 65 20 6c 69 73 74 20 6f 66 20 61  on the list of a
376d0 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69  utomatic extensi
376e0 6f 6e 73 20 69 73 20 61 20 68 61 72 6d 6c 65 73  ons is a harmles
376f0 73 20 6e 6f 2d 6f 70 2e 20 5e 4e 6f 20 65 6e 74  s no-op. ^No ent
37700 72 79 20 70 6f 69 6e 74 0a 2a 2a 20 77 69 6c 6c  ry point.** will
37710 20 62 65 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20   be called more 
37720 74 68 61 6e 20 6f 6e 63 65 20 66 6f 72 20 65 61  than once for ea
37730 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ch database conn
37740 65 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20 6f  ection that is o
37750 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  pened..**.** See
37760 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
37770 72 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e  reset_auto_exten
37780 73 69 6f 6e 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  sion()]..*/.int 
37790 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74  sqlite3_auto_ext
377a0 65 6e 73 69 6f 6e 28 76 6f 69 64 20 28 2a 78 45  ension(void (*xE
377b0 6e 74 72 79 50 6f 69 6e 74 29 28 76 6f 69 64 29  ntryPoint)(void)
377c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
377d0 45 46 3a 20 52 65 73 65 74 20 41 75 74 6f 6d 61  EF: Reset Automa
377e0 74 69 63 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f  tic Extension Lo
377f0 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  ading.**.** ^Thi
37800 73 20 69 6e 74 65 72 66 61 63 65 20 64 69 73 61  s interface disa
37810 62 6c 65 73 20 61 6c 6c 20 61 75 74 6f 6d 61 74  bles all automat
37820 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 70 72  ic extensions pr
37830 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 72 65 67 69  eviously.** regi
37840 73 74 65 72 65 64 20 75 73 69 6e 67 20 5b 73 71  stered using [sq
37850 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e  lite3_auto_exten
37860 73 69 6f 6e 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64  sion()]..*/.void
37870 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 5f 61   sqlite3_reset_a
37880 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f  uto_extension(vo
37890 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20  id);../*.** The 
378a0 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68 65  interface to the
378b0 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d   virtual-table m
378c0 65 63 68 61 6e 69 73 6d 20 69 73 20 63 75 72 72  echanism is curr
378d0 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64  ently considered
378e0 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69  .** to be experi
378f0 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74  mental.  The int
37900 65 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 61  erface might cha
37910 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69  nge in incompati
37920 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20  ble ways..** If 
37930 74 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65  this is a proble
37940 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f  m for you, do no
37950 74 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 66  t use the interf
37960 61 63 65 20 61 74 20 74 68 69 73 20 74 69 6d 65  ace at this time
37970 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
37980 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d   virtual-table m
37990 65 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c 69  echanism stabili
379a0 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63  zes, we will dec
379b0 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65  lare the.** inte
379c0 72 66 61 63 65 20 66 69 78 65 64 2c 20 73 75 70  rface fixed, sup
379d0 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69  port it indefini
379e0 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65  tely, and remove
379f0 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a   this comment..*
37a00 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74 72 75 63 74 75  /../*.** Structu
37a10 72 65 73 20 75 73 65 64 20 62 79 20 74 68 65 20  res used by the 
37a20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6e  virtual table in
37a30 74 65 72 66 61 63 65 0a 2a 2f 0a 74 79 70 65 64  terface.*/.typed
37a40 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
37a50 33 5f 76 74 61 62 20 73 71 6c 69 74 65 33 5f 76  3_vtab sqlite3_v
37a60 74 61 62 3b 0a 74 79 70 65 64 65 66 20 73 74 72  tab;.typedef str
37a70 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  uct sqlite3_inde
37a80 78 5f 69 6e 66 6f 20 73 71 6c 69 74 65 33 5f 69  x_info sqlite3_i
37a90 6e 64 65 78 5f 69 6e 66 6f 3b 0a 74 79 70 65 64  ndex_info;.typed
37aa0 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
37ab0 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 73 71  3_vtab_cursor sq
37ac0 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
37ad0 72 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  r;.typedef struc
37ae0 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  t sqlite3_module
37af0 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 3b   sqlite3_module;
37b00 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
37b10 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20  : Virtual Table 
37b20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52  Object.** KEYWOR
37b30 44 53 3a 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75  DS: sqlite3_modu
37b40 6c 65 20 7b 76 69 72 74 75 61 6c 20 74 61 62 6c  le {virtual tabl
37b50 65 20 6d 6f 64 75 6c 65 7d 0a 2a 2a 0a 2a 2a 20  e module}.**.** 
37b60 54 68 69 73 20 73 74 72 75 63 74 75 72 65 2c 20  This structure, 
37b70 73 6f 6d 65 74 69 6d 65 73 20 63 61 6c 6c 65 64  sometimes called
37b80 20 61 20 22 76 69 72 74 75 61 6c 20 74 61 62 6c   a "virtual tabl
37b90 65 20 6d 6f 64 75 6c 65 22 2c 20 0a 2a 2a 20 64  e module", .** d
37ba0 65 66 69 6e 65 73 20 74 68 65 20 69 6d 70 6c 65  efines the imple
37bb0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 20 5b  mentation of a [
37bc0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 2e  virtual tables].
37bd0 20 20 0a 2a 2a 20 54 68 69 73 20 73 74 72 75 63    .** This struc
37be0 74 75 72 65 20 63 6f 6e 73 69 73 74 73 20 6d 6f  ture consists mo
37bf0 73 74 6c 79 20 6f 66 20 6d 65 74 68 6f 64 73 20  stly of methods 
37c00 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a  for the module..
37c10 2a 2a 0a 2a 2a 20 5e 41 20 76 69 72 74 75 61 6c  **.** ^A virtual
37c20 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 20 69 73   table module is
37c30 20 63 72 65 61 74 65 64 20 62 79 20 66 69 6c 6c   created by fill
37c40 69 6e 67 20 69 6e 20 61 20 70 65 72 73 69 73 74  ing in a persist
37c50 65 6e 74 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20  ent.** instance 
37c60 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72  of this structur
37c70 65 20 61 6e 64 20 70 61 73 73 69 6e 67 20 61 20  e and passing a 
37c80 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20  pointer to that 
37c90 69 6e 73 74 61 6e 63 65 0a 2a 2a 20 74 6f 20 5b  instance.** to [
37ca0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d  sqlite3_create_m
37cb0 6f 64 75 6c 65 28 29 5d 20 6f 72 20 5b 73 71 6c  odule()] or [sql
37cc0 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75  ite3_create_modu
37cd0 6c 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 5e 54 68  le_v2()]..** ^Th
37ce0 65 20 72 65 67 69 73 74 72 61 74 69 6f 6e 20 72  e registration r
37cf0 65 6d 61 69 6e 73 20 76 61 6c 69 64 20 75 6e 74  emains valid unt
37d00 69 6c 20 69 74 20 69 73 20 72 65 70 6c 61 63 65  il it is replace
37d10 64 20 62 79 20 61 20 64 69 66 66 65 72 65 6e 74  d by a different
37d20 0a 2a 2a 20 6d 6f 64 75 6c 65 20 6f 72 20 75 6e  .** module or un
37d30 74 69 6c 20 74 68 65 20 5b 64 61 74 61 62 61 73  til the [databas
37d40 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63 6c  e connection] cl
37d50 6f 73 65 73 2e 20 20 54 68 65 20 63 6f 6e 74 65  oses.  The conte
37d60 6e 74 0a 2a 2a 20 6f 66 20 74 68 69 73 20 73 74  nt.** of this st
37d70 72 75 63 74 75 72 65 20 6d 75 73 74 20 6e 6f 74  ructure must not
37d80 20 63 68 61 6e 67 65 20 77 68 69 6c 65 20 69 74   change while it
37d90 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20 77   is registered w
37da0 69 74 68 0a 2a 2a 20 61 6e 79 20 64 61 74 61 62  ith.** any datab
37db0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a  ase connection..
37dc0 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  */.struct sqlite
37dd0 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20 69 6e 74  3_module {.  int
37de0 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74   iVersion;.  int
37df0 20 28 2a 78 43 72 65 61 74 65 29 28 73 71 6c 69   (*xCreate)(sqli
37e00 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78  te3*, void *pAux
37e10 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
37e20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74   int argc, const
37e30 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67   char *const*arg
37e40 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  v,.             
37e50 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a    sqlite3_vtab *
37e60 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29  *ppVTab, char**)
37e70 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6e 6e 65  ;.  int (*xConne
37e80 63 74 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f  ct)(sqlite3*, vo
37e90 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20  id *pAux,.      
37ea0 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67           int arg
37eb0 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63  c, const char *c
37ec0 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20  onst*argv,.     
37ed0 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65            sqlite
37ee0 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c  3_vtab **ppVTab,
37ef0 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20   char**);.  int 
37f00 28 2a 78 42 65 73 74 49 6e 64 65 78 29 28 73 71  (*xBestIndex)(sq
37f10 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
37f20 62 2c 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  b, sqlite3_index
37f30 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74 20 28  _info*);.  int (
37f40 2a 78 44 69 73 63 6f 6e 6e 65 63 74 29 28 73 71  *xDisconnect)(sq
37f50 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
37f60 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 73  b);.  int (*xDes
37f70 74 72 6f 79 29 28 73 71 6c 69 74 65 33 5f 76 74  troy)(sqlite3_vt
37f80 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e  ab *pVTab);.  in
37f90 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74  t (*xOpen)(sqlit
37fa0 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20  e3_vtab *pVTab, 
37fb0 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
37fc0 73 6f 72 20 2a 2a 70 70 43 75 72 73 6f 72 29 3b  sor **ppCursor);
37fd0 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29  .  int (*xClose)
37fe0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75  (sqlite3_vtab_cu
37ff0 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  rsor*);.  int (*
38000 78 46 69 6c 74 65 72 29 28 73 71 6c 69 74 65 33  xFilter)(sqlite3
38010 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 69  _vtab_cursor*, i
38020 6e 74 20 69 64 78 4e 75 6d 2c 20 63 6f 6e 73 74  nt idxNum, const
38030 20 63 68 61 72 20 2a 69 64 78 53 74 72 2c 0a 20   char *idxStr,. 
38040 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
38050 6e 74 20 61 72 67 63 2c 20 73 71 6c 69 74 65 33  nt argc, sqlite3
38060 5f 76 61 6c 75 65 20 2a 2a 61 72 67 76 29 3b 0a  _value **argv);.
38070 20 20 69 6e 74 20 28 2a 78 4e 65 78 74 29 28 73    int (*xNext)(s
38080 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
38090 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 45  or*);.  int (*xE
380a0 6f 66 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  of)(sqlite3_vtab
380b0 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74  _cursor*);.  int
380c0 20 28 2a 78 43 6f 6c 75 6d 6e 29 28 73 71 6c 69   (*xColumn)(sqli
380d0 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a  te3_vtab_cursor*
380e0 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  , sqlite3_contex
380f0 74 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20  t*, int);.  int 
38100 28 2a 78 52 6f 77 69 64 29 28 73 71 6c 69 74 65  (*xRowid)(sqlite
38110 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20  3_vtab_cursor*, 
38120 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70  sqlite3_int64 *p
38130 52 6f 77 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a  Rowid);.  int (*
38140 78 55 70 64 61 74 65 29 28 73 71 6c 69 74 65 33  xUpdate)(sqlite3
38150 5f 76 74 61 62 20 2a 2c 20 69 6e 74 2c 20 73 71  _vtab *, int, sq
38160 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 2c 20  lite3_value **, 
38170 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 29  sqlite3_int64 *)
38180 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 67 69 6e  ;.  int (*xBegin
38190 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
381a0 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a  pVTab);.  int (*
381b0 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 76  xSync)(sqlite3_v
381c0 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69  tab *pVTab);.  i
381d0 6e 74 20 28 2a 78 43 6f 6d 6d 69 74 29 28 73 71  nt (*xCommit)(sq
381e0 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
381f0 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f 6c  b);.  int (*xRol
38200 6c 62 61 63 6b 29 28 73 71 6c 69 74 65 33 5f 76  lback)(sqlite3_v
38210 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69  tab *pVTab);.  i
38220 6e 74 20 28 2a 78 46 69 6e 64 46 75 6e 63 74 69  nt (*xFindFuncti
38230 6f 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  on)(sqlite3_vtab
38240 20 2a 70 56 74 61 62 2c 20 69 6e 74 20 6e 41 72   *pVtab, int nAr
38250 67 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  g, const char *z
38260 4e 61 6d 65 2c 0a 20 20 20 20 20 20 20 20 20 20  Name,.          
38270 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69               voi
38280 64 20 28 2a 2a 70 78 46 75 6e 63 29 28 73 71 6c  d (**pxFunc)(sql
38290 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
382a0 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
382b0 2a 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  *),.            
382c0 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 20             void 
382d0 2a 2a 70 70 41 72 67 29 3b 0a 20 20 69 6e 74 20  **ppArg);.  int 
382e0 28 2a 78 52 65 6e 61 6d 65 29 28 73 71 6c 69 74  (*xRename)(sqlit
382f0 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20  e3_vtab *pVtab, 
38300 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 65 77  const char *zNew
38310 29 3b 0a 20 20 2f 2a 20 54 68 65 20 6d 65 74 68  );.  /* The meth
38320 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
38330 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68   version 1 of th
38340 65 20 73 71 6c 69 74 65 5f 6d 6f 64 75 6c 65 20  e sqlite_module 
38350 6f 62 6a 65 63 74 2e 20 54 68 6f 73 65 20 0a 20  object. Those . 
38360 20 2a 2a 20 62 65 6c 6f 77 20 61 72 65 20 66 6f   ** below are fo
38370 72 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20  r version 2 and 
38380 67 72 65 61 74 65 72 2e 20 2a 2f 0a 20 20 69 6e  greater. */.  in
38390 74 20 28 2a 78 53 61 76 65 70 6f 69 6e 74 29 28  t (*xSavepoint)(
383a0 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
383b0 54 61 62 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74  Tab, int);.  int
383c0 20 28 2a 78 52 65 6c 65 61 73 65 29 28 73 71 6c   (*xRelease)(sql
383d0 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
383e0 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
383f0 78 52 6f 6c 6c 62 61 63 6b 54 6f 29 28 73 71 6c  xRollbackTo)(sql
38400 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
38410 2c 20 69 6e 74 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a  , int);.};../*.*
38420 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74  * CAPI3REF: Virt
38430 75 61 6c 20 54 61 62 6c 65 20 49 6e 64 65 78 69  ual Table Indexi
38440 6e 67 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ng Information.*
38450 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69  * KEYWORDS: sqli
38460 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 0a 2a  te3_index_info.*
38470 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
38480 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72 75  _index_info stru
38490 63 74 75 72 65 20 61 6e 64 20 69 74 73 20 73 75  cture and its su
384a0 62 73 74 72 75 63 74 75 72 65 73 20 69 73 20 75  bstructures is u
384b0 73 65 64 20 61 73 20 70 61 72 74 0a 2a 2a 20 6f  sed as part.** o
384c0 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74  f the [virtual t
384d0 61 62 6c 65 5d 20 69 6e 74 65 72 66 61 63 65 20  able] interface 
384e0 74 6f 0a 2a 2a 20 70 61 73 73 20 69 6e 66 6f 72  to.** pass infor
384f0 6d 61 74 69 6f 6e 20 69 6e 74 6f 20 61 6e 64 20  mation into and 
38500 72 65 63 65 69 76 65 20 74 68 65 20 72 65 70 6c  receive the repl
38510 79 20 66 72 6f 6d 20 74 68 65 20 5b 78 42 65 73  y from the [xBes
38520 74 49 6e 64 65 78 5d 0a 2a 2a 20 6d 65 74 68 6f  tIndex].** metho
38530 64 20 6f 66 20 61 20 5b 76 69 72 74 75 61 6c 20  d of a [virtual 
38540 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20  table module].  
38550 54 68 65 20 66 69 65 6c 64 73 20 75 6e 64 65 72  The fields under
38560 20 2a 2a 49 6e 70 75 74 73 2a 2a 20 61 72 65 20   **Inputs** are 
38570 74 68 65 0a 2a 2a 20 69 6e 70 75 74 73 20 74 6f  the.** inputs to
38580 20 78 42 65 73 74 49 6e 64 65 78 20 61 6e 64 20   xBestIndex and 
38590 61 72 65 20 72 65 61 64 2d 6f 6e 6c 79 2e 20 20  are read-only.  
385a0 78 42 65 73 74 49 6e 64 65 78 20 69 6e 73 65 72  xBestIndex inser
385b0 74 73 20 69 74 73 0a 2a 2a 20 72 65 73 75 6c 74  ts its.** result
385c0 73 20 69 6e 74 6f 20 74 68 65 20 2a 2a 4f 75 74  s into the **Out
385d0 70 75 74 73 2a 2a 20 66 69 65 6c 64 73 2e 0a 2a  puts** fields..*
385e0 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 43 6f 6e 73  *.** ^(The aCons
385f0 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 72  traint[] array r
38600 65 63 6f 72 64 73 20 57 48 45 52 45 20 63 6c 61  ecords WHERE cla
38610 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20  use constraints 
38620 6f 66 20 74 68 65 20 66 6f 72 6d 3a 0a 2a 2a 0a  of the form:.**.
38630 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 63  ** <blockquote>c
38640 6f 6c 75 6d 6e 20 4f 50 20 65 78 70 72 3c 2f 62  olumn OP expr</b
38650 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
38660 20 77 68 65 72 65 20 4f 50 20 69 73 20 3d 2c 20   where OP is =, 
38670 26 6c 74 3b 2c 20 26 6c 74 3b 3d 2c 20 26 67 74  &lt;, &lt;=, &gt
38680 3b 2c 20 6f 72 20 26 67 74 3b 3d 2e 29 5e 20 20  ;, or &gt;=.)^  
38690 5e 28 54 68 65 20 70 61 72 74 69 63 75 6c 61 72  ^(The particular
386a0 20 6f 70 65 72 61 74 6f 72 20 69 73 0a 2a 2a 20   operator is.** 
386b0 73 74 6f 72 65 64 20 69 6e 20 61 43 6f 6e 73 74  stored in aConst
386c0 72 61 69 6e 74 5b 5d 2e 6f 70 20 75 73 69 6e 67  raint[].op using
386d0 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b   one of the.** [
386e0 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e  SQLITE_INDEX_CON
386f0 53 54 52 41 49 4e 54 5f 45 51 20 7c 20 53 51 4c  STRAINT_EQ | SQL
38700 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52  ITE_INDEX_CONSTR
38710 41 49 4e 54 5f 20 76 61 6c 75 65 73 5d 2e 29 5e  AINT_ values].)^
38720 0a 2a 2a 20 5e 28 54 68 65 20 69 6e 64 65 78 20  .** ^(The index 
38730 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73  of the column is
38740 20 73 74 6f 72 65 64 20 69 6e 0a 2a 2a 20 61 43   stored in.** aC
38750 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 69 43 6f 6c  onstraint[].iCol
38760 75 6d 6e 2e 29 5e 20 20 5e 28 61 43 6f 6e 73 74  umn.)^  ^(aConst
38770 72 61 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 20 69  raint[].usable i
38780 73 20 54 52 55 45 20 69 66 20 74 68 65 0a 2a 2a  s TRUE if the.**
38790 20 65 78 70 72 20 6f 6e 20 74 68 65 20 72 69 67   expr on the rig
387a0 68 74 2d 68 61 6e 64 20 73 69 64 65 20 63 61 6e  ht-hand side can
387b0 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 28 61   be evaluated (a
387c0 6e 64 20 74 68 75 73 20 74 68 65 20 63 6f 6e 73  nd thus the cons
387d0 74 72 61 69 6e 74 0a 2a 2a 20 69 73 20 75 73 61  traint.** is usa
387e0 62 6c 65 29 20 61 6e 64 20 66 61 6c 73 65 20 69  ble) and false i
387f0 66 20 69 74 20 63 61 6e 6e 6f 74 2e 29 5e 0a 2a  f it cannot.)^.*
38800 2a 0a 2a 2a 20 5e 54 68 65 20 6f 70 74 69 6d 69  *.** ^The optimi
38810 7a 65 72 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  zer automaticall
38820 79 20 69 6e 76 65 72 74 73 20 74 65 72 6d 73 20  y inverts terms 
38830 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 65 78 70  of the form "exp
38840 72 20 4f 50 20 63 6f 6c 75 6d 6e 22 0a 2a 2a 20  r OP column".** 
38850 61 6e 64 20 6d 61 6b 65 73 20 6f 74 68 65 72 20  and makes other 
3