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

Artifact 6bff7c59ae3cec01e628800b79ae87a2897c576c:


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 2f 0a 23 64 65 66 69  e it.  .*/.#defi
85a0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
85b0: 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20 20  LOCKSTATE       
85c0: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
85d0: 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  E_GET_LOCKPROXYF
85e0: 49 4c 45 20 20 20 20 20 20 32 0a 23 64 65 66 69  ILE      2.#defi
85f0: 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f  ne SQLITE_SET_LO
8600: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20  CKPROXYFILE     
8610: 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
8620: 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20  E_LAST_ERRNO    
8630: 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69           4.#defi
8640: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
8650: 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20  SIZE_HINT       
8660: 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   5.#define SQLIT
8670: 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49  E_FCNTL_CHUNK_SI
8680: 5a 45 20 20 20 20 20 20 20 36 0a 23 64 65 66 69  ZE       6.#defi
8690: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
86a0: 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20  FILE_POINTER    
86b0: 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   7.#define SQLIT
86c0: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49  E_FCNTL_SYNC_OMI
86d0: 54 54 45 44 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a  TTED     8.../*.
86e0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74  ** CAPI3REF: Mut
86f0: 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20  ex Handle.**.** 
8700: 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65  The mutex module
8710: 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64   within SQLite d
8720: 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f  efines [sqlite3_
8730: 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a  mutex] to be an.
8740: 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70 65  ** abstract type
8750: 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a   for a mutex obj
8760: 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65  ect.  The SQLite
8770: 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b   core never look
8780: 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65  s.** at the inte
8790: 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74  rnal representat
87a0: 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  ion of an [sqlit
87b0: 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f  e3_mutex].  It o
87c0: 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74  nly.** deals wit
87d0: 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68  h pointers to th
87e0: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
87f0: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
8800: 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65 61  Mutexes are crea
8810: 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
8820: 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
8830: 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  ]..*/.typedef st
8840: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74  ruct sqlite3_mut
8850: 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ex sqlite3_mutex
8860: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
8870: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
8880: 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20  Object.**.** An 
8890: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
88a0: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
88b0: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
88c0: 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
88d0: 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63  .** the SQLite c
88e0: 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65  ore and the unde
88f0: 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67  rlying operating
8900: 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76   system.  The "v
8910: 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  fs".** in the na
8920: 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74  me of the object
8930: 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72   stands for "vir
8940: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
8950: 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b  ".  See.** the [
8960: 56 46 53 20 7c 20 56 46 53 20 64 6f 63 75 6d 65  VFS | VFS docume
8970: 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72  ntation] for fur
8980: 74 68 65 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  ther information
8990: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75  ..**.** The valu
89a0: 65 20 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f  e of the iVersio
89b0: 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69  n field is initi
89c0: 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62  ally 1 but may b
89d0: 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66  e larger in.** f
89e0: 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
89f0: 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74  f SQLite.  Addit
8a00: 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79  ional fields may
8a10: 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20   be appended to 
8a20: 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77  this.** object w
8a30: 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e  hen the iVersion
8a40: 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61   value is increa
8a50: 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20  sed.  Note that 
8a60: 74 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a  the structure.**
8a70: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
8a80: 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67  vfs object chang
8a90: 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61  es in the transa
8aa0: 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a  ction between.**
8ab0: 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
8ac0: 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20  3.5.9 and 3.6.0 
8ad0: 61 6e 64 20 79 65 74 20 74 68 65 20 69 56 65 72  and yet the iVer
8ae0: 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e  sion field was n
8af0: 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a  ot.** modified..
8b00: 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69  **.** The szOsFi
8b10: 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 20  le field is the 
8b20: 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63  size of the subc
8b30: 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f  lassed [sqlite3_
8b40: 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75  file].** structu
8b50: 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73 20  re used by this 
8b60: 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65  VFS.  mxPathname
8b70: 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20   is the maximum 
8b80: 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70  length of.** a p
8b90: 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20  athname in this 
8ba0: 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73  VFS..**.** Regis
8bb0: 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66  tered sqlite3_vf
8bc0: 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65  s objects are ke
8bd0: 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c  pt on a linked l
8be0: 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a  ist formed by.**
8bf0: 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74   the pNext point
8c00: 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  er.  The [sqlite
8c10: 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29  3_vfs_register()
8c20: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
8c30: 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72  3_vfs_unregister
8c40: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ()] interfaces m
8c50: 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a  anage this list.
8c60: 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73  ** in a thread-s
8c70: 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73  afe way.  The [s
8c80: 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28  qlite3_vfs_find(
8c90: 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  )] interface.** 
8ca0: 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 73  searches the lis
8cb0: 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65 20  t.  Neither the 
8cc0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65  application code
8cd0: 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20   nor the VFS.** 
8ce0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73  implementation s
8cf0: 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e  hould use the pN
8d00: 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ext pointer..**.
8d10: 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 65  ** The pNext fie
8d20: 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66  ld is the only f
8d30: 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69  ield in the sqli
8d40: 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63  te3_vfs.** struc
8d50: 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74 65  ture that SQLite
8d60: 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66   will ever modif
8d70: 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  y.  SQLite will 
8d80: 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f  only access.** o
8d90: 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69  r modify this fi
8da0: 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e  eld while holdin
8db0: 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 73  g a particular s
8dc0: 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20  tatic mutex..** 
8dd0: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
8de0: 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64  should never mod
8df0: 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74  ify anything wit
8e00: 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hin the sqlite3_
8e10: 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e  vfs.** object on
8e20: 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61  ce the object ha
8e30: 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72 65  s been registere
8e40: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61  d..**.** The zNa
8e50: 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74  me field holds t
8e60: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56  he name of the V
8e70: 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20  FS module.  The 
8e80: 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20  name must.** be 
8e90: 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c  unique across al
8ea0: 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a  l VFS modules..*
8eb0: 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76  *.** [[sqlite3_v
8ec0: 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53  fs.xOpen]].** ^S
8ed0: 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73  QLite guarantees
8ee0: 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e   that the zFilen
8ef0: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ame parameter to
8f00: 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74   xOpen.** is eit
8f10: 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  her a NULL point
8f20: 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74  er or string obt
8f30: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46  ained.** from xF
8f40: 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69  ullPathname() wi
8f50: 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73  th an optional s
8f60: 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20  uffix added..** 
8f70: 5e 49 66 20 61 20 73 75 66 66 69 78 20 69 73 20  ^If a suffix is 
8f80: 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69  added to the zFi
8f90: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
8fa0: 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e  , it will.** con
8fb0: 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65  sist of a single
8fc0: 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 20 66   "-" character f
8fd0: 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f  ollowed by no mo
8fe0: 72 65 20 74 68 61 6e 0a 2a 2a 20 31 30 20 61 6c  re than.** 10 al
8ff0: 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f  phanumeric and/o
9000: 72 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 73  r "-" characters
9010: 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72  ..** ^SQLite fur
9020: 74 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20  ther guarantees 
9030: 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69  that.** the stri
9040: 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64  ng will be valid
9050: 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75   and unchanged u
9060: 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73  ntil xClose() is
9070: 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61  .** called. Beca
9080: 75 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69  use of the previ
9090: 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a  ous sentence,.**
90a0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
90b0: 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73  le] can safely s
90c0: 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74  tore a pointer t
90d0: 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d  o the.** filenam
90e0: 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f  e if it needs to
90f0: 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69   remember the fi
9100: 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20  lename for some 
9110: 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68  reason..** If th
9120: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
9130: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69  meter to xOpen i
9140: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
9150: 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d   then xOpen.** m
9160: 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f  ust invent its o
9170: 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d  wn temporary nam
9180: 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20  e for the file. 
9190: 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a   ^Whenever the .
91a0: 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72  ** xFilename par
91b0: 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69  ameter is NULL i
91c0: 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74  t will also be t
91d0: 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
91e0: 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65  .** flags parame
91f0: 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65  ter will include
9200: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
9210: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a  LETEONCLOSE]..**
9220: 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72  .** The flags ar
9230: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28  gument to xOpen(
9240: 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62  ) includes all b
9250: 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68  its set in.** th
9260: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
9270: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
9280: 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20  n_v2()].  Or if 
9290: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
92a0: 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
92b0: 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65  open16()] is use
92c0: 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e  d, then flags in
92d0: 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a  cludes at least.
92e0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
92f0: 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
9300: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
9310: 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28  ]. .** If xOpen(
9320: 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72  ) opens a file r
9330: 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74  ead-only then it
9340: 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73   sets *pOutFlags
9350: 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b   to.** include [
9360: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
9370: 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69  ONLY].  Other bi
9380: 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73  ts in *pOutFlags
9390: 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a   may be set..**.
93a0: 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c  ** ^(SQLite will
93b0: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
93c0: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
93d0: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
93e0: 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70  n().** call, dep
93f0: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62  ending on the ob
9400: 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65  ject being opene
9410: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  d:.**.** <ul>.**
9420: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
9430: 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20  PEN_MAIN_DB].** 
9440: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
9450: 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d  EN_MAIN_JOURNAL]
9460: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
9470: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a  E_OPEN_TEMP_DB].
9480: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
9490: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e  _OPEN_TEMP_JOURN
94a0: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
94b0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49  LITE_OPEN_TRANSI
94c0: 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  ENT_DB].** <li> 
94d0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55   [SQLITE_OPEN_SU
94e0: 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  BJOURNAL].** <li
94f0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
9500: 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a  MASTER_JOURNAL].
9510: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
9520: 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f  _OPEN_WAL].** </
9530: 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ul>)^.**.** The 
9540: 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65  file I/O impleme
9550: 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20  ntation can use 
9560: 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20  the object type 
9570: 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e  flags to.** chan
9580: 67 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65  ge the way it de
9590: 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20  als with files. 
95a0: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e   For example, an
95b0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
95c0: 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61  that does not ca
95d0: 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72  re about crash r
95e0: 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62  ecovery or rollb
95f0: 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a  ack might make.*
9600: 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20  * the open of a 
9610: 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e  journal file a n
9620: 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f  o-op.  Writes to
9630: 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f   this journal wo
9640: 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e  uld.** also be n
9650: 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61  o-ops, and any a
9660: 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74  ttempt to read t
9670: 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64  he journal would
9680: 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54   return.** SQLIT
9690: 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65  E_IOERR.  Or the
96a0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
96b0: 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20  might recognize 
96c0: 74 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a  that a database.
96d0: 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20  ** file will be 
96e0: 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e  doing page-align
96f0: 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20  ed sector reads 
9700: 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20  and writes in a 
9710: 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20  random.** order 
9720: 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49  and set up its I
9730: 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63  /O subsystem acc
9740: 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ordingly..**.** 
9750: 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73  SQLite might als
9760: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
9770: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
9780: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65   to the xOpen me
9790: 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  thod:.**.** <ul>
97a0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
97b0: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
97c0: 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  OSE].** <li> [SQ
97d0: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
97e0: 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  IVE].** </ul>.**
97f0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
9800: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
9810: 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74  SE] flag means t
9820: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62  he file should b
9830: 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65  e.** deleted whe
9840: 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20  n it is closed. 
9850: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50   ^The [SQLITE_OP
9860: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
9870: 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74  ].** will be set
9880: 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61   for TEMP databa
9890: 73 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f  ses and their jo
98a0: 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e  urnals, transien
98b0: 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20  t.** databases, 
98c0: 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e  and subjournals.
98d0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  .**.** ^The [SQL
98e0: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
98f0: 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61  VE] flag is alwa
9900: 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75  ys used in conju
9910: 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74  nction.** with t
9920: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
9930: 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68  CREATE] flag, wh
9940: 69 63 68 20 61 72 65 20 62 6f 74 68 20 64 69 72  ich are both dir
9950: 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f  ectly.** analogo
9960: 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c  us to the O_EXCL
9970: 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61   and O_CREAT fla
9980: 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20  gs of the POSIX 
9990: 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20  open().** API.  
99a0: 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  The SQLITE_OPEN_
99b0: 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20  EXCLUSIVE flag, 
99c0: 77 68 65 6e 20 70 61 69 72 65 64 20 77 69 74 68  when paired with
99d0: 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f   the .** SQLITE_
99e0: 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20  OPEN_CREATE, is 
99f0: 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65  used to indicate
9a00: 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c   that file shoul
9a10: 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63  d always.** be c
9a20: 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74  reated, and that
9a30: 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20   it is an error 
9a40: 69 66 20 69 74 20 61 6c 72 65 61 64 79 20 65 78  if it already ex
9a50: 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c  ists..** It is <
9a60: 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74  i>not</i> used t
9a70: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65 20 66  o indicate the f
9a80: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70  ile should be op
9a90: 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63  ened .** for exc
9aa0: 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a  lusive access..*
9ab0: 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73  *.** ^At least s
9ac0: 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66  zOsFile bytes of
9ad0: 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f   memory are allo
9ae0: 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a  cated by SQLite.
9af0: 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20  ** to hold the  
9b00: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73  [sqlite3_file] s
9b10: 74 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20  tructure passed 
9b20: 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  as the third.** 
9b30: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
9b40: 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65  n.  The xOpen me
9b50: 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61  thod does not ha
9b60: 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74  ve to.** allocat
9b70: 65 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b  e the structure;
9b80: 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20   it should just 
9b90: 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74  fill it in.  Not
9ba0: 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f  e that.** the xO
9bb0: 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20  pen method must 
9bc0: 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  set the sqlite3_
9bd0: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f  file.pMethods to
9be0: 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c   either.** a val
9bf0: 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  id [sqlite3_io_m
9c00: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f  ethods] object o
9c10: 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65  r to NULL.  xOpe
9c20: 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69  n must do.** thi
9c30: 73 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70  s even if the op
9c40: 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74  en fails.  SQLit
9c50: 65 20 65 78 70 65 63 74 73 20 74 68 61 74 20 74  e expects that t
9c60: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
9c70: 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d  pMethods.** elem
9c80: 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69  ent will be vali
9c90: 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65  d after xOpen re
9ca0: 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73  turns regardless
9cb0: 20 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 0a   of the success.
9cc0: 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66  ** or failure of
9cd0: 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e   the xOpen call.
9ce0: 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33  .**.** [[sqlite3
9cf0: 5f 76 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a  _vfs.xAccess]].*
9d00: 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67  * ^The flags arg
9d10: 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73  ument to xAccess
9d20: 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54  () may be [SQLIT
9d30: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d  E_ACCESS_EXISTS]
9d40: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20  .** to test for 
9d50: 74 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66  the existence of
9d60: 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c   a file, or [SQL
9d70: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
9d80: 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74  RITE] to.** test
9d90: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20   whether a file 
9da0: 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  is readable and 
9db0: 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51  writable, or [SQ
9dc0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
9dd0: 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65  ].** to test whe
9de0: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61  ther a file is a
9df0: 74 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65  t least readable
9e00: 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e  .   The file can
9e10: 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f   be a.** directo
9e20: 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  ry..**.** ^SQLit
9e30: 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c  e will always al
9e40: 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20  locate at least 
9e50: 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74  mxPathname+1 byt
9e60: 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75  es for the.** ou
9e70: 74 70 75 74 20 62 75 66 66 65 72 20 78 46 75 6c  tput buffer xFul
9e80: 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20  lPathname.  The 
9e90: 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68  exact size of th
9ea0: 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a  e output buffer.
9eb0: 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65  ** is also passe
9ec0: 64 20 61 73 20 61 20 70 61 72 61 6d 65 74 65 72  d as a parameter
9ed0: 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64   to both  method
9ee0: 73 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75 74  s. If the output
9ef0: 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f   buffer.** is no
9f00: 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20  t large enough, 
9f10: 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  [SQLITE_CANTOPEN
9f20: 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75  ] should be retu
9f30: 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73  rned. Since this
9f40: 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61   is.** handled a
9f50: 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20  s a fatal error 
9f60: 62 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69  by SQLite, vfs i
9f70: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73  mplementations s
9f80: 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a  hould endeavor.*
9f90: 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69  * to prevent thi
9fa0: 73 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50  s by setting mxP
9fb0: 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66  athname to a suf
9fc0: 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20  ficiently large 
9fd0: 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  value..**.** The
9fe0: 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20   xRandomness(), 
9ff0: 78 53 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65  xSleep(), xCurre
a000: 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43  ntTime(), and xC
a010: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
a020: 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  ).** interfaces 
a030: 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  are not strictly
a040: 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66   a part of the f
a050: 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74  ilesystem, but t
a060: 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75  hey are.** inclu
a070: 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73  ded in the VFS s
a080: 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d  tructure for com
a090: 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68  pleteness..** Th
a0a0: 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20  e xRandomness() 
a0b0: 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74  function attempt
a0c0: 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74  s to return nByt
a0d0: 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67  es bytes.** of g
a0e0: 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64  ood-quality rand
a0f0: 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74  omness into zOut
a100: 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61  .  The return va
a110: 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63  lue is.** the ac
a120: 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62  tual number of b
a130: 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
a140: 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20  ss obtained..** 
a150: 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74  The xSleep() met
a160: 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63  hod causes the c
a170: 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f  alling thread to
a180: 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a   sleep for at.**
a190: 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65   least the numbe
a1a0: 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64  r of microsecond
a1b0: 73 20 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78  s given.  ^The x
a1c0: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a  CurrentTime().**
a1d0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
a1e0: 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d  a Julian Day Num
a1f0: 62 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72  ber for the curr
a200: 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d  ent date and tim
a210: 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69  e as.** a floati
a220: 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a  ng point value..
a230: 2a 2a 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74  ** ^The xCurrent
a240: 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68  TimeInt64() meth
a250: 6f 64 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61  od returns, as a
a260: 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a  n integer, the J
a270: 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d  ulian.** Day Num
a280: 62 65 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62  ber multiplied b
a290: 79 20 38 36 34 30 30 30 30 30 20 28 74 68 65 20  y 86400000 (the 
a2a0: 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73  number of millis
a2b0: 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20  econds in .** a 
a2c0: 32 34 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a  24-hour day).  .
a2d0: 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
a2e0: 75 73 65 20 74 68 65 20 78 43 75 72 72 65 6e 74  use the xCurrent
a2f0: 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68  TimeInt64() meth
a300: 6f 64 20 74 6f 20 67 65 74 20 74 68 65 20 63 75  od to get the cu
a310: 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e  rrent.** date an
a320: 64 20 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d  d time if that m
a330: 65 74 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62  ethod is availab
a340: 6c 65 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20  le (if iVersion 
a350: 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61  is 2 or .** grea
a360: 74 65 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63  ter and the func
a370: 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
a380: 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69  not NULL) and wi
a390: 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20  ll fall back.** 
a3a0: 74 6f 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  to xCurrentTime(
a3b0: 29 20 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d  ) if xCurrentTim
a3c0: 65 49 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76  eInt64() is unav
a3d0: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e  ailable..**.** ^
a3e0: 54 68 65 20 78 53 65 74 53 79 73 74 65 6d 43 61  The xSetSystemCa
a3f0: 6c 6c 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d  ll(), xGetSystem
a400: 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73  Call(), and xNes
a410: 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e  tSystemCall() in
a420: 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20  terfaces.** are 
a430: 6e 6f 74 20 75 73 65 64 20 62 79 20 74 68 65 20  not used by the 
a440: 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68  SQLite core.  Th
a450: 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74  ese optional int
a460: 65 72 66 61 63 65 73 20 61 72 65 20 70 72 6f 76  erfaces are prov
a470: 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20  ided.** by some 
a480: 56 46 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74  VFSes to facilit
a490: 61 74 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74  ate testing of t
a4a0: 68 65 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20  he VFS code. By 
a4b0: 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73  overriding .** s
a4c0: 79 73 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68  ystem calls with
a4d0: 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72   functions under
a4e0: 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20   its control, a 
a4f0: 74 65 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e  test program can
a500: 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75  .** simulate fau
a510: 6c 74 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f  lts and error co
a520: 6e 64 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f  nditions that wo
a530: 75 6c 64 20 6f 74 68 65 72 77 69 73 65 20 62 65  uld otherwise be
a540: 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72   difficult.** or
a550: 20 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69   impossible to i
a560: 6e 64 75 63 65 2e 20 20 54 68 65 20 73 65 74 20  nduce.  The set 
a570: 6f 66 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20  of system calls 
a580: 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72  that can be over
a590: 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73  ridden.** varies
a5a0: 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f   from one VFS to
a5b0: 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72   another, and fr
a5c0: 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f  om one version o
a5d0: 66 20 74 68 65 20 73 61 6d 65 20 56 46 53 20 74  f the same VFS t
a5e0: 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20  o the.** next.  
a5f0: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
a600: 74 20 75 73 65 20 74 68 65 73 65 20 69 6e 74 65  t use these inte
a610: 72 66 61 63 65 73 20 6d 75 73 74 20 62 65 20 70  rfaces must be p
a620: 72 65 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a  repared for any.
a630: 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65  ** or all of the
a640: 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f  se interfaces to
a650: 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20   be NULL or for 
a660: 74 68 65 69 72 20 62 65 68 61 76 69 6f 72 20 74  their behavior t
a670: 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d  o change.** from
a680: 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20   one release to 
a690: 74 68 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69  the next.  Appli
a6a0: 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74  cations must not
a6b0: 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65   attempt to acce
a6c0: 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65  ss.** any of the
a6d0: 73 65 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68  se methods if th
a6e0: 65 20 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68  e iVersion of th
a6f0: 65 20 56 46 53 20 69 73 20 6c 65 73 73 20 74 68  e VFS is less th
a700: 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  an 3..*/.typedef
a710: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
a720: 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b  vfs sqlite3_vfs;
a730: 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a  .typedef void (*
a740: 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f  sqlite3_syscall_
a750: 70 74 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75  ptr)(void);.stru
a760: 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b  ct sqlite3_vfs {
a770: 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b  .  int iVersion;
a780: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
a790: 74 72 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e  tructure version
a7a0: 20 6e 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74   number (current
a7b0: 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73  ly 3) */.  int s
a7c0: 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20  zOsFile;        
a7d0: 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73      /* Size of s
a7e0: 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65  ubclassed sqlite
a7f0: 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  3_file */.  int 
a800: 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20  mxPathname;     
a810: 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
a820: 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65  file pathname le
a830: 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65  ngth */.  sqlite
a840: 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20  3_vfs *pNext;   
a850: 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73     /* Next regis
a860: 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63  tered VFS */.  c
a870: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
a880: 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20  ;       /* Name 
a890: 6f 66 20 74 68 69 73 20 76 69 72 74 75 61 6c 20  of this virtual 
a8a0: 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20  file system */. 
a8b0: 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b   void *pAppData;
a8c0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69            /* Poi
a8d0: 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74  nter to applicat
a8e0: 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74  ion-specific dat
a8f0: 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70  a */.  int (*xOp
a900: 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  en)(sqlite3_vfs*
a910: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
a920: 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c  ame, sqlite3_fil
a930: 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  e*,.            
a940: 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e     int flags, in
a950: 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20  t *pOutFlags);. 
a960: 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28   int (*xDelete)(
a970: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
a980: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
a990: 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20   int syncDir);. 
a9a0: 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28   int (*xAccess)(
a9b0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
a9c0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
a9d0: 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20   int flags, int 
a9e0: 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74  *pResOut);.  int
a9f0: 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65   (*xFullPathname
aa00: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
aa10: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
aa20: 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61  e, int nOut, cha
aa30: 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64  r *zOut);.  void
aa40: 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c   *(*xDlOpen)(sql
aa50: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
aa60: 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65   char *zFilename
aa70: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45  );.  void (*xDlE
aa80: 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66  rror)(sqlite3_vf
aa90: 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63  s*, int nByte, c
aaa0: 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20  har *zErrMsg);. 
aab0: 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d   void (*(*xDlSym
aac0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76  )(sqlite3_vfs*,v
aad0: 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  oid*, const char
aae0: 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64   *zSymbol))(void
aaf0: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43  );.  void (*xDlC
ab00: 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lose)(sqlite3_vf
ab10: 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e  s*, void*);.  in
ab20: 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29  t (*xRandomness)
ab30: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
ab40: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
ab50: 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  zOut);.  int (*x
ab60: 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76  Sleep)(sqlite3_v
ab70: 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65  fs*, int microse
ab80: 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a  conds);.  int (*
ab90: 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71  xCurrentTime)(sq
aba0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62  lite3_vfs*, doub
abb0: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47  le*);.  int (*xG
abc0: 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c  etLastError)(sql
abd0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20  ite3_vfs*, int, 
abe0: 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20  char *);.  /*.  
abf0: 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61  ** The methods a
ac00: 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73  bove are in vers
ac10: 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c  ion 1 of the sql
ac20: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20  ite_vfs object. 
ac30: 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20   ** definition. 
ac40: 20 54 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c   Those that foll
ac50: 6f 77 20 61 72 65 20 61 64 64 65 64 20 69 6e 20  ow are added in 
ac60: 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74  version 2 or lat
ac70: 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  er.  */.  int (*
ac80: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
ac90: 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  4)(sqlite3_vfs*,
aca0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29   sqlite3_int64*)
acb0: 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20  ;.  /*.  ** The 
acc0: 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  methods above ar
acd0: 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20  e in versions 1 
ace0: 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c  and 2 of the sql
acf0: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a  ite_vfs object..
ad00: 20 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77    ** Those below
ad10: 20 61 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e   are for version
ad20: 20 33 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a   3 and greater..
ad30: 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65    */.  int (*xSe
ad40: 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c  tSystemCall)(sql
ad50: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
ad60: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71   char *zName, sq
ad70: 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74  lite3_syscall_pt
ad80: 72 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79  r);.  sqlite3_sy
ad90: 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74  scall_ptr (*xGet
ada0: 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
adb0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
adc0: 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20  char *zName);.  
add0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e  const char *(*xN
ade0: 65 78 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  extSystemCall)(s
adf0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
ae00: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
ae10: 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d  .  /*.  ** The m
ae20: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
ae30: 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74   in versions 1 t
ae40: 68 72 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20  hrough 3 of the 
ae50: 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
ae60: 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c  t..  ** New fiel
ae70: 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64  ds may be append
ae80: 65 64 20 69 6e 20 66 69 67 75 72 65 20 76 65 72  ed in figure ver
ae90: 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72  sions.  The iVer
aea0: 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20  sion.  ** value 
aeb0: 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77  will increment w
aec0: 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70  henever this hap
aed0: 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a  pens. .  */.};..
aee0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
aef0: 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41  Flags for the xA
af00: 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64  ccess VFS method
af10: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
af20: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63  eger constants c
af30: 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68  an be used as th
af40: 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
af50: 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63  r to.** the xAcc
af60: 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e  ess method of an
af70: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
af80: 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65 74  bject.  They det
af90: 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b  ermine.** what k
afa0: 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f  ind of permissio
afb0: 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ns the xAccess m
afc0: 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67  ethod is looking
afd0: 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51   for..** With SQ
afe0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
aff0: 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TS, the xAccess 
b000: 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79  method.** simply
b010: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
b020: 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e  the file exists.
b030: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
b040: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
b050: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
b060: 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77  thod.** checks w
b070: 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64  hether the named
b080: 20 64 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f   directory is bo
b090: 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  th readable and 
b0a0: 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20  writable.** (in 
b0b0: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20  other words, if 
b0c0: 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64  files can be add
b0d0: 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64  ed, removed, and
b0e0: 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a   renamed within.
b0f0: 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f 72 79  ** the directory
b100: 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  )..** The SQLITE
b110: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
b120: 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75  E constant is cu
b130: 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c  rrently used onl
b140: 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d  y by the.** [tem
b150: 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
b160: 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67  y pragma], thoug
b170: 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61  h this could cha
b180: 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a  nge in a future.
b190: 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  ** release of SQ
b1a0: 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51  Lite..** With SQ
b1b0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
b1c0: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
b1d0: 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77  thod.** checks w
b1e0: 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20  hether the file 
b1f0: 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68  is readable.  Th
b200: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
b210: 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73  READ constant is
b220: 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e  .** currently un
b230: 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20  used, though it 
b240: 6d 69 67 68 74 20 62 65 20 75 73 65 64 20 69 6e  might be used in
b250: 20 61 20 66 75 74 75 72 65 20 72 65 6c 65 61 73   a future releas
b260: 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a  e of.** SQLite..
b270: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
b280: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20  E_ACCESS_EXISTS 
b290: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
b2a0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
b2b0: 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64  RITE 1   /* Used
b2c0: 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f   by PRAGMA temp_
b2d0: 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
b2e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
b2f0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20 20  E_ACCESS_READ   
b300: 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64     2   /* Unused
b310: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
b320: 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74  REF: Flags for t
b330: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20  he xShmLock VFS 
b340: 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65  method.**.** The
b350: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
b360: 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65 20  ants define the 
b370: 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20  various locking 
b380: 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c  operations.** al
b390: 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78 53 68  lowed by the xSh
b3a0: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20  mLock method of 
b3b0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
b3c0: 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f  ods].  The.** fo
b3d0: 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20  llowing are the 
b3e0: 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69  only legal combi
b3f0: 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73  nations of flags
b400: 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c   to the.** xShmL
b410: 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a  ock method:.**.*
b420: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
b430: 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
b440: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  | SQLITE_SHM_SHA
b450: 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  RED.** <li>  SQL
b460: 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53  ITE_SHM_LOCK | S
b470: 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53  QLITE_SHM_EXCLUS
b480: 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  IVE.** <li>  SQL
b490: 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c  ITE_SHM_UNLOCK |
b4a0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
b4b0: 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  ED.** <li>  SQLI
b4c0: 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20  TE_SHM_UNLOCK | 
b4d0: 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55  SQLITE_SHM_EXCLU
b4e0: 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  SIVE.** </ul>.**
b4f0: 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69  .** When unlocki
b500: 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41  ng, the same SHA
b510: 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45  RED or EXCLUSIVE
b520: 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75   flag must be su
b530: 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73  pplied as.** was
b540: 20 67 69 76 65 6e 20 6e 6f 20 74 68 65 20 63 6f   given no the co
b550: 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b  rresponding lock
b560: 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  .  .**.** The xS
b570: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61  hmLock method ca
b580: 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74  n transition bet
b590: 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e  ween unlocked an
b5a0: 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62  d SHARED or.** b
b5b0: 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20  etween unlocked 
b5c0: 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20  and EXCLUSIVE.  
b5d0: 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69  It cannot transi
b5e0: 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41  tion between SHA
b5f0: 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55  RED.** and EXCLU
b600: 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  SIVE..*/.#define
b610: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
b620: 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65 66 69  CK       1.#defi
b630: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  ne SQLITE_SHM_LO
b640: 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23 64 65  CK         2.#de
b650: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
b660: 53 48 41 52 45 44 20 20 20 20 20 20 20 34 0a 23  SHARED       4.#
b670: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
b680: 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 38  M_EXCLUSIVE    8
b690: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
b6a0: 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f  : Maximum xShmLo
b6b0: 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54  ck index.**.** T
b6c0: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
b6d0: 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69  od on [sqlite3_i
b6e0: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75  o_methods] may u
b6f0: 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74  se values.** bet
b700: 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20  ween 0 and this 
b710: 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69  upper bound as i
b720: 74 73 20 22 6f 66 66 73 65 74 22 20 61 72 67 75  ts "offset" argu
b730: 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  ment..** The SQL
b740: 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65  ite core will ne
b750: 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61  ver attempt to a
b760: 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73  cquire or releas
b770: 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73  e a.** lock outs
b780: 69 64 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67  ide of this rang
b790: 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e.*/.#define SQL
b7a0: 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20  ITE_SHM_NLOCK   
b7b0: 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43       8.../*.** C
b7c0: 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c  API3REF: Initial
b7d0: 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c  ize The SQLite L
b7e0: 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68  ibrary.**.** ^Th
b7f0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
b800: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69  lize() routine i
b810: 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a  nitializes the.*
b820: 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  * SQLite library
b830: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
b840: 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69  shutdown() routi
b850: 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65  ne.** deallocate
b860: 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20  s any resources 
b870: 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61  that were alloca
b880: 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69  ted by sqlite3_i
b890: 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20  nitialize()..** 
b8a0: 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
b8b0: 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61  re designed to a
b8c0: 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e  id in process in
b8d0: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64  itialization and
b8e0: 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20  .** shutdown on 
b8f0: 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73  embedded systems
b900: 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61  .  Workstation a
b910: 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e  pplications usin
b920: 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d  g.** SQLite norm
b930: 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64  ally do not need
b940: 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65   to invoke eithe
b950: 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  r of these routi
b960: 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c  nes..**.** A cal
b970: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69  l to sqlite3_ini
b980: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20  tialize() is an 
b990: 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c  "effective" call
b9a0: 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65   if it is.** the
b9b0: 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69   first time sqli
b9c0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
b9d0: 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69   is invoked duri
b9e0: 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20  ng the lifetime 
b9f0: 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73  of.** the proces
ba00: 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 74  s, or if it is t
ba10: 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71  he first time sq
ba20: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
ba30: 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
ba40: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c   following a cal
ba50: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
ba60: 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79  tdown().  ^(Only
ba70: 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61   an effective ca
ba80: 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  ll.** of sqlite3
ba90: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f  _initialize() do
baa0: 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a  es any initializ
bab0: 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65  ation.  All othe
bac0: 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68  r calls.** are h
bad0: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29  armless no-ops.)
bae0: 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ^.**.** A call t
baf0: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
bb00: 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  wn() is an "effe
bb10: 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
bb20: 74 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a  t is the first.*
bb30: 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  * call to sqlite
bb40: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e  3_shutdown() sin
bb50: 63 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69  ce the last sqli
bb60: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
bb70: 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20  .  ^(Only.** an 
bb80: 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74  effective call t
bb90: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
bba0: 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65  wn() does any de
bbb0: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a  initialization..
bbc0: 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c  ** All other val
bbd0: 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  id calls to sqli
bbe0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61  te3_shutdown() a
bbf0: 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  re harmless no-o
bc00: 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ps.)^.**.** The 
bc10: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
bc20: 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ze() interface i
bc30: 73 20 74 68 72 65 61 64 73 61 66 65 2c 20 62 75  s threadsafe, bu
bc40: 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  t sqlite3_shutdo
bc50: 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20  wn().** is not. 
bc60: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75   The sqlite3_shu
bc70: 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63  tdown() interfac
bc80: 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63  e must only be c
bc90: 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20  alled from a.** 
bca0: 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20  single thread.  
bcb0: 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61  All open [databa
bcc0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
bcd0: 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61  must be closed a
bce0: 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20  nd all.** other 
bcf0: 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73  SQLite resources
bd00: 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63   must be dealloc
bd10: 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e  ated prior to in
bd20: 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  voking.** sqlite
bd30: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a  3_shutdown()..**
bd40: 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20  .** Among other 
bd50: 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33  things, ^sqlite3
bd60: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69  _initialize() wi
bd70: 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c  ll invoke.** sql
bd80: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
bd90: 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c   Similarly, ^sql
bda0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
bdb0: 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73  ** will invoke s
bdc0: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e  qlite3_os_end().
bdd0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
bde0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
bdf0: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
be00: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
be10: 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20  success..** ^If 
be20: 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c  for some reason,
be30: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
be40: 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20  ize() is unable 
be50: 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a  to initialize.**
be60: 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 65   the library (pe
be70: 72 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 62  rhaps it is unab
be80: 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61  le to allocate a
be90: 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 65   needed resource
bea0: 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75   such.** as a mu
beb0: 74 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 20  tex) it returns 
bec0: 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
bed0: 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
bee0: 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  TE_OK]..**.** ^T
bef0: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
bf00: 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
bf10: 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e  is called intern
bf20: 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68  ally by many oth
bf30: 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  er.** SQLite int
bf40: 65 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 20  erfaces so that 
bf50: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75  an application u
bf60: 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20  sually does not 
bf70: 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b  need to.** invok
bf80: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
bf90: 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e  lize() directly.
bfa0: 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b    For example, [
bfb0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a  sqlite3_open()].
bfc0: 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33  ** calls sqlite3
bfd0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f  _initialize() so
bfe0: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
bff0: 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f  ary will be auto
c000: 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69  matically.** ini
c010: 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73  tialized when [s
c020: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69  qlite3_open()] i
c030: 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68  s called if it h
c040: 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61  as not be initia
c050: 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79  lized.** already
c060: 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20  .  ^However, if 
c070: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
c080: 65 64 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ed with the [SQL
c090: 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49  ITE_OMIT_AUTOINI
c0a0: 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  T].** compile-ti
c0b0: 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20  me option, then 
c0c0: 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61  the automatic ca
c0d0: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  lls to sqlite3_i
c0e0: 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61  nitialize().** a
c0f0: 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74  re omitted and t
c100: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
c110: 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  ust call sqlite3
c120: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69  _initialize() di
c130: 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20  rectly.** prior 
c140: 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68  to using any oth
c150: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
c160: 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75  ace.  For maximu
c170: 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a  m portability,.*
c180: 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  * it is recommen
c190: 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61  ded that applica
c1a0: 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76  tions always inv
c1b0: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  oke sqlite3_init
c1c0: 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65  ialize().** dire
c1d0: 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73  ctly prior to us
c1e0: 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
c1f0: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
c200: 20 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   Future releases
c210: 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61  .** of SQLite ma
c220: 79 20 72 65 71 75 69 72 65 20 74 68 69 73 2e 20  y require this. 
c230: 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
c240: 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 78   the behavior ex
c250: 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20  hibited.** when 
c260: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
c270: 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
c280: 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d  OMIT_AUTOINIT] m
c290: 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a  ight become the.
c2a0: 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61 76  ** default behav
c2b0: 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75  ior in some futu
c2c0: 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  re release of SQ
c2d0: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
c2e0: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
c2f0: 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f  ) routine does o
c300: 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20  perating-system 
c310: 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74  specific.** init
c320: 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68  ialization of th
c330: 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
c340: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  .  The sqlite3_o
c350: 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69  s_end().** routi
c360: 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66  ne undoes the ef
c370: 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f  fect of sqlite3_
c380: 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69  os_init().  Typi
c390: 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72  cal tasks.** per
c3a0: 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65 20  formed by these 
c3b0: 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65  routines include
c3c0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64   allocation or d
c3d0: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
c3e0: 66 20 73 74 61 74 69 63 20 72 65 73 6f 75 72 63  f static resourc
c3f0: 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  es, initializati
c400: 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72  on of global var
c410: 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69  iables,.** setti
c420: 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c 74 20  ng up a default 
c430: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f  [sqlite3_vfs] mo
c440: 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67  dule, or setting
c450: 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74   up.** a default
c460: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75   configuration u
c470: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f  sing [sqlite3_co
c480: 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  nfig()]..**.** T
c490: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
c4a0: 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f  hould never invo
c4b0: 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69 74 65  ke either sqlite
c4c0: 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f  3_os_init().** o
c4d0: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  r sqlite3_os_end
c4e0: 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68  () directly.  Th
c4f0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
c500: 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65  ould only invoke
c510: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  .** sqlite3_init
c520: 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c  ialize() and sql
c530: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
c540: 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73    The sqlite3_os
c550: 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72  _init().** inter
c560: 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61  face is called a
c570: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20  utomatically by 
c580: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
c590: 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  ze() and.** sqli
c5a0: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20  te3_os_end() is 
c5b0: 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65  called by sqlite
c5c0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41  3_shutdown().  A
c5d0: 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d  ppropriate.** im
c5e0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f  plementations fo
c5f0: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  r sqlite3_os_ini
c600: 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
c610: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20  os_end().** are 
c620: 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
c630: 65 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d  e when it is com
c640: 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20  piled for Unix, 
c650: 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32  Windows, or OS/2
c660: 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f  ..** When [custo
c670: 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74  m builds | built
c680: 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66   for other platf
c690: 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20  orms].** (using 
c6a0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f  the [SQLITE_OS_O
c6b0: 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d  THER=1] compile-
c6c0: 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20  time.** option) 
c6d0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
c6e0: 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 75  must supply a su
c6f0: 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  itable implement
c700: 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c  ation for.** sql
c710: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
c720: 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
c730: 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61  d().  An applica
c740: 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a  tion-supplied.**
c750: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
c760: 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
c770: 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  it() or sqlite3_
c780: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74  os_end().** must
c790: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
c7a0: 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61  OK] on success a
c7b0: 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65  nd some other [e
c7c0: 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a  rror code] upon.
c7d0: 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69  ** failure..*/.i
c7e0: 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  nt sqlite3_initi
c7f0: 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74  alize(void);.int
c800: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
c810: 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  n(void);.int sql
c820: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69  ite3_os_init(voi
c830: 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
c840: 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f  os_end(void);../
c850: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
c860: 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53  onfiguring The S
c870: 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a  QLite Library.**
c880: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
c890: 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
c8a0: 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61  ce is used to ma
c8b0: 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67  ke global config
c8c0: 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67  uration.** chang
c8d0: 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20  es to SQLite in 
c8e0: 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51  order to tune SQ
c8f0: 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63  Lite to the spec
c900: 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a  ific needs of.**
c910: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
c920: 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63  .  The default c
c930: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20  onfiguration is 
c940: 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
c950: 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74  most.** applicat
c960: 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73  ions and so this
c970: 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61   routine is usua
c980: 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72  lly not necessar
c990: 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f  y.  It is.** pro
c9a0: 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74  vided to support
c9b0: 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f   rare applicatio
c9c0: 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20  ns with unusual 
c9d0: 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  needs..**.** The
c9e0: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
c9f0: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  ) interface is n
ca00: 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 20  ot threadsafe.  
ca10: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a  The application.
ca20: 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74  ** must insure t
ca30: 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c  hat no other SQL
ca40: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61  ite interfaces a
ca50: 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74  re invoked by ot
ca60: 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77  her.** threads w
ca70: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e  hile sqlite3_con
ca80: 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  fig() is running
ca90: 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20  .  Furthermore, 
caa0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
cab0: 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  .** may only be 
cac0: 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f  invoked prior to
cad0: 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c   library initial
cae0: 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a  ization using.**
caf0: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
cb00: 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72  lize()] or after
cb10: 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71   shutdown by [sq
cb20: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
cb30: 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  ]..** ^If sqlite
cb40: 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61  3_config() is ca
cb50: 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69  lled after [sqli
cb60: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
cb70: 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20  ] and before.** 
cb80: 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
cb90: 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c  n()] then it wil
cba0: 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  l return SQLITE_
cbb0: 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c  MISUSE..** Note,
cbc0: 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e   however, that ^
cbd0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
cbe0: 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61   can be called a
cbf0: 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a  s part of the.**
cc00: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
cc10: 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  of an applicatio
cc20: 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74  n-defined [sqlit
cc30: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a  e3_os_init()]..*
cc40: 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
cc50: 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
cc60: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61  e3_config() is a
cc70: 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f  n integer.** [co
cc80: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
cc90: 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69  on] that determi
cca0: 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70  nes.** what prop
ccb0: 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69  erty of SQLite i
ccc0: 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72  s to be configur
ccd0: 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20  ed.  Subsequent 
cce0: 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72  arguments.** var
ccf0: 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  y depending on t
cd00: 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f  he [configuratio
cd10: 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20  n option].** in 
cd20: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
cd30: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20  nt..**.** ^When 
cd40: 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  a configuration 
cd50: 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73  option is set, s
cd60: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
cd70: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
cd80: 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  OK]..** ^If the 
cd90: 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77  option is unknow
cda0: 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75  n or SQLite is u
cdb0: 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  nable to set the
cdc0: 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20   option.** then 
cdd0: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  this routine ret
cde0: 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20  urns a non-zero 
cdf0: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f  [error code]..*/
ce00: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  .int sqlite3_con
ce10: 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a  fig(int, ...);..
ce20: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
ce30: 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 61  Configure databa
ce40: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a  se connections.*
ce50: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
ce60: 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  _db_config() int
ce70: 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74  erface is used t
ce80: 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61  o make configura
ce90: 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20  tion.** changes 
cea0: 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  to a [database c
ceb0: 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65  onnection].  The
cec0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 69   interface is si
ced0: 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c  milar to.** [sql
cee0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65  ite3_config()] e
cef0: 78 63 65 70 74 20 74 68 61 74 20 74 68 65 20 63  xcept that the c
cf00: 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20  hanges apply to 
cf10: 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74  a single.** [dat
cf20: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
cf30: 5d 20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20  ] (specified in 
cf40: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
cf50: 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  nt)..**.** The s
cf60: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
cf70: 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  o sqlite3_db_con
cf80: 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73  fig(D,V,...)  is
cf90: 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
cfa0: 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
cfb0: 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69  DE | configurati
cfc0: 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e  on verb] - an in
cfd0: 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74  teger code .** t
cfe0: 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 68  hat indicates wh
cff0: 61 74 20 61 73 70 65 63 74 20 6f 66 20 74 68 65  at aspect of the
d000: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
d010: 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20  ction] is being 
d020: 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53  configured..** S
d030: 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65  ubsequent argume
d040: 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e 64 69  nts vary dependi
d050: 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67  ng on the config
d060: 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a  uration verb..**
d070: 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71  .** ^Calls to sq
d080: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
d090: 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  ) return SQLITE_
d0a0: 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  OK if and only i
d0b0: 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73  f.** the call is
d0c0: 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63   considered succ
d0d0: 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73  essful..*/.int s
d0e0: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
d0f0: 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f  (sqlite3*, int o
d100: 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20  p, ...);../*.** 
d110: 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
d120: 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74   Allocation Rout
d130: 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  ines.**.** An in
d140: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
d150: 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68  bject defines th
d160: 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77  e interface betw
d170: 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e  een SQLite.** an
d180: 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f  d low-level memo
d190: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
d1a0: 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  utines..**.** Th
d1b0: 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  is object is use
d1c0: 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c  d in only one pl
d1d0: 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74  ace in the SQLit
d1e0: 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20  e interface..** 
d1f0: 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  A pointer to an 
d200: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
d210: 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20 61   object is the a
d220: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73  rgument to.** [s
d230: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
d240: 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67   when the config
d250: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69  uration option i
d260: 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  s.** [SQLITE_CON
d270: 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b  FIG_MALLOC] or [
d280: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
d290: 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42  TMALLOC].  .** B
d2a0: 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e  y creating an in
d2b0: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
d2c0: 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73  bject.** and pas
d2d0: 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69  sing it to [sqli
d2e0: 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c  te3_config]([SQL
d2f0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
d300: 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f  C]).** during co
d310: 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20  nfiguration, an 
d320: 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20  application can 
d330: 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72  specify an alter
d340: 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79  native.** memory
d350: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73   allocation subs
d360: 79 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65  ystem for SQLite
d370: 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20   to use for all 
d380: 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69  of its.** dynami
d390: 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a  c memory needs..
d3a0: 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
d3b0: 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74  SQLite comes wit
d3c0: 68 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74  h several [built
d3d0: 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  -in memory alloc
d3e0: 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61  ators].** that a
d3f0: 72 65 20 70 65 72 66 65 63 74 6c 79 20 61 64 65  re perfectly ade
d400: 71 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76  quate for the ov
d410: 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72  erwhelming major
d420: 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69  ity of applicati
d430: 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20  ons.** and that 
d440: 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f  this object is o
d450: 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20  nly useful to a 
d460: 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66  tiny minority of
d470: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
d480: 20 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65   with specialize
d490: 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  d memory allocat
d4a0: 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73  ion requirements
d4b0: 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  .  This object i
d4c0: 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64  s.** also used d
d4d0: 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66  uring testing of
d4e0: 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72   SQLite in order
d4f0: 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61   to specify an a
d500: 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65  lternative.** me
d510: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74  mory allocator t
d520: 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65  hat simulates me
d530: 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f  mory out-of-memo
d540: 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e  ry conditions in
d550: 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72  .** order to ver
d560: 69 66 79 20 74 68 61 74 20 53 51 4c 69 74 65 20  ify that SQLite 
d570: 72 65 63 6f 76 65 72 73 20 67 72 61 63 65 66 75  recovers gracefu
d580: 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a  lly from such.**
d590: 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a   conditions..**.
d5a0: 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 20 61  ** The xMalloc a
d5b0: 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73  nd xFree methods
d5c0: 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20   must work like 
d5d0: 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 20  the.** malloc() 
d5e0: 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63 74  and free() funct
d5f0: 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74  ions from the st
d600: 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
d610: 2e 0a 2a 2a 20 54 68 65 20 78 52 65 61 6c 6c 6f  ..** The xReallo
d620: 63 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 77 6f  c method must wo
d630: 72 6b 20 6c 69 6b 65 20 72 65 61 6c 6c 6f 63 28  rk like realloc(
d640: 29 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  ) from the stand
d650: 61 72 64 20 43 20 6c 69 62 72 61 72 79 0a 2a 2a  ard C library.**
d660: 20 77 69 74 68 20 74 68 65 20 65 78 63 65 70 74   with the except
d670: 69 6f 6e 20 74 68 61 74 20 69 66 20 74 68 65 20  ion that if the 
d680: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
d690: 74 6f 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 7a  to xRealloc is z
d6a0: 65 72 6f 2c 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63  ero,.** xRealloc
d6b0: 20 6d 75 73 74 20 62 65 20 61 20 6e 6f 2d 6f 70   must be a no-op
d6c0: 20 2d 20 69 74 20 6d 75 73 74 20 6e 6f 74 20 70   - it must not p
d6d0: 65 72 66 6f 72 6d 20 61 6e 79 20 61 6c 6c 6f 63  erform any alloc
d6e0: 61 74 69 6f 6e 20 6f 72 0a 2a 2a 20 64 65 61 6c  ation or.** deal
d6f0: 6c 6f 63 61 74 69 6f 6e 2e 20 20 5e 53 51 4c 69  location.  ^SQLi
d700: 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  te guarantees th
d710: 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  at the second ar
d720: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65  gument to.** xRe
d730: 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20  alloc is always 
d740: 61 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  a value returned
d750: 20 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c   by a prior call
d760: 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a   to xRoundup..**
d770: 20 41 6e 64 20 73 6f 20 69 6e 20 63 61 73 65 73   And so in cases
d780: 20 77 68 65 72 65 20 78 52 6f 75 6e 64 75 70 20   where xRoundup 
d790: 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61  always returns a
d7a0: 20 70 6f 73 69 74 69 76 65 20 6e 75 6d 62 65 72   positive number
d7b0: 2c 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 63 61  ,.** xRealloc ca
d7c0: 6e 20 70 65 72 66 6f 72 6d 20 65 78 61 63 74 6c  n perform exactl
d7d0: 79 20 61 73 20 74 68 65 20 73 74 61 6e 64 61 72  y as the standar
d7e0: 64 20 6c 69 62 72 61 72 79 20 72 65 61 6c 6c 6f  d library reallo
d7f0: 63 28 29 20 61 6e 64 0a 2a 2a 20 73 74 69 6c 6c  c() and.** still
d800: 20 62 65 20 69 6e 20 63 6f 6d 70 6c 69 61 6e 63   be in complianc
d810: 65 20 77 69 74 68 20 74 68 69 73 20 73 70 65 63  e with this spec
d820: 69 66 69 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  ification..**.**
d830: 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65   xSize should re
d840: 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74  turn the allocat
d850: 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d  ed size of a mem
d860: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
d870: 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74  * previously obt
d880: 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c  ained from xMall
d890: 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20  oc or xRealloc. 
d8a0: 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   The allocated s
d8b0: 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  ize.** is always
d8c0: 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 69 67   at least as big
d8d0: 20 61 73 20 74 68 65 20 72 65 71 75 65 73 74 65   as the requeste
d8e0: 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62  d size but may b
d8f0: 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20  e larger..**.** 
d900: 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74  The xRoundup met
d910: 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61 74  hod returns what
d920: 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c   would be the al
d930: 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a  located size of.
d940: 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ** a memory allo
d950: 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70  cation given a p
d960: 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 65 73  articular reques
d970: 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20  ted size.  Most 
d980: 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
d990: 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65  tors round up me
d9a0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
d9b0: 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65   at least to the
d9c0: 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a   next multiple.*
d9d0: 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c  * of 8.  Some al
d9e0: 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75  locators round u
d9f0: 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75  p to a larger mu
da00: 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70  ltiple or to a p
da10: 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76  ower of 2..** Ev
da20: 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ery memory alloc
da30: 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f  ation request co
da40: 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20  ming in through 
da50: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
da60: 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  )].** or [sqlite
da70: 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72  3_realloc()] fir
da80: 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75  st calls xRoundu
da90: 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20  p.  If xRoundup 
daa0: 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74  returns 0, .** t
dab0: 68 61 74 20 63 61 75 73 65 73 20 74 68 65 20 63  hat causes the c
dac0: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d  orresponding mem
dad0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
dae0: 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68  o fail..**.** Th
daf0: 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69  e xInit method i
db00: 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d  nitializes the m
db10: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e  emory allocator.
db20: 20 20 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a    (For example,.
db30: 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f  ** it might allo
db40: 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 65  cate any require
db50: 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74   mutexes or init
db60: 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20  ialize internal 
db70: 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72  data.** structur
db80: 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f  es.  The xShutdo
db90: 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76  wn method is inv
dba0: 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79  oked (indirectly
dbb0: 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ) by.** [sqlite3
dbc0: 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64  _shutdown()] and
dbd0: 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61   should dealloca
dbe0: 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73  te any resources
dbf0: 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20   acquired.** by 
dc00: 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70  xInit.  The pApp
dc10: 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20  Data pointer is 
dc20: 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79  used as the only
dc30: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
dc40: 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74   xInit and xShut
dc50: 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  down..**.** SQLi
dc60: 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51  te holds the [SQ
dc70: 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
dc80: 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20  C_MASTER] mutex 
dc90: 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a  when it invokes.
dca0: 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74  ** the xInit met
dcb0: 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69  hod, so the xIni
dcc0: 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f  t method need no
dcd0: 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e  t be threadsafe.
dce0: 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f    The.** xShutdo
dcf0: 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c  wn method is onl
dd00: 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73  y called from [s
dd10: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
dd20: 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a  )] so it does.**
dd30: 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
dd40: 74 68 72 65 61 64 73 61 66 65 20 65 69 74 68 65  threadsafe eithe
dd50: 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65  r.  For all othe
dd60: 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74  r methods, SQLit
dd70: 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b  e.** holds the [
dd80: 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
dd90: 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61  TIC_MEM] mutex a
dda0: 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a  s long as the.**
ddb0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
ddc0: 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69  MEMSTATUS] confi
ddd0: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
dde0: 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68  is turned on (wh
ddf0: 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20  ich.** it is by 
de00: 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20  default) and so 
de10: 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20  the methods are 
de20: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65  automatically se
de30: 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77  rialized..** How
de40: 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45  ever, if [SQLITE
de50: 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
de60: 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20  S] is disabled, 
de70: 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a  then the other.*
de80: 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62  * methods must b
de90: 65 20 74 68 72 65 61 64 73 61 66 65 20 6f 72 20  e threadsafe or 
dea0: 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20  else make their 
deb0: 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73  own arrangements
dec0: 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a   for.** serializ
ded0: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  ation..**.** SQL
dee0: 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69  ite will never i
def0: 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f  nvoke xInit() mo
df00: 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74  re than once wit
df10: 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e  hout an interven
df20: 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78  ing.** call to x
df30: 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74  Shutdown()..*/.t
df40: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
df50: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
df60: 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  s sqlite3_mem_me
df70: 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
df80: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
df90: 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d  s {.  void *(*xM
dfa0: 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20  alloc)(int);    
dfb0: 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61       /* Memory a
dfc0: 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69  llocation functi
dfd0: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78  on */.  void (*x
dfe0: 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20  Free)(void*);   
dff0: 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61         /* Free a
e000: 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
e010: 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78  n */.  void *(*x
e020: 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69  Realloc)(void*,i
e030: 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20  nt);  /* Resize 
e040: 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  an allocation */
e050: 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28  .  int (*xSize)(
e060: 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
e070: 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20    /* Return the 
e080: 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63  size of an alloc
e090: 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28  ation */.  int (
e0a0: 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b  *xRoundup)(int);
e0b0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75            /* Rou
e0c0: 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69  nd up request si
e0d0: 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e  ze to allocation
e0e0: 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28   size */.  int (
e0f0: 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20  *xInit)(void*); 
e100: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69            /* Ini
e110: 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f  tialize the memo
e120: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a  ry allocator */.
e130: 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f    void (*xShutdo
e140: 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  wn)(void*);     
e150: 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65   /* Deinitialize
e160: 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
e170: 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20  cator */.  void 
e180: 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20  *pAppData;      
e190: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67            /* Arg
e1a0: 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29  ument to xInit()
e1b0: 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29   and xShutdown()
e1c0: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
e1d0: 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
e1e0: 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a  ation Options.**
e1f0: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66   KEYWORDS: {conf
e200: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
e210: 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
e220: 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20  nstants are the 
e230: 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65  available intege
e240: 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  r configuration 
e250: 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20  options that.** 
e260: 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73  can be passed as
e270: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
e280: 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ent to the [sqli
e290: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
e2a0: 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e  terface..**.** N
e2b0: 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
e2c0: 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
e2d0: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
e2e0: 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
e2f0: 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  te..** Existing 
e300: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
e310: 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64  tions might be d
e320: 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70  iscontinued.  Ap
e330: 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
e340: 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72  ould check the r
e350: 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20  eturn code from 
e360: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
e370: 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  )] to make sure 
e380: 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  that.** the call
e390: 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73   worked.  The [s
e3a0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
e3b0: 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
e3c0: 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d  return a.** non-
e3d0: 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
e3e0: 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e  ] if a discontin
e3f0: 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74  ued or unsupport
e400: 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ed configuration
e410: 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e   option.** is in
e420: 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  voked..**.** <dl
e430: 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  >.** [[SQLITE_CO
e440: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
e450: 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
e460: 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
e470: 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  AD</dt>.** <dd>T
e480: 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
e490: 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
e4a0: 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74  tion.  ^This opt
e4b0: 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
e4c0: 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
e4d0: 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61   to Single-threa
e4e0: 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  d.  In other wor
e4f0: 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a  ds, it disables.
e500: 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20  ** all mutexing 
e510: 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 20  and puts SQLite 
e520: 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72  into a mode wher
e530: 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65  e it can only be
e540: 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69   used.** by a si
e550: 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e  ngle thread.   ^
e560: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
e570: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
e580: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
e590: 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
e5a0: 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
e5b0: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
e5c0: 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
e5d0: 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68  t possible to ch
e5e0: 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61 64  ange the [thread
e5f0: 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69  ing mode] from i
e600: 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61  ts default.** va
e610: 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68  lue of Single-th
e620: 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c  read and so [sql
e630: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
e640: 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b  ill return .** [
e650: 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
e660: 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65   called with the
e670: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
e680: 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63  INGLETHREAD.** c
e690: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
e6a0: 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
e6b0: 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
e6c0: 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64  MULTITHREAD]] <d
e6d0: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
e6e0: 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e  MULTITHREAD</dt>
e6f0: 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
e700: 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
e710: 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
e720: 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
e730: 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
e740: 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c  ing mode] to Mul
e750: 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f  ti-thread.  In o
e760: 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64  ther words, it d
e770: 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78  isables.** mutex
e780: 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  ing on [database
e790: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
e7a0: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
e7b0: 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
e7c0: 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
e7d0: 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  n is responsible
e7e0: 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67   for serializing
e7f0: 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64   access to.** [d
e800: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
e810: 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ons] and [prepar
e820: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20  ed statements]. 
e830: 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78   But other mutex
e840: 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65  es.** are enable
e850: 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65  d so that SQLite
e860: 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f   will be safe to
e870: 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d   use in a multi-
e880: 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69  threaded.** envi
e890: 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20  ronment as long 
e8a0: 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64  as no two thread
e8b0: 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65  s attempt to use
e8c0: 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61   the same.** [da
e8d0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
e8e0: 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  n] at the same t
e8f0: 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65  ime.  ^If SQLite
e900: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
e910: 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
e920: 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
e930: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
e940: 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
e950: 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
e960: 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
e970: 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c  e to set the Mul
e980: 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61  ti-thread [threa
e990: 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a  ding mode] and.*
e9a0: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
e9b0: 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
e9c0: 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
e9d0: 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
e9e0: 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e  he.** SQLITE_CON
e9f0: 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20  FIG_MULTITHREAD 
ea00: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
ea10: 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
ea20: 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
ea30: 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64  _SERIALIZED]] <d
ea40: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
ea50: 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a  SERIALIZED</dt>.
ea60: 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
ea70: 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
ea80: 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
ea90: 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
eaa0: 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
eab0: 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69  ng mode] to Seri
eac0: 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72  alized. In other
ead0: 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74   words, this opt
eae0: 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61  ion enables.** a
eaf0: 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75  ll mutexes inclu
eb00: 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 69  ding the recursi
eb10: 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e  ve.** mutexes on
eb20: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
eb30: 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70  ction] and [prep
eb40: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
eb50: 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74  objects..** In t
eb60: 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20  his mode (which 
eb70: 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 77  is the default w
eb80: 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f  hen SQLite is co
eb90: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b  mpiled with.** [
eba0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
ebb0: 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65  E=1]) the SQLite
ebc0: 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74   library will it
ebd0: 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61  self serialize a
ebe0: 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74  ccess.** to [dat
ebf0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
ec00: 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  s] and [prepared
ec10: 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20   statements] so 
ec20: 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c  that the.** appl
ec30: 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20  ication is free 
ec40: 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 20  to use the same 
ec50: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
ec60: 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20  tion] or the.** 
ec70: 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
ec80: 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66  tatement] in dif
ec90: 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20 61  ferent threads a
eca0: 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e  t the same time.
ecb0: 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .** ^If SQLite i
ecc0: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
ecd0: 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
ece0: 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
ecf0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
ed00: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
ed10: 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
ed20: 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
ed30: 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69 61  to set the Seria
ed40: 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
ed50: 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73   mode] and.** [s
ed60: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
ed70: 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
ed80: 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
ed90: 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  alled with the.*
eda0: 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
edb0: 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69  SERIALIZED confi
edc0: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
edd0: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
ede0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
edf0: 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OC]] <dt>SQLITE_
ee00: 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64  CONFIG_MALLOC</d
ee10: 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
ee20: 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
ee30: 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
ee40: 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
ee50: 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73  ter to an.** ins
ee60: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
ee70: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
ee80: 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
ee90: 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63  he argument spec
eea0: 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61  ifies.** alterna
eeb0: 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d  tive low-level m
eec0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
eed0: 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
eee0: 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66  used in place of
eef0: 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  .** the memory a
ef00: 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
ef10: 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  es built into SQ
ef20: 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20  Lite.)^ ^SQLite 
ef30: 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e  makes.** its own
ef40: 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
ef50: 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
ef60: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
ef70: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
ef80: 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68  ure.** before th
ef90: 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
efa0: 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e  g()] call return
efb0: 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  s.</dd>.**.** [[
efc0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
efd0: 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51  TMALLOC]] <dt>SQ
efe0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
eff0: 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ALLOC</dt>.** <d
f000: 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
f010: 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
f020: 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
f030: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
f040: 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
f050: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   the [sqlite3_me
f060: 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  m_methods] struc
f070: 74 75 72 65 2e 20 20 54 68 65 20 5b 73 71 6c 69  ture.  The [sqli
f080: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
f090: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73  .** structure is
f0a0: 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
f0b0: 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
f0c0: 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ed memory alloca
f0d0: 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e  tion routines.)^
f0e0: 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  .** This option 
f0f0: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
f100: 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61  verload the defa
f110: 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ult memory alloc
f120: 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65  ation.** routine
f130: 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72  s with a wrapper
f140: 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e   that simulation
f150: 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
f160: 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a  ion failure or.*
f170: 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20  * tracks memory 
f180: 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70  usage, for examp
f190: 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  le. </dd>.**.** 
f1a0: 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
f1b0: 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e  MEMSTATUS]] <dt>
f1c0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
f1d0: 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20  MSTATUS</dt>.** 
f1e0: 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
f1f0: 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61  n takes single a
f200: 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20  rgument of type 
f210: 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64  int, interpreted
f220: 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61   as a .** boolea
f230: 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73  n, which enables
f240: 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
f250: 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d   collection of m
f260: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
f270: 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e   .** statistics.
f280: 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61   ^(When memory a
f290: 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
f2a0: 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65  tics are disable
f2b0: 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f  d, the .** follo
f2c0: 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65  wing SQLite inte
f2d0: 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f  rfaces become no
f2e0: 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a  n-operational:.*
f2f0: 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  *   <ul>.**   <l
f300: 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  i> [sqlite3_memo
f310: 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20  ry_used()].**   
f320: 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65  <li> [sqlite3_me
f330: 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
f340: 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
f350: 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
f360: 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c  imit64()].**   <
f370: 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61  li> [sqlite3_sta
f380: 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c  tus()].**   </ul
f390: 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61  >)^.** ^Memory a
f3a0: 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
f3b0: 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64  tics are enabled
f3c0: 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65   by default unle
f3d0: 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20  ss SQLite is.** 
f3e0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53  compiled with [S
f3f0: 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45  QLITE_DEFAULT_ME
f400: 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68  MSTATUS]=0 in wh
f410: 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a  ich case memory.
f420: 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ** allocation st
f430: 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73  atistics are dis
f440: 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
f450: 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
f460: 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
f470: 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53  _SCRATCH]] <dt>S
f480: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
f490: 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATCH</dt>.** <dd
f4a0: 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73  > ^This option s
f4b0: 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69  pecifies a stati
f4c0: 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  c memory buffer 
f4d0: 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20  that SQLite can 
f4e0: 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74  use for.** scrat
f4f0: 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72  ch memory.  Ther
f500: 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
f510: 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 65  ments:  A pointe
f520: 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61  r an 8-byte.** a
f530: 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75  ligned memory bu
f540: 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20  ffer from which 
f550: 74 68 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f  the scratch allo
f560: 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a  cations will be.
f570: 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69  ** drawn, the si
f580: 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74  ze of each scrat
f590: 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73  ch allocation (s
f5a0: 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d  z),.** and the m
f5b0: 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
f5c0: 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
f5d0: 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68 65 20 73  ions (N).  The s
f5e0: 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75  z.** argument mu
f5f0: 73 74 20 62 65 20 61 20 6d 75 6c 74 69 70 6c 65  st be a multiple
f600: 20 6f 66 20 31 36 2e 0a 2a 2a 20 54 68 65 20 66   of 16..** The f
f610: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
f620: 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  st be a pointer 
f630: 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69  to an 8-byte ali
f640: 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f  gned buffer.** o
f650: 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20  f at least sz*N 
f660: 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e  bytes of memory.
f670: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
f680: 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61   use no more tha
f690: 6e 20 74 77 6f 20 73 63 72 61 74 63 68 20 62 75  n two scratch bu
f6a0: 66 66 65 72 73 20 70 65 72 20 74 68 72 65 61 64  ffers per thread
f6b0: 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c  .  So.** N shoul
f6c0: 64 20 62 65 20 73 65 74 20 74 6f 20 74 77 69 63  d be set to twic
f6d0: 65 20 74 68 65 20 65 78 70 65 63 74 65 64 20 6d  e the expected m
f6e0: 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
f6f0: 20 74 68 72 65 61 64 73 2e 0a 2a 2a 20 5e 53 51   threads..** ^SQ
f700: 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  Lite will never 
f710: 72 65 71 75 69 72 65 20 61 20 73 63 72 61 74 63  require a scratc
f720: 68 20 62 75 66 66 65 72 20 74 68 61 74 20 69 73  h buffer that is
f730: 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20   more than 6.** 
f740: 74 69 6d 65 73 20 74 68 65 20 64 61 74 61 62 61  times the databa
f750: 73 65 20 70 61 67 65 20 73 69 7a 65 2e 20 5e 49  se page size. ^I
f760: 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e  f SQLite needs n
f770: 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a  eeds additional.
f780: 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72  ** scratch memor
f790: 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73  y beyond what is
f7a0: 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69   provided by thi
f7b0: 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
f7c0: 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a  option, then .**
f7d0: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
f7e0: 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64  ()] will be used
f7f0: 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d   to obtain the m
f800: 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 2f 64  emory needed.</d
f810: 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
f820: 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
f830: 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  HE]] <dt>SQLITE_
f840: 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
f850: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
f860: 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  his option speci
f870: 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
f880: 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74  mory buffer that
f890: 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20   SQLite can use 
f8a0: 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  for.** the datab
f8b0: 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77  ase page cache w
f8c0: 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20  ith the default 
f8d0: 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
f8e0: 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20  mentation.  .** 
f8f0: 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69  This configurati
f900: 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  on should not be
f910: 20 75 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c   used if an appl
f920: 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70  ication-define p
f930: 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70  age.** cache imp
f940: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c  lementation is l
f950: 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68 65 20  oaded using the 
f960: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
f970: 41 43 48 45 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20  ACHE option..** 
f980: 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20  There are three 
f990: 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
f9a0: 73 20 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e  s option: A poin
f9b0: 74 65 72 20 74 6f 20 38 2d 62 79 74 65 20 61 6c  ter to 8-byte al
f9c0: 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c  igned.** memory,
f9d0: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63   the size of eac
f9e0: 68 20 70 61 67 65 20 62 75 66 66 65 72 20 28 73  h page buffer (s
f9f0: 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62  z), and the numb
fa00: 65 72 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e  er of pages (N).
fa10: 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d  .** The sz argum
fa20: 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68  ent should be th
fa30: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61  e size of the la
fa40: 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70  rgest database p
fa50: 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20  age.** (a power 
fa60: 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35  of two between 5
fa70: 31 32 20 61 6e 64 20 33 32 37 36 38 29 20 70 6c  12 and 32768) pl
fa80: 75 73 20 61 20 6c 69 74 74 6c 65 20 65 78 74 72  us a little extr
fa90: 61 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61  a for each.** pa
faa0: 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65  ge header.  ^The
fab0: 20 70 61 67 65 20 68 65 61 64 65 72 20 73 69 7a   page header siz
fac0: 65 20 69 73 20 32 30 20 74 6f 20 34 30 20 62 79  e is 20 to 40 by
fad0: 74 65 73 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  tes depending on
fae0: 0a 2a 2a 20 74 68 65 20 68 6f 73 74 20 61 72 63  .** the host arc
faf0: 68 69 74 65 63 74 75 72 65 2e 20 20 5e 49 74 20  hitecture.  ^It 
fb00: 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61  is harmless, apa
fb10: 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74  rt from the wast
fb20: 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f  ed memory,.** to
fb30: 20 6d 61 6b 65 20 73 7a 20 61 20 6c 69 74 74 6c   make sz a littl
fb40: 65 20 74 6f 6f 20 6c 61 72 67 65 2e 20 20 54 68  e too large.  Th
fb50: 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d  e first.** argum
fb60: 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74  ent should point
fb70: 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f   to an allocatio
fb80: 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a  n of at least sz
fb90: 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  *N bytes of memo
fba0: 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  ry..** ^SQLite w
fbb0: 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d 6f  ill use the memo
fbc0: 72 79 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  ry provided by t
fbd0: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
fbe0: 74 20 74 6f 20 73 61 74 69 73 66 79 20 69 74 73  t to satisfy its
fbf0: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73  .** memory needs
fc00: 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e   for the first N
fc10: 20 70 61 67 65 73 20 74 68 61 74 20 69 74 20 61   pages that it a
fc20: 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20 5e  dds to cache.  ^
fc30: 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  If additional.**
fc40: 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f   page cache memo
fc50: 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79  ry is needed bey
fc60: 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76  ond what is prov
fc70: 69 64 65 64 20 62 79 20 74 68 69 73 20 6f 70 74  ided by this opt
fc80: 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c  ion, then.** SQL
fc90: 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c  ite goes to [sql
fca0: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66  ite3_malloc()] f
fcb0: 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61  or the additiona
fcc0: 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e  l storage space.
fcd0: 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20  .** The pointer 
fce0: 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
fcf0: 75 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 62 65  ument must.** be
fd00: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38   aligned to an 8
fd10: 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 6f  -byte boundary o
fd20: 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68  r subsequent beh
fd30: 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a  avior of SQLite.
fd40: 2a 2a 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66  ** will be undef
fd50: 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ined.</dd>.**.**
fd60: 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
fd70: 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49  _HEAP]] <dt>SQLI
fd80: 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f  TE_CONFIG_HEAP</
fd90: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
fda0: 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69  s option specifi
fdb0: 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f  es a static memo
fdc0: 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53  ry buffer that S
fdd0: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a  QLite will use.*
fde0: 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  * for all of its
fdf0: 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20   dynamic memory 
fe00: 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
fe10: 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72   beyond those pr
fe20: 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79  ovided.** for by
fe30: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
fe40: 53 43 52 41 54 43 48 5d 20 61 6e 64 20 5b 53 51  SCRATCH] and [SQ
fe50: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
fe60: 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65  CACHE]..** There
fe70: 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d   are three argum
fe80: 65 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74 65 20  ents: An 8-byte 
fe90: 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20  aligned pointer 
fea0: 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a  to the memory,.*
feb0: 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
fec0: 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d  bytes in the mem
fed0: 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20  ory buffer, and 
fee0: 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f  the minimum allo
fef0: 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20  cation size..** 
ff00: 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 70 6f  ^If the first po
ff10: 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72  inter (the memor
ff20: 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55  y pointer) is NU
ff30: 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  LL, then SQLite 
ff40: 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73  reverts.** to us
ff50: 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20  ing its default 
ff60: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
ff70: 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c   (the system mal
ff80: 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61  loc() implementa
ff90: 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e  tion),.** undoin
ffa0: 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f  g any prior invo
ffb0: 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54  cation of [SQLIT
ffc0: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
ffd0: 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65  .  ^If the.** me
ffe0: 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20  mory pointer is 
fff0: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74  not NULL and eit
10000 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  her [SQLITE_ENAB
10010 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a  LE_MEMSYS3] or.*
10020 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
10030 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65 20 64 65  _MEMSYS5] are de
10040 66 69 6e 65 64 2c 20 74 68 65 6e 20 74 68 65 20  fined, then the 
10050 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f  alternative memo
10060 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20  ry.** allocator 
10070 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61  is engaged to ha
10080 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69  ndle all of SQLi
10090 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  tes memory alloc
100a0 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20  ation needs..** 
100b0 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65  The first pointe
100c0 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f  r (the memory po
100d0 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20 61  inter) must be a
100e0 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62  ligned to an 8-b
100f0 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20  yte.** boundary 
10100 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65  or subsequent be
10110 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65  havior of SQLite
10120 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e   will be undefin
10130 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d  ed..** The minim
10140 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  um allocation si
10150 7a 65 20 69 73 20 63 61 70 70 65 64 20 61 74 20  ze is capped at 
10160 32 5e 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65  2^12. Reasonable
10170 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74   values.** for t
10180 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
10190 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 20 32  ation size are 2
101a0 5e 35 20 74 68 72 6f 75 67 68 20 32 5e 38 2e 3c  ^5 through 2^8.<
101b0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
101c0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
101d0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
101e0 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a  NFIG_MUTEX</dt>.
101f0 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
10200 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
10210 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
10220 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
10230 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e   to an.** instan
10240 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
10250 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
10260 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
10270 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69  e argument speci
10280 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74  fies.** alternat
10290 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75  ive low-level mu
102a0 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  tex routines to 
102b0 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65  be used in place
102c0 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 20 72 6f  .** the mutex ro
102d0 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74  utines built int
102e0 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51  o SQLite.)^  ^SQ
102f0 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  Lite makes a cop
10300 79 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6e 74  y of the.** cont
10310 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ent of the [sqli
10320 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
10330 73 5d 20 73 74 72 75 63 74 75 72 65 20 62 65 66  s] structure bef
10340 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a  ore the call to.
10350 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
10360 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e  ig()] returns. ^
10370 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
10380 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
10390 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
103a0 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
103b0 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
103c0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
103d0 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69  then.** the enti
103e0 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73  re mutexing subs
103f0 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64  ystem is omitted
10400 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20   from the build 
10410 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20  and hence calls 
10420 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
10430 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68  onfig()] with th
10440 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
10450 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74  MUTEX configurat
10460 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a  ion option will.
10470 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
10480 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a  E_ERROR].</dd>.*
10490 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
104a0 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20  NFIG_GETMUTEX]] 
104b0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
104c0 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a  G_GETMUTEX</dt>.
104d0 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
104e0 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
104f0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
10500 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
10510 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e   to an.** instan
10520 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
10530 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
10540 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
10550 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75  e.** [sqlite3_mu
10560 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  tex_methods].** 
10570 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c  structure is fil
10580 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72  led with the cur
10590 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d  rently defined m
105a0 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e  utex routines.)^
105b0 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  .** This option 
105c0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
105d0 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61  verload the defa
105e0 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61  ult mutex alloca
105f0 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  tion.** routines
10600 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20   with a wrapper 
10610 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75  used to track mu
10620 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 65  tex usage for pe
10630 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f  rformance.** pro
10640 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e  filing or testin
10650 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20  g, for example. 
10660 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20    ^If SQLite is 
10670 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
10680 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
10690 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
106a0 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
106b0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
106c0 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65  on then.** the e
106d0 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73  ntire mutexing s
106e0 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74  ubsystem is omit
106f0 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69  ted from the bui
10700 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c  ld and hence cal
10710 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
10720 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68  3_config()] with
10730 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
10740 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66  IG_GETMUTEX conf
10750 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
10760 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20   will.** return 
10770 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c  [SQLITE_ERROR].<
10780 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
10790 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
107a0 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  SIDE]] <dt>SQLIT
107b0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
107c0 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  DE</dt>.** <dd> 
107d0 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
107e0 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  kes two argument
107f0 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  s that determine
10800 20 74 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20   the default.** 
10810 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
10820 6e 20 66 6f 72 20 74 68 65 20 6c 6f 6f 6b 61 73  n for the lookas
10830 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ide memory alloc
10840 61 74 6f 72 20 6f 6e 20 65 61 63 68 0a 2a 2a 20  ator on each.** 
10850 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
10860 74 69 6f 6e 5d 2e 20 20 54 68 65 20 66 69 72 73  tion].  The firs
10870 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  t argument is th
10880 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63  e.** size of eac
10890 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  h lookaside buff
108a0 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 20  er slot and the 
108b0 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e 75  second is the nu
108c0 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73  mber of.** slots
108d0 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65 61   allocated to ea
108e0 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ch database conn
108f0 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 54 68 69  ection.)^  ^(Thi
10900 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
10910 65 0a 2a 2a 20 3c 69 3e 64 65 66 61 75 6c 74 3c  e.** <i>default<
10920 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69  /i> lookaside si
10930 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  ze. The [SQLITE_
10940 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
10950 44 45 5d 0a 2a 2a 20 76 65 72 62 20 74 6f 20 5b  DE].** verb to [
10960 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
10970 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65 64  g()] can be used
10980 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c   to change the l
10990 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66  ookaside.** conf
109a0 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64  iguration on ind
109b0 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69  ividual connecti
109c0 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a  ons.)^ </dd>.**.
109d0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
109e0 49 47 5f 50 43 41 43 48 45 5d 5d 20 3c 64 74 3e  IG_PCACHE]] <dt>
109f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
10a00 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ACHE</dt>.** <dd
10a10 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
10a20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
10a30 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
10a40 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a   a pointer to.**
10a50 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61   an [sqlite3_pca
10a60 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  che_methods] obj
10a70 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63  ect.  This objec
10a80 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20  t specifies the 
10a90 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20  interface.** to 
10aa0 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61  a custom page ca
10ab0 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
10ac0 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d  on.)^  ^SQLite m
10ad0 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
10ae0 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64  he.** object and
10af0 20 75 73 65 73 20 69 74 20 66 6f 72 20 70 61 67   uses it for pag
10b00 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61  e cache memory a
10b10 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e  llocations.</dd>
10b20 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
10b30 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
10b40 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
10b50 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 3c 2f  NFIG_GETPCACHE</
10b60 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
10b70 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
10b80 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
10b90 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
10ba0 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73  nter to an.** [s
10bb0 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
10bc0 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20 20  thods] object.  
10bd0 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66  SQLite copies of
10be0 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
10bf0 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
10c00 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74  mentation into t
10c10 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f  hat object.)^ </
10c20 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
10c30 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20  TE_CONFIG_LOG]] 
10c40 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
10c50 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  G_LOG</dt>.** <d
10c60 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  d> ^The SQLITE_C
10c70 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e  ONFIG_LOG option
10c80 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d   takes two argum
10c90 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20  ents: a pointer 
10ca0 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  to a.** function
10cb0 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67   with a call sig
10cc0 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a  nature of void(*
10cd0 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
10ce0 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e  t char*), .** an
10cf0 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76  d a pointer to v
10d00 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e  oid. ^If the fun
10d10 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73  ction pointer is
10d20 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73   not NULL, it is
10d30 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b  .** invoked by [
10d40 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74  sqlite3_log()] t
10d50 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c  o process each l
10d60 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e  ogging event.  ^
10d70 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69  If the.** functi
10d80 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55  on pointer is NU
10d90 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33  LL, the [sqlite3
10da0 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63  _log()] interfac
10db0 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f  e becomes a no-o
10dc0 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20  p..** ^The void 
10dd0 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20  pointer that is 
10de0 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
10df0 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f  ent to SQLITE_CO
10e00 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70  NFIG_LOG is.** p
10e10 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73  assed through as
10e20 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
10e30 65 74 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c  eter to the appl
10e40 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
10e50 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69  logger.** functi
10e60 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61 74  on whenever that
10e70 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76   function is inv
10e80 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f  oked.  ^The seco
10e90 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  nd parameter to.
10ea0 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75  ** the logger fu
10eb0 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79  nction is a copy
10ec0 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 70 61   of the first pa
10ed0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
10ee0 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20  orresponding.** 
10ef0 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
10f00 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65  call and is inte
10f10 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65  nded to be a [re
10f20 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e  sult code] or an
10f30 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
10f40 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68  sult code].  ^Th
10f50 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
10f60 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20  r passed to the 
10f70 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67  logger is.** log
10f80 20 6d 65 73 73 61 67 65 20 61 66 74 65 72 20 66   message after f
10f90 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73  ormatting via [s
10fa0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
10fb0 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  )]..** The SQLit
10fc0 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66  e logging interf
10fd0 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74  ace is not reent
10fe0 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72  rant; the logger
10ff0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70   function.** sup
11000 70 6c 69 65 64 20 62 79 20 74 68 65 20 61 70 70  plied by the app
11010 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
11020 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c  t invoke any SQL
11030 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ite interface..*
11040 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72  * In a multi-thr
11050 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f  eaded applicatio
11060 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  n, the applicati
11070 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65  on-defined logge
11080 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75  r.** function mu
11090 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  st be threadsafe
110a0 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  . </dd>.**.** [[
110b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
110c0 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  I]] <dt>SQLITE_C
110d0 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64  ONFIG_URI.** <dd
110e0 3e 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  > This option ta
110f0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
11100 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e  ument of type in
11110 74 2e 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  t. If non-zero, 
11120 74 68 65 6e 0a 2a 2a 20 55 52 49 20 68 61 6e 64  then.** URI hand
11130 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79  ling is globally
11140 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65   enabled. If the
11150 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65   parameter is ze
11160 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e  ro, then URI han
11170 64 6c 69 6e 67 0a 2a 2a 20 69 73 20 67 6c 6f 62  dling.** is glob
11180 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 20 49  ally disabled. I
11190 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  f URI handling i
111a0 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c  s globally enabl
111b0 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65  ed, all filename
111c0 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 6f 20 5b  s.** passed to [
111d0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
111e0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
111f0 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  2()], [sqlite3_o
11200 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73  pen16()] or.** s
11210 70 65 63 69 66 69 65 64 20 61 73 20 70 61 72 74  pecified as part
11220 20 6f 66 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d   of [ATTACH] com
11230 6d 61 6e 64 73 20 61 72 65 20 69 6e 74 65 72 70  mands are interp
11240 72 65 74 65 64 20 61 73 20 55 52 49 73 2c 20 72  reted as URIs, r
11250 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20  egardless.** of 
11260 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
11270 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
11280 55 52 49 5d 20 66 6c 61 67 20 69 73 20 73 65 74  URI] flag is set
11290 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   when the databa
112a0 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
112b0 20 69 73 20 6f 70 65 6e 65 64 2e 20 49 66 20 69   is opened. If i
112c0 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69  t is globally di
112d0 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65  sabled, filename
112e0 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e  s are.** only in
112f0 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49  terpreted as URI
11300 73 20 69 66 20 74 68 65 20 53 51 4c 49 54 45 5f  s if the SQLITE_
11310 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67 20 69 73  OPEN_URI flag is
11320 20 73 65 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a   set when the.**
11330 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
11340 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20  tion is opened. 
11350 42 79 20 64 65 66 61 75 6c 74 2c 20 55 52 49 20  By default, URI 
11360 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
11370 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64  ally.** disabled
11380 2e 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61  . The default va
11390 6c 75 65 20 6d 61 79 20 62 65 20 63 68 61 6e 67  lue may be chang
113a0 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20  ed by compiling 
113b0 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
113c0 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d  ITE_USE_URI] sym
113d0 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  bol defined..** 
113e0 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
113f0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
11400 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20  INGLETHREAD  1  
11410 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
11420 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
11430 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20  MULTITHREAD   2 
11440 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
11450 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
11460 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33  _SERIALIZED    3
11470 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
11480 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
11490 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20  G_MALLOC        
114a0 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65  4  /* sqlite3_me
114b0 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  m_methods* */.#d
114c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
114d0 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20  FIG_GETMALLOC   
114e0 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f    5  /* sqlite3_
114f0 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  mem_methods* */.
11500 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
11510 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20  ONFIG_SCRATCH   
11520 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c      6  /* void*,
11530 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a   int sz, int N *
11540 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
11550 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
11560 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64  E     7  /* void
11570 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e  *, int sz, int N
11580 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
11590 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20  TE_CONFIG_HEAP  
115a0 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f          8  /* vo
115b0 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  id*, int nByte, 
115c0 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69  int min */.#defi
115d0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
115e0 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39  _MEMSTATUS     9
115f0 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a    /* boolean */.
11600 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
11610 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20  ONFIG_MUTEX     
11620 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65     10  /* sqlite
11630 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a  3_mutex_methods*
11640 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
11650 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
11660 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71  EX     11  /* sq
11670 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
11680 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69  ods* */./* previ
11690 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e  ously SQLITE_CON
116a0 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31  FIG_CHUNKALLOC 1
116b0 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75  2 which is now u
116c0 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69  nused. */ .#defi
116d0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
116e0 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33  _LOOKASIDE    13
116f0 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a    /* int int */.
11700 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
11710 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20  ONFIG_PCACHE    
11720 20 20 20 31 34 20 20 2f 2a 20 73 71 6c 69 74 65     14  /* sqlite
11730 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
11740 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
11750 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
11760 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 73  ACHE    15  /* s
11770 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
11780 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
11790 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
117a0 4c 4f 47 20 20 20 20 20 20 20 20 20 20 31 36 20  LOG          16 
117b0 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a   /* xFunc, void*
117c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
117d0 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20 20  TE_CONFIG_URI   
117e0 20 20 20 20 20 20 20 31 37 20 20 2f 2a 20 69 6e         17  /* in
117f0 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t */../*.** CAPI
11800 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
11810 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67  onnection Config
11820 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a  uration Options.
11830 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
11840 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76  tants are the av
11850 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20  ailable integer 
11860 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
11870 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61  tions that.** ca
11880 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  n be passed as t
11890 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
118a0 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  nt to the [sqlit
118b0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
118c0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
118d0 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69   New configurati
118e0 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62  on options may b
118f0 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
11900 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
11910 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e  Lite..** Existin
11920 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  g configuration 
11930 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65  options might be
11940 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20   discontinued.  
11950 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  Applications.** 
11960 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65  should check the
11970 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f   return code fro
11980 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  m [sqlite3_db_co
11990 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20  nfig()] to make 
119a0 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  sure that.** the
119b0 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e   call worked.  ^
119c0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  The [sqlite3_db_
119d0 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
119e0 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ace will return 
119f0 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  a.** non-zero [e
11a00 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20  rror code] if a 
11a10 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20  discontinued or 
11a20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66  unsupported conf
11a30 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
11a40 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a  .** is invoked..
11a50 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64  **.** <dl>.** <d
11a60 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
11a70 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e  G_LOOKASIDE</dt>
11a80 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
11a90 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65  ption takes thre
11aa0 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  e additional arg
11ab0 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65  uments that dete
11ac0 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c  rmine the .** [l
11ad0 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
11ae0 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69  allocator] confi
11af0 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65  guration for the
11b00 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
11b10 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20  ction]..** ^The 
11b20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28  first argument (
11b30 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
11b40 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
11b50 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20  db_config()] is 
11b60 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20  a.** pointer to 
11b70 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  a memory buffer 
11b80 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61  to use for looka
11b90 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  side memory..** 
11ba0 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
11bb0 65 6e 74 20 61 66 74 65 72 20 74 68 65 20 53 51  ent after the SQ
11bc0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
11bd0 4f 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20  OKASIDE verb.** 
11be0 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77  may be NULL in w
11bf0 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65  hich case SQLite
11c00 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74   will allocate t
11c10 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20  he.** lookaside 
11c20 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73  buffer itself us
11c30 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  ing [sqlite3_mal
11c40 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63  loc()]. ^The sec
11c50 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
11c60 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65  the.** size of e
11c70 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  ach lookaside bu
11c80 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65  ffer slot.  ^The
11c90 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
11ca0 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
11cb0 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20  .** slots.  The 
11cc0 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66  size of the buff
11cd0 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  er in the first 
11ce0 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
11cf0 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a   greater than.**
11d00 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65   or equal to the
11d10 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20   product of the 
11d20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64  second and third
11d30 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65   arguments.  The
11d40 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20   buffer.** must 
11d50 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  be aligned to an
11d60 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8-byte boundary
11d70 2e 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e  .  ^If the secon
11d80 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
11d90 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
11da0 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f  _LOOKASIDE is no
11db0 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  t a multiple of 
11dc0 38 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61  8, it is interna
11dd0 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64  lly.** rounded d
11de0 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20  own to the next 
11df0 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65  smaller multiple
11e00 20 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f   of 8.  ^(The lo
11e10 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a  okaside memory.*
11e20 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
11e30 66 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63  for a database c
11e40 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e  onnection can on
11e50 6c 79 20 62 65 20 63 68 61 6e 67 65 64 20 77 68  ly be changed wh
11e60 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65  en that.** conne
11e70 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72  ction is not cur
11e80 72 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f  rently using loo
11e90 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f  kaside memory, o
11ea0 72 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  r in other words
11eb0 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75  .** when the "cu
11ec0 72 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74  rrent value" ret
11ed0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
11ee0 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28  ite3_db_status](
11ef0 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  D,[SQLITE_CONFIG
11f00 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29  _LOOKASIDE],...)
11f10 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79   is zero..** Any
11f20 20 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e   attempt to chan
11f30 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65  ge the lookaside
11f40 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72   memory configur
11f50 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61  ation when looka
11f60 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69  side.** memory i
11f70 73 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20  s in use leaves 
11f80 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
11f90 6e 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20  n unchanged and 
11fa0 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c  returns .** [SQL
11fb0 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64  ITE_BUSY].)^</dd
11fc0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
11fd0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
11fe0 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20  LE_FKEY</dt>.** 
11ff0 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
12000 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61  n is used to ena
12010 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74  ble or disable t
12020 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f  he enforcement o
12030 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65  f.** [foreign ke
12040 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20  y constraints]. 
12050 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65   There should be
12060 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
12070 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68  arguments..** Th
12080 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
12090 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77   is an integer w
120a0 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73  hich is 0 to dis
120b0 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  able FK enforcem
120c0 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65  ent,.** positive
120d0 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e   to enable FK en
120e0 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67  forcement or neg
120f0 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46  ative to leave F
12100 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a  K enforcement.**
12110 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65   unchanged.  The
12120 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
12130 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
12140 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74  o an integer int
12150 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72  o which.** is wr
12160 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20  itten 0 or 1 to 
12170 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72  indicate whether
12180 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
12190 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20  is off or on.** 
121a0 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63  following this c
121b0 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  all.  The second
121c0 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
121d0 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
121e0 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61  , in.** which ca
121f0 73 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63  se the FK enforc
12200 65 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73  ement setting is
12210 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61   not reported ba
12220 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ck. </dd>.**.** 
12230 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
12240 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47  FIG_ENABLE_TRIGG
12250 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  ER</dt>.** <dd> 
12260 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  ^This option is 
12270 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f  used to enable o
12280 72 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54  r disable [CREAT
12290 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67  E TRIGGER | trig
122a0 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20  gers]..** There 
122b0 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64  should be two ad
122c0 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
122d0 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ts..** The first
122e0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20   argument is an 
122f0 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
12300 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72   0 to disable tr
12310 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74  iggers,.** posit
12320 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72  ive to enable tr
12330 69 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69  iggers or negati
12340 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20  ve to leave the 
12350 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65  setting unchange
12360 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  d..** The second
12370 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
12380 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
12390 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
123a0 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30  .** is written 0
123b0 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
123c0 65 20 77 68 65 74 68 65 72 20 74 72 69 67 67 65  e whether trigge
123d0 72 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  rs are disabled 
123e0 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f  or enabled.** fo
123f0 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c  llowing this cal
12400 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  l.  The second p
12410 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
12420 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
12430 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65  in.** which case
12440 20 74 68 65 20 74 72 69 67 67 65 72 20 73 65 74   the trigger set
12450 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f  ting is not repo
12460 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e  rted back. </dd>
12470 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  .**.** </dl>.*/.
12480 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
12490 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
124a0 45 20 20 20 20 20 20 20 31 30 30 31 20 20 2f 2a  E       1001  /*
124b0 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a   void* int int *
124c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
124d0 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
124e0 5f 46 4b 45 59 20 20 20 20 20 31 30 30 32 20 20  _FKEY     1002  
124f0 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23  /* int int* */.#
12500 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
12510 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52  CONFIG_ENABLE_TR
12520 49 47 47 45 52 20 20 31 30 30 33 20 20 2f 2a 20  IGGER  1003  /* 
12530 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a  int int* */.../*
12540 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e  .** CAPI3REF: En
12550 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20  able Or Disable 
12560 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20  Extended Result 
12570 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  Codes.**.** ^The
12580 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
12590 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
125a0 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73   routine enables
125b0 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
125c0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
125d0 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74  sult codes] feat
125e0 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e  ure of SQLite. ^
125f0 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73  The extended res
12600 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65  ult.** codes are
12610 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
12620 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69  ault for histori
12630 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  cal compatibilit
12640 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  y..*/.int sqlite
12650 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
12660 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a  t_codes(sqlite3*
12670 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f  , int onoff);../
12680 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c  *.** CAPI3REF: L
12690 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64  ast Insert Rowid
126a0 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74  .**.** ^Each ent
126b0 72 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20  ry in an SQLite 
126c0 74 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71  table has a uniq
126d0 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ue 64-bit signed
126e0 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20  .** integer key 
126f0 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49  called the [ROWI
12700 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54  D | "rowid"]. ^T
12710 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61  he rowid is alwa
12720 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20  ys available.** 
12730 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64  as an undeclared
12740 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f   column named RO
12750 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f  WID, OID, or _RO
12760 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20  WID_ as long as 
12770 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61  those.** names a
12780 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64  re not also used
12790 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64   by explicitly d
127a0 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e  eclared columns.
127b0 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c   ^If.** the tabl
127c0 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f  e has a column o
127d0 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20  f type [INTEGER 
127e0 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65  PRIMARY KEY] the
127f0 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  n that column.**
12800 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61   is another alia
12810 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e  s for the rowid.
12820 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
12830 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
12840 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20   [rowid] of the 
12850 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73  most recent.** s
12860 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
12870 54 5d 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61  T] into the data
12880 62 61 73 65 20 66 72 6f 6d 20 74 68 65 20 5b 64  base from the [d
12890 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
128a0 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69  on].** in the fi
128b0 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e  rst argument.  ^
128c0 41 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72  As of SQLite ver
128d0 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 74 68 69 73  sion 3.7.7, this
128e0 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 72 65 63   routines.** rec
128f0 6f 72 64 73 20 74 68 65 20 6c 61 73 74 20 69 6e  ords the last in
12900 73 65 72 74 20 72 6f 77 69 64 20 6f 66 20 62 6f  sert rowid of bo
12910 74 68 20 6f 72 64 69 6e 61 72 79 20 74 61 62 6c  th ordinary tabl
12920 65 73 20 61 6e 64 20 5b 76 69 72 74 75 61 6c 20  es and [virtual 
12930 74 61 62 6c 65 73 5d 2e 0a 2a 2a 20 5e 49 66 20  tables]..** ^If 
12940 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  no successful [I
12950 4e 53 45 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20  NSERT]s.** have 
12960 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e  ever occurred on
12970 20 74 68 61 74 20 64 61 74 61 62 61 73 65 20 63   that database c
12980 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20  onnection, zero 
12990 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
129a0 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45  ** ^(If an [INSE
129b0 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69  RT] occurs withi
129c0 6e 20 61 20 74 72 69 67 67 65 72 20 6f 72 20 77  n a trigger or w
129d0 69 74 68 69 6e 20 61 20 5b 76 69 72 74 75 61 6c  ithin a [virtual
129e0 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f   table].** metho
129f0 64 2c 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75  d, then this rou
12a00 74 69 6e 65 20 77 69 6c 6c 20 72 65 74 75 72 6e  tine will return
12a10 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20   the [rowid] of 
12a20 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20  the inserted.** 
12a30 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  row as long as t
12a40 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  he trigger or vi
12a50 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68  rtual table meth
12a60 6f 64 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  od is running..*
12a70 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74  * But once the t
12a80 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61  rigger or virtua
12a90 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 65  l table method e
12aa0 6e 64 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72  nds, the value r
12ab0 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74  eturned .** by t
12ac0 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65  his routine reve
12ad0 72 74 73 20 74 6f 20 77 68 61 74 20 69 74 20 77  rts to what it w
12ae0 61 73 20 62 65 66 6f 72 65 20 74 68 65 20 74 72  as before the tr
12af0 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c  igger or virtual
12b00 0a 2a 2a 20 74 61 62 6c 65 20 6d 65 74 68 6f 64  .** table method
12b10 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20   began.)^.**.** 
12b20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61  ^An [INSERT] tha
12b30 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61  t fails due to a
12b40 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
12b50 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a  ation is not a.*
12b60 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  * successful [IN
12b70 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e  SERT] and does n
12b80 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61  ot change the va
12b90 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
12ba0 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e  this.** routine.
12bb0 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f    ^Thus INSERT O
12bc0 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f  R FAIL, INSERT O
12bd0 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54  R IGNORE, INSERT
12be0 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a   OR ROLLBACK,.**
12bf0 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41   and INSERT OR A
12c00 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61  BORT make no cha
12c10 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74 75  nges to the retu
12c20 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  rn value of this
12c30 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e  .** routine when
12c40 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e   their insertion
12c50 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20   fails.  ^(When 
12c60 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43  INSERT OR REPLAC
12c70 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20  E.** encounters 
12c80 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  a constraint vio
12c90 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20  lation, it does 
12ca0 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a  not fail.  The.*
12cb0 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75  * INSERT continu
12cc0 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  es to completion
12cd0 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20   after deleting 
12ce0 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 64  rows that caused
12cf0 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69  .** the constrai
12d00 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e  nt problem so IN
12d10 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20  SERT OR REPLACE 
12d20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e  will always chan
12d30 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e  ge.** the return
12d40 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69   value of this i
12d50 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a  nterface.)^.**.*
12d60 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f  * ^For the purpo
12d70 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ses of this rout
12d80 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d  ine, an [INSERT]
12d90 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74   is considered t
12da0 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66  o.** be successf
12db0 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69 73  ul even if it is
12dc0 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f   subsequently ro
12dd0 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a  lled back..**.**
12de0 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69   This function i
12df0 73 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20  s accessible to 
12e00 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76  SQL statements v
12e10 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f  ia the.** [last_
12e20 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53  insert_rowid() S
12e30 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
12e40 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
12e50 65 20 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d  e thread perform
12e60 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d  s a new [INSERT]
12e70 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20   on the same.** 
12e80 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
12e90 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73  ion while the [s
12ea0 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
12eb0 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66  rt_rowid()].** f
12ec0 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
12ed0 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e  ng and thus chan
12ee0 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73  ges the last ins
12ef0 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20  ert [rowid],.** 
12f00 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72  then the value r
12f10 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
12f20 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
12f30 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75  rowid()] is.** u
12f40 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
12f50 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c   might not equal
12f60 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20   either the old 
12f70 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61  or the new.** la
12f80 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64  st insert [rowid
12f90 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e  ]..*/.sqlite3_in
12fa0 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74  t64 sqlite3_last
12fb0 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71  _insert_rowid(sq
12fc0 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
12fd0 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20  CAPI3REF: Count 
12fe0 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f  The Number Of Ro
12ff0 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a  ws Modified.**.*
13000 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
13010 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
13020 62 65 72 20 6f 66 20 64 61 74 61 62 61 73 65 20  ber of database 
13030 72 6f 77 73 20 74 68 61 74 20 77 65 72 65 20 63  rows that were c
13040 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73  hanged.** or ins
13050 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64  erted or deleted
13060 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63   by the most rec
13070 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20  ently completed 
13080 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL statement.**
13090 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73   on the [databas
130a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70  e connection] sp
130b0 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 66  ecified by the f
130c0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a  irst parameter..
130d0 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61 6e 67 65  ** ^(Only change
130e0 73 20 74 68 61 74 20 61 72 65 20 64 69 72 65 63  s that are direc
130f0 74 6c 79 20 73 70 65 63 69 66 69 65 64 20 62 79  tly specified by
13100 20 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c 20 5b   the [INSERT], [
13110 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b  UPDATE],.** or [
13120 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e  DELETE] statemen
13130 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 20 20  t are counted.  
13140 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65  Auxiliary change
13150 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a 20 74  s caused by.** t
13160 72 69 67 67 65 72 73 20 6f 72 20 5b 66 6f 72 65  riggers or [fore
13170 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d  ign key actions]
13180 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64   are not counted
13190 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a 2a 20 5b  .)^ Use the.** [
131a0 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
131b0 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f  anges()] functio
131c0 6e 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f  n to find the to
131d0 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  tal number of ch
131e0 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75 64 69  anges.** includi
131f0 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ng changes cause
13200 64 20 62 79 20 74 72 69 67 67 65 72 73 20 61 6e  d by triggers an
13210 64 20 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63  d foreign key ac
13220 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68  tions..**.** ^Ch
13230 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20  anges to a view 
13240 74 68 61 74 20 61 72 65 20 73 69 6d 75 6c 61 74  that are simulat
13250 65 64 20 62 79 20 61 6e 20 5b 49 4e 53 54 45 41  ed by an [INSTEA
13260 44 20 4f 46 20 74 72 69 67 67 65 72 5d 0a 2a 2a  D OF trigger].**
13270 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64   are not counted
13280 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74 61 62  .  Only real tab
13290 6c 65 20 63 68 61 6e 67 65 73 20 61 72 65 20 63  le changes are c
132a0 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ounted..**.** ^(
132b0 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20 69  A "row change" i
132c0 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61 20  s a change to a 
132d0 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61 20  single row of a 
132e0 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20  single table.** 
132f0 63 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e 53  caused by an INS
13300 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20  ERT, DELETE, or 
13310 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74  UPDATE statement
13320 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20  .  Rows that.** 
13330 61 72 65 20 63 68 61 6e 67 65 64 20 61 73 20 73  are changed as s
13340 69 64 65 20 65 66 66 65 63 74 73 20 6f 66 20 5b  ide effects of [
13350 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61  REPLACE] constra
13360 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a  int resolution,.
13370 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f  ** rollback, ABO
13380 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 5b  RT processing, [
13390 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f 72 20  DROP TABLE], or 
133a0 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  by any other.** 
133b0 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f  mechanisms do no
133c0 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65 63  t count as direc
133d0 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 29 5e  t row changes.)^
133e0 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 65  .**.** A "trigge
133f0 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61 20  r context" is a 
13400 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74 69  scope of executi
13410 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20 61  on that begins a
13420 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 20  nd.** ends with 
13430 74 68 65 20 73 63 72 69 70 74 20 6f 66 20 61 20  the script of a 
13440 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20  [CREATE TRIGGER 
13450 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a 20  | trigger]. .** 
13460 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65  Most SQL stateme
13470 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75  nts are.** evalu
13480 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66 20  ated outside of 
13490 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54 68  any trigger.  Th
134a0 69 73 20 69 73 20 74 68 65 20 22 74 6f 70 20 6c  is is the "top l
134b0 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72  evel".** trigger
134c0 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 20   context.  If a 
134d0 74 72 69 67 67 65 72 20 66 69 72 65 73 20 66 72  trigger fires fr
134e0 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c  om the top level
134f0 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67  , a.** new trigg
13500 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65 6e  er context is en
13510 74 65 72 65 64 20 66 6f 72 20 74 68 65 20 64 75  tered for the du
13520 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f  ration of that o
13530 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 20  ne.** trigger.  
13540 53 75 62 74 72 69 67 67 65 72 73 20 63 72 65 61  Subtriggers crea
13550 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20 66  te subcontexts f
13560 6f 72 20 74 68 65 69 72 20 64 75 72 61 74 69 6f  or their duratio
13570 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  n..**.** ^Callin
13580 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  g [sqlite3_exec(
13590 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73  )] or [sqlite3_s
135a0 74 65 70 28 29 5d 20 72 65 63 75 72 73 69 76 65  tep()] recursive
135b0 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63  ly does.** not c
135c0 72 65 61 74 65 20 61 20 6e 65 77 20 74 72 69 67  reate a new trig
135d0 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a  ger context..**.
135e0 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
135f0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
13600 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74 20 72  mber of direct r
13610 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  ow changes in th
13620 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74  e.** most recent
13630 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
13640 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65   or DELETE state
13650 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20  ment within the 
13660 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72 20  same.** trigger 
13670 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e  context..**.** ^
13680 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c 65  Thus, when calle
13690 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c  d from the top l
136a0 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e 63 74  evel, this funct
136b0 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ion returns the.
136c0 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  ** number of cha
136d0 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74  nges in the most
136e0 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20   recent INSERT, 
136f0 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
13700 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f  E.** that also o
13710 63 63 75 72 72 65 64 20 61 74 20 74 68 65 20 74  ccurred at the t
13720 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28 57 69 74  op level.  ^(Wit
13730 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20  hin the body of 
13740 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74 68  a trigger,.** th
13750 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  e sqlite3_change
13760 73 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  s() interface ca
13770 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20 66  n be called to f
13780 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ind the number o
13790 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20  f.** changes in 
137a0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c  the most recentl
137b0 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45  y completed INSE
137c0 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
137d0 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65  ELETE.** stateme
137e0 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 62 6f  nt within the bo
137f0 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20 74  dy of the same t
13800 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76  rigger..** Howev
13810 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 72  er, the number r
13820 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74  eturned does not
13830 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73   include changes
13840 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73 75  .** caused by su
13850 62 74 72 69 67 67 65 72 73 20 73 69 6e 63 65 20  btriggers since 
13860 74 68 6f 73 65 20 68 61 76 65 20 74 68 65 69 72  those have their
13870 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 29 5e 0a   own context.)^.
13880 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  **.** See also t
13890 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  he [sqlite3_tota
138a0 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74  l_changes()] int
138b0 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b  erface, the.** [
138c0 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72  count_changes pr
138d0 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b  agma], and the [
138e0 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
138f0 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
13900 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
13910 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ead makes change
13920 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  s on the same da
13930 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
13940 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69  n.** while [sqli
13950 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  te3_changes()] i
13960 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74  s running then t
13970 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
13980 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63  d.** is unpredic
13990 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65  table and not me
139a0 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74  aningful..*/.int
139b0 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
139c0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
139d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74  ** CAPI3REF: Tot
139e0 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77  al Number Of Row
139f0 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a  s Modified.**.**
13a00 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
13a10 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
13a20 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65  er of row change
13a30 73 20 63 61 75 73 65 64 20 62 79 20 5b 49 4e 53  s caused by [INS
13a40 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54 45  ERT],.** [UPDATE
13a50 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74  ] or [DELETE] st
13a60 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65 20 74  atements since t
13a70 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
13a80 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70 65  nection] was ope
13a90 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65 20 63 6f  ned..** ^(The co
13aa0 75 6e 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  unt returned by 
13ab0 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
13ac0 61 6e 67 65 73 28 29 20 69 6e 63 6c 75 64 65 73  anges() includes
13ad0 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a 2a 2a 20   all changes.** 
13ae0 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41 54 45  from all [CREATE
13af0 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67   TRIGGER | trigg
13b00 65 72 5d 20 63 6f 6e 74 65 78 74 73 20 61 6e 64  er] contexts and
13b10 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 62 79   changes made by
13b20 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79  .** [foreign key
13b30 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f 77 65 76   actions]. Howev
13b40 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74  er,.** the count
13b50 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
13b60 65 20 63 68 61 6e 67 65 73 20 75 73 65 64 20 74  e changes used t
13b70 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52 45 50  o implement [REP
13b80 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74  LACE] constraint
13b90 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63  s,.** do rollbac
13ba0 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f 63  ks or ABORT proc
13bb0 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52 4f 50  essing, or [DROP
13bc0 20 54 41 42 4c 45 5d 20 70 72 6f 63 65 73 73 69   TABLE] processi
13bd0 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f 75 6e  ng.  The.** coun
13be0 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  t does not inclu
13bf0 64 65 20 72 6f 77 73 20 6f 66 20 76 69 65 77 73  de rows of views
13c00 20 74 68 61 74 20 66 69 72 65 20 61 6e 20 5b 49   that fire an [I
13c10 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
13c20 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20 69 66  r],.** though if
13c30 20 74 68 65 20 49 4e 53 54 45 41 44 20 4f 46 20   the INSTEAD OF 
13c40 74 72 69 67 67 65 72 20 6d 61 6b 65 73 20 63 68  trigger makes ch
13c50 61 6e 67 65 73 20 6f 66 20 69 74 73 20 6f 77 6e  anges of its own
13c60 2c 20 74 68 6f 73 65 20 63 68 61 6e 67 65 73 20  , those changes 
13c70 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65 64 2e  .** are counted.
13c80 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  )^.** ^The sqlit
13c90 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
13ca0 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 6f 75 6e  () function coun
13cb0 74 73 20 74 68 65 20 63 68 61 6e 67 65 73 20 61  ts the changes a
13cc0 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74 68 65  s soon as.** the
13cd0 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
13ce0 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 20 63 6f  makes them is co
13cf0 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74 68  mpleted (when th
13d00 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  e statement hand
13d10 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20  le.** is passed 
13d20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
13d30 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
13d40 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a  _finalize()])..*
13d50 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
13d60 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
13d70 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c  es()] interface,
13d80 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63   the.** [count_c
13d90 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20  hanges pragma], 
13da0 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63  and the [total_c
13db0 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e  hanges() SQL fun
13dc0 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ction]..**.** If
13dd0 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
13de0 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  ad makes changes
13df0 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
13e00 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
13e10 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  .** while [sqlit
13e20 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
13e30 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ()] is running t
13e40 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a  hen the value.**
13e50 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70   returned is unp
13e60 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e  redictable and n
13e70 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a  ot meaningful..*
13e80 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f  /.int sqlite3_to
13e90 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69  tal_changes(sqli
13ea0 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
13eb0 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70  PI3REF: Interrup
13ec0 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67  t A Long-Running
13ed0 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68   Query.**.** ^Th
13ee0 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73  is function caus
13ef0 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64  es any pending d
13f00 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f  atabase operatio
13f10 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a  n to abort and.*
13f20 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73 20  * return at its 
13f30 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75  earliest opportu
13f40 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69  nity. This routi
13f50 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a  ne is typically.
13f60 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73  ** called in res
13f70 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20  ponse to a user 
13f80 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70  action such as p
13f90 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22  ressing "Cancel"
13fa0 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68  .** or Ctrl-C wh
13fb0 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61 6e  ere the user wan
13fc0 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20  ts a long query 
13fd0 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c  operation to hal
13fe0 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79  t.** immediately
13ff0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73  ..**.** ^It is s
14000 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73  afe to call this
14010 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20   routine from a 
14020 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e 74  thread different
14030 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72   from the.** thr
14040 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72 72  ead that is curr
14050 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68  ently running th
14060 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61  e database opera
14070 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a  tion.  But it.**
14080 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
14090 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e  call this routin
140a0 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61  e with a [databa
140b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
140c0 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64  hat.** is closed
140d0 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20   or might close 
140e0 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69  before sqlite3_i
140f0 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75 72  nterrupt() retur
14100 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ns..**.** ^If an
14110 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69   SQL operation i
14120 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69  s very nearly fi
14130 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74 69  nished at the ti
14140 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  me when.** sqlit
14150 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69  e3_interrupt() i
14160 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69  s called, then i
14170 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65  t might not have
14180 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a   an opportunity.
14190 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75  ** to be interru
141a0 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63  pted and might c
141b0 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c  ontinue to compl
141c0 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e  etion..**.** ^An
141d0 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74   SQL operation t
141e0 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74  hat is interrupt
141f0 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  ed will return [
14200 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
14210 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e  ]..** ^If the in
14220 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70  terrupted SQL op
14230 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e  eration is an IN
14240 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
14250 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20   DELETE.** that 
14260 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70  is inside an exp
14270 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
14280 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69  n, then the enti
14290 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a  re transaction.*
142a0 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64  * will be rolled
142b0 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61   back automatica
142c0 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  lly..**.** ^The 
142d0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
142e0 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20  t(D) call is in 
142f0 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c  effect until all
14300 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69   currently runni
14310 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  ng.** SQL statem
14320 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73  ents on [databas
14330 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
14340 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20  complete.  ^Any 
14350 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  new SQL statemen
14360 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
14370 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65  tarted after the
14380 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
14390 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65  pt() call and be
143a0 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e  fore the .** run
143b0 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20  ning statements 
143c0 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65  reaches zero are
143d0 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 73 20   interrupted as 
143e0 69 66 20 74 68 65 79 20 68 61 64 20 62 65 65 6e  if they had been
143f0 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f  .** running prio
14400 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
14410 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
14420 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 61  l.  ^New SQL sta
14430 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20  tements.** that 
14440 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65  are started afte
14450 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74  r the running st
14460 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65  atement count re
14470 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a  aches zero are.*
14480 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62  * not effected b
14490 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  y the sqlite3_in
144a0 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41  terrupt()..** ^A
144b0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
144c0 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 74 68  _interrupt(D) th
144d0 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74  at occurs when t
144e0 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e  here are no runn
144f0 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ing.** SQL state
14500 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70  ments is a no-op
14510 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65   and has no effe
14520 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d  ct on SQL statem
14530 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
14540 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
14550 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
14560 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75  rupt() call retu
14570 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  rns..**.** If th
14580 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
14590 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69  ction closes whi
145a0 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65  le [sqlite3_inte
145b0 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72  rrupt()].** is r
145c0 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20  unning then bad 
145d0 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65  things will like
145e0 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f  ly happen..*/.vo
145f0 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  id sqlite3_inter
14600 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a  rupt(sqlite3*);.
14610 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
14620 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e   Determine If An
14630 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49   SQL Statement I
14640 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a  s Complete.**.**
14650 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
14660 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e  are useful durin
14670 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69  g command-line i
14680 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e  nput to determin
14690 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72  e if the.** curr
146a0 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65  ently entered te
146b0 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d  xt seems to form
146c0 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
146d0 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20  statement or.** 
146e0 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  if additional in
146f0 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 65  put is needed be
14700 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65  fore sending the
14710 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51   text into.** SQ
14720 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67  Lite for parsing
14730 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  .  ^These routin
14740 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20 74  es return 1 if t
14750 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a  he input string.
14760 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65  ** appears to be
14770 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
14780 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73  statement.  ^A s
14790 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67  tatement is judg
147a0 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70  ed to be.** comp
147b0 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 20  lete if it ends 
147c0 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e  with a semicolon
147d0 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f   token and is no
147e0 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a  t a prefix of a.
147f0 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43  ** well-formed C
14800 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74  REATE TRIGGER st
14810 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63  atement.  ^Semic
14820 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65  olons that are e
14830 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a  mbedded within.*
14840 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  * string literal
14850 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e  s or quoted iden
14860 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20  tifier names or 
14870 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74  comments are not
14880 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20  .** independent 
14890 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65  tokens (they are
148a0 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b   part of the tok
148b0 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 79  en in which they
148c0 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64   are.** embedded
148d0 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f  ) and thus do no
148e0 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61  t count as a sta
148f0 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f  tement terminato
14900 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a  r.  ^Whitespace.
14910 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20  ** and comments 
14920 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20  that follow the 
14930 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20  final semicolon 
14940 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a  are ignored..**.
14950 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
14960 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20 74  es return 0 if t
14970 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
14980 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66  incomplete.  ^If
14990 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c   a.** memory all
149a0 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74  ocation fails, t
149b0 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  hen SQLITE_NOMEM
149c0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
149d0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
149e0 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65  nes do not parse
149f0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
14a00 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c  nts thus.** will
14a10 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74   not detect synt
14a20 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72  actically incorr
14a30 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  ect SQL..**.** ^
14a40 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e  (If SQLite has n
14a50 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69  ot been initiali
14a60 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  zed using [sqlit
14a70 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
14a80 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e   prior .** to in
14a90 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  voking sqlite3_c
14aa0 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e  omplete16() then
14ab0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
14ac0 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
14ad0 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
14ae0 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d  y by sqlite3_com
14af0 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20 74  plete16().  If t
14b00 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  hat initializati
14b10 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65  on fails,.** the
14b20 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  n the return val
14b30 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
14b40 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c  complete16() wil
14b50 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a  l be non-zero.**
14b60 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
14b70 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
14b80 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63  e input SQL is c
14b90 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a  omplete.)^.**.**
14ba0 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73   The input to [s
14bb0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
14bc0 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72  )] must be a zer
14bd0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
14be0 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a  UTF-8 string..**
14bf0 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f  .** The input to
14c00 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
14c10 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20  te16()] must be 
14c20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
14c30 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69  d.** UTF-16 stri
14c40 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74  ng in native byt
14c50 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20  e order..*/.int 
14c60 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
14c70 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  (const char *sql
14c80 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
14c90 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20  omplete16(const 
14ca0 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a  void *sql);../*.
14cb0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67  ** CAPI3REF: Reg
14cc0 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b  ister A Callback
14cd0 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54   To Handle SQLIT
14ce0 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a  E_BUSY Errors.**
14cf0 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
14d00 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63  e sets a callbac
14d10 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  k function that 
14d20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64  might be invoked
14d30 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20   whenever.** an 
14d40 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20  attempt is made 
14d50 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61 62 61  to open a databa
14d60 73 65 20 74 61 62 6c 65 20 74 68 61 74 20 61 6e  se table that an
14d70 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20  other thread.** 
14d80 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 20 6c  or process has l
14d90 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  ocked..**.** ^If
14da0 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   the busy callba
14db0 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  ck is NULL, then
14dc0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f   [SQLITE_BUSY] o
14dd0 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
14de0 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72  BLOCKED].** is r
14df0 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74  eturned immediat
14e00 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74  ely upon encount
14e10 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20  ering the lock. 
14e20 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61   ^If the busy ca
14e30 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74  llback.** is not
14e40 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20   NULL, then the 
14e50 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62  callback might b
14e60 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74  e invoked with t
14e70 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  wo arguments..**
14e80 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
14e90 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62  rgument to the b
14ea0 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61  usy handler is a
14eb0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69   copy of the voi
14ec0 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68  d* pointer which
14ed0 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 64  .** is the third
14ee0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
14ef0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
14f00 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e  r().  ^The secon
14f10 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
14f20 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
14f30 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68  r callback is th
14f40 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65  e number of time
14f50 73 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20  s that the busy 
14f60 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62  handler has.** b
14f70 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20  een invoked for 
14f80 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65  this locking eve
14f90 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  nt.  ^If the.** 
14fa0 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65  busy callback re
14fb0 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f  turns 0, then no
14fc0 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65   additional atte
14fd0 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f  mpts are made to
14fe0 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20 64  .** access the d
14ff0 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c  atabase and [SQL
15000 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51  ITE_BUSY] or [SQ
15010 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
15020 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ED] is returned.
15030 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c  .** ^If the call
15040 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e  back returns non
15050 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74  -zero, then anot
15060 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69  her attempt.** i
15070 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 74  s made to open t
15080 68 65 20 64 61 74 61 62 61 73 65 20 66 6f 72 20  he database for 
15090 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68 65 20  reading and the 
150a0 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a  cycle repeats..*
150b0 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63  *.** The presenc
150c0 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64  e of a busy hand
150d0 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61  ler does not gua
150e0 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 77  rantee that it w
150f0 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a  ill be invoked.*
15100 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20  * when there is 
15110 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e  lock contention.
15120 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74 65   ^If SQLite dete
15130 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f  rmines that invo
15140 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a  king the busy.**
15150 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72   handler could r
15160 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c  esult in a deadl
15170 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20  ock, it will go 
15180 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e  ahead and return
15190 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a   [SQLITE_BUSY].*
151a0 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  * or [SQLITE_IOE
151b0 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 74  RR_BLOCKED] inst
151c0 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20  ead of invoking 
151d0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
151e0 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20  ..** Consider a 
151f0 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f  scenario where o
15200 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f  ne process is ho
15210 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63  lding a read loc
15220 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20  k that.** it is 
15230 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74  trying to promot
15240 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64 20  e to a reserved 
15250 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65  lock and.** a se
15260 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20  cond process is 
15270 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76  holding a reserv
15280 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20  ed lock that it 
15290 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20  is trying.** to 
152a0 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78  promote to an ex
152b0 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54  clusive lock.  T
152c0 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
152d0 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a   cannot proceed.
152e0 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69 73  ** because it is
152f0 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20   blocked by the 
15300 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73  second and the s
15310 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61  econd process ca
15320 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20  nnot.** proceed 
15330 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c  because it is bl
15340 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69 72  ocked by the fir
15350 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f  st.  If both pro
15360 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65  cesses.** invoke
15370 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
15380 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c  rs, neither will
15390 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65   make any progre
153a0 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a  ss.  Therefore,.
153b0 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e  ** SQLite return
153c0 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  s [SQLITE_BUSY] 
153d0 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70 72  for the first pr
153e0 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68  ocess, hoping th
153f0 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20  at this.** will 
15400 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73 74  induce the first
15410 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65   process to rele
15420 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63  ase its read loc
15430 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74  k and allow.** t
15440 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73  he second proces
15450 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a  s to proceed..**
15460 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74  .** ^The default
15470 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69   busy callback i
15480 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s NULL..**.** ^T
15490 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  he [SQLITE_BUSY]
154a0 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 72   error is conver
154b0 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49  ted to [SQLITE_I
154c0 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a  OERR_BLOCKED].**
154d0 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
154e0 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66  in the middle of
154f0 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63   a large transac
15500 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 74  tion where all t
15510 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 69  he.** changes wi
15520 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20  ll not fit into 
15530 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61  the in-memory ca
15540 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77 69 6c  che.  SQLite wil
15550 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c  l.** already hol
15560 64 20 61 20 52 45 53 45 52 56 45 44 20 6c 6f 63  d a RESERVED loc
15570 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73  k on the databas
15580 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74 20 6e  e file, but it n
15590 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f  eeds.** to promo
155a0 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20  te this lock to 
155b0 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74 68 61  EXCLUSIVE so tha
155c0 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 63  t it can spill c
155d0 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e  ache.** pages in
155e0 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
155f0 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68 61 72  file without har
15600 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a  m to concurrent.
15610 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 5e 49 66  ** readers.  ^If
15620 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f   it is unable to
15630 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63   promote the loc
15640 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d  k, then the in-m
15650 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 77  emory.** cache w
15660 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 61  ill be left in a
15670 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73  n inconsistent s
15680 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68 65 20  tate and so the 
15690 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73  error.** code is
156a0 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74   promoted from t
156b0 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20 62 65  he relatively be
156c0 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  nign [SQLITE_BUS
156d0 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72  Y] to.** the mor
156e0 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49 54 45  e severe [SQLITE
156f0 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e  _IOERR_BLOCKED].
15700 20 20 5e 54 68 69 73 20 65 72 72 6f 72 20 63 6f    ^This error co
15710 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20  de promotion.** 
15720 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f 6d 61  forces an automa
15730 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20  tic rollback of 
15740 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20 53 65  the changes.  Se
15750 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66  e the.** <a href
15760 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 3f  ="/cvstrac/wiki?
15770 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c  p=CorruptionFoll
15780 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 22 3e  owingBusyError">
15790 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f  .** CorruptionFo
157a0 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72  llowingBusyError
157b0 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 20 66  </a> wiki page f
157c0 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f 6e 20  or a discussion 
157d0 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 69  of why.** this i
157e0 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a  s important..**.
157f0 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f  ** ^(There can o
15800 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20  nly be a single 
15810 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66  busy handler def
15820 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a  ined for each.**
15830 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
15840 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67  ction].  Setting
15850 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64   a new busy hand
15860 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a  ler clears any.*
15870 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74  * previously set
15880 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f   handler.)^  ^No
15890 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20  te that calling 
158a0 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69  [sqlite3_busy_ti
158b0 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c  meout()].** will
158c0 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c 65   also set or cle
158d0 61 72 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ar the busy hand
158e0 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62  ler..**.** The b
158f0 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f  usy callback sho
15900 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79  uld not take any
15910 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d   actions which m
15920 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74  odify the.** dat
15930 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
15940 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
15950 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20  e busy handler. 
15960 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e   Any such action
15970 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75  s.** result in u
15980 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f  ndefined behavio
15990 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79  r..** .** A busy
159a0 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f   handler must no
159b0 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61  t close the data
159c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
159d0 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20  ** or [prepared 
159e0 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
159f0 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79  invoked the busy
15a00 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74   handler..*/.int
15a10 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
15a20 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20  ndler(sqlite3*, 
15a30 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74  int(*)(void*,int
15a40 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
15a50 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20  * CAPI3REF: Set 
15a60 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a  A Busy Timeout.*
15a70 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
15a80 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74  ne sets a [sqlit
15a90 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20  e3_busy_handler 
15aa0 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20  | busy handler] 
15ab0 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66  that sleeps.** f
15ac0 6f 72 20 61 20 73 70 65 63 69 66 69 65 64 20 61  or a specified a
15ad0 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68  mount of time wh
15ae0 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f  en a table is lo
15af0 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 6e 64  cked.  ^The hand
15b00 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65  ler.** will slee
15b10 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73  p multiple times
15b20 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20   until at least 
15b30 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  "ms" millisecond
15b40 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a  s of sleeping.**
15b50 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65   have accumulate
15b60 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20 6c 65  d.  ^After at le
15b70 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65  ast "ms" millise
15b80 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e  conds of sleepin
15b90 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65  g,.** the handle
15ba0 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69 63  r returns 0 whic
15bb0 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65  h causes [sqlite
15bc0 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74  3_step()] to ret
15bd0 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42  urn.** [SQLITE_B
15be0 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  USY] or [SQLITE_
15bf0 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a  IOERR_BLOCKED]..
15c00 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74  **.** ^Calling t
15c10 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68  his routine with
15c20 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73   an argument les
15c30 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  s than or equal 
15c40 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73  to zero.** turns
15c50 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61   off all busy ha
15c60 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ndlers..**.** ^(
15c70 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62  There can only b
15c80 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20  e a single busy 
15c90 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61  handler for a pa
15ca0 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74  rticular.** [dat
15cb0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
15cc0 5d 20 61 6e 79 20 61 6e 79 20 67 69 76 65 6e 20  ] any any given 
15cd0 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74  moment.  If anot
15ce0 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72  her busy handler
15cf0 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20  .** was defined 
15d00 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33   (using [sqlite3
15d10 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d  _busy_handler()]
15d20 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69  ) prior to calli
15d30 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69  ng.** this routi
15d40 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62  ne, that other b
15d50 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63  usy handler is c
15d60 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a 69 6e 74  leared.)^.*/.int
15d70 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69   sqlite3_busy_ti
15d80 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20  meout(sqlite3*, 
15d90 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20  int ms);../*.** 
15da0 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e  CAPI3REF: Conven
15db0 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46  ience Routines F
15dc0 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69  or Running Queri
15dd0 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73  es.**.** This is
15de0 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66   a legacy interf
15df0 61 63 65 20 74 68 61 74 20 69 73 20 70 72 65 73  ace that is pres
15e00 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b 77 61  erved for backwa
15e10 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
15e20 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68 69  y..** Use of thi
15e30 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  s interface is n
15e40 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a  ot recommended..
15e50 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e  **.** Definition
15e60 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61  : A <b>result ta
15e70 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72  ble</b> is memor
15e80 79 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  y data structure
15e90 20 63 72 65 61 74 65 64 20 62 79 20 74 68 65 0a   created by the.
15ea0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  ** [sqlite3_get_
15eb0 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61  table()] interfa
15ec0 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61  ce.  A result ta
15ed0 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a  ble records the.
15ee0 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72  ** complete quer
15ef0 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f  y results from o
15f00 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69  ne or more queri
15f10 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61  es..**.** The ta
15f20 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79  ble conceptually
15f30 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66   has a number of
15f40 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e   rows and column
15f50 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65  s.  But.** these
15f60 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74   numbers are not
15f70 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 65 73   part of the res
15f80 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66  ult table itself
15f90 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62  .  These.** numb
15fa0 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64  ers are obtained
15fb0 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65   separately.  Le
15fc0 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65  t N be the numbe
15fd0 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64  r of rows.** and
15fe0 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72   M be the number
15ff0 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a   of columns..**.
16000 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
16010 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  e is an array of
16020 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72   pointers to zer
16030 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
16040 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54  -8 strings..** T
16050 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d  here are (N+1)*M
16060 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65   elements in the
16070 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 69 72   array.  The fir
16080 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f  st M pointers po
16090 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74  int.** to zero-t
160a0 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
160b0 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20  s that  contain 
160c0 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65  the names of the
160d0 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65   columns..** The
160e0 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69   remaining entri
160f0 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20  es all point to 
16100 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20  query results.  
16110 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75  NULL values resu
16120 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f  lt.** in NULL po
16130 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68  inters.  All oth
16140 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e  er values are in
16150 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72   their UTF-8 zer
16160 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
16170 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74  string represent
16180 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65  ation as returne
16190 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d by [sqlite3_co
161a0 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a  lumn_text()]..**
161b0 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
161c0 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74  le might consist
161d0 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20   of one or more 
161e0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
161f0 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74  ns..** It is not
16200 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 61 20   safe to pass a 
16210 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72  result table dir
16220 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65  ectly to [sqlite
16230 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20  3_free()]..** A 
16240 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f  result table sho
16250 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  uld be deallocat
16260 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
16270 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e  3_free_table()].
16280 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65  .**.** ^(As an e
16290 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65  xample of the re
162a0 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61  sult table forma
162b0 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75 65  t, suppose a que
162c0 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20  ry result.** is 
162d0 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
162e0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
162f0 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61  re>.**        Na
16300 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a  me        | Age.
16310 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d  **        ------
16320 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
16330 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63  -.**        Alic
16340 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20  e       | 43.** 
16350 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20 20         Bob      
16360 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20     | 28.**      
16370 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20    Cindy       | 
16380 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  21.** </pre></bl
16390 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
163a0 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f  There are two co
163b0 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20  lumn (M==2) and 
163c0 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33  three rows (N==3
163d0 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20  ).  Thus the.** 
163e0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73  result table has
163f0 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70   8 entries.  Sup
16400 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74 20  pose the result 
16410 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a  table is stored.
16420 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e  ** in an array n
16430 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20  ames azResult.  
16440 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f  Then azResult ho
16450 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74  lds this content
16460 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
16470 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
16480 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
16490 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a  ;0] = "Name";.**
164a0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
164b0 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b  &#91;1] = "Age";
164c0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
164d0 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c  ult&#91;2] = "Al
164e0 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ice";.**        
164f0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20  azResult&#91;3] 
16500 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20  = "43";.**      
16510 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34    azResult&#91;4
16520 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20  ] = "Bob";.**   
16530 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
16540 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20  1;5] = "28";.** 
16550 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
16560 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22  #91;6] = "Cindy"
16570 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
16580 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32  sult&#91;7] = "2
16590 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  1";.** </pre></b
165a0 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a  lockquote>)^.**.
165b0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
165c0 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63  get_table() func
165d0 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f  tion evaluates o
165e0 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65  ne or more.** se
165f0 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65  micolon-separate
16600 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  d SQL statements
16610 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72   in the zero-ter
16620 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a  minated UTF-8.**
16630 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32   string of its 2
16640 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64  nd parameter and
16650 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c   returns a resul
16660 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a  t table to the.*
16670 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20  * pointer given 
16680 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 61 6d  in its 3rd param
16690 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65  eter..**.** Afte
166a0 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
166b0 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  n has finished w
166c0 69 74 68 20 74 68 65 20 72 65 73 75 6c 74 20 66  ith the result f
166d0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  rom sqlite3_get_
166e0 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d  table(),.** it m
166f0 75 73 74 20 70 61 73 73 20 74 68 65 20 72 65 73  ust pass the res
16700 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65  ult table pointe
16710 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65  r to sqlite3_fre
16720 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64  e_table() in ord
16730 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65  er to.** release
16740 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74   the memory that
16750 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20   was malloced.  
16760 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 77  Because of the w
16770 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ay the.** [sqlit
16780 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70  e3_malloc()] hap
16790 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69  pens within sqli
167a0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c  te3_get_table(),
167b0 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20   the calling.** 
167c0 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  function must no
167d0 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73  t try to call [s
167e0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64  qlite3_free()] d
167f0 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a  irectly.  Only.*
16800 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  * [sqlite3_free_
16810 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65  table()] is able
16820 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20   to release the 
16830 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20  memory properly 
16840 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a  and safely..**.*
16850 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65  * The sqlite3_ge
16860 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66  t_table() interf
16870 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74  ace is implement
16880 65 64 20 61 73 20 61 20 77 72 61 70 70 65 72 20  ed as a wrapper 
16890 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  around.** [sqlit
168a0 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65  e3_exec()].  The
168b0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
168c0 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65  le() routine doe
168d0 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73  s not have acces
168e0 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65  s.** to any inte
168f0 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63 74  rnal data struct
16900 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20  ures of SQLite. 
16910 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68   It uses only th
16920 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65  e public.** inte
16930 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 68 65  rface defined he
16940 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71  re.  As a conseq
16950 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68  uence, errors th
16960 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a  at occur in the.
16970 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65 72  ** wrapper layer
16980 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20   outside of the 
16990 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65  internal [sqlite
169a0 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61  3_exec()] call a
169b0 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63  re not.** reflec
169c0 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e  ted in subsequen
169d0 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  t calls to [sqli
169e0 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f  te3_errcode()] o
169f0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72  r.** [sqlite3_er
16a00 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  rmsg()]..*/.int 
16a10 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
16a20 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  e(.  sqlite3 *db
16a30 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e  ,          /* An
16a40 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a   open database *
16a50 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
16a60 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c  zSql,     /* SQL
16a70 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64   to be evaluated
16a80 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61   */.  char ***pa
16a90 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52  zResult,    /* R
16aa0 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75  esults of the qu
16ab0 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e  ery */.  int *pn
16ac0 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f  Row,           /
16ad0 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75  * Number of resu
16ae0 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20  lt rows written 
16af0 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  here */.  int *p
16b00 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20  nColumn,        
16b10 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73  /* Number of res
16b20 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74  ult columns writ
16b30 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68  ten here */.  ch
16b40 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20  ar **pzErrmsg   
16b50 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67      /* Error msg
16b60 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
16b70 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .);.void sqlite3
16b80 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72  _free_table(char
16b90 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a   **result);../*.
16ba0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72  ** CAPI3REF: For
16bb0 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20 50 72  matted String Pr
16bc0 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73  inting Functions
16bd0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
16be0 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61  tines are work-a
16bf0 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72  likes of the "pr
16c00 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f  intf()" family o
16c10 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66  f functions.** f
16c20 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64  rom the standard
16c30 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a   C library..**.*
16c40 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  * ^The sqlite3_m
16c50 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c  printf() and sql
16c60 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20  ite3_vmprintf() 
16c70 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20 74  routines write t
16c80 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20  heir.** results 
16c90 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  into memory obta
16ca0 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
16cb0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a  e3_malloc()]..**
16cc0 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74   The strings ret
16cd0 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 74  urned by these t
16ce0 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75  wo routines shou
16cf0 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65  ld be.** release
16d00 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72  d by [sqlite3_fr
16d10 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f  ee()].  ^Both ro
16d20 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a  utines return a.
16d30 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
16d40 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  if [sqlite3_mall
16d50 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20  oc()] is unable 
16d60 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75  to allocate enou
16d70 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20  gh.** memory to 
16d80 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69  hold the resulti
16d90 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ng string..**.**
16da0 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73   ^(The sqlite3_s
16db0 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  nprintf() routin
16dc0 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20  e is similar to 
16dd0 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f  "snprintf()" fro
16de0 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72  m.** the standar
16df0 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68  d C library.  Th
16e00 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 74  e result is writ
16e10 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  ten into the.** 
16e20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 20  buffer supplied 
16e30 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
16e40 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69  rameter whose si
16e50 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a  ze is given by.*
16e60 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  * the first para
16e70 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74  meter. Note that
16e80 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68   the order of th
16e90 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70  e.** first two p
16ea0 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 76  arameters is rev
16eb0 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69  ersed from snpri
16ec0 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69  ntf().)^  This i
16ed0 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63  s an.** historic
16ee0 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61 74  al accident that
16ef0 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64   cannot be fixed
16f00 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
16f10 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63  g.** backwards c
16f20 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e  ompatibility.  ^
16f30 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20  (Note also that 
16f40 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
16f50 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20  ().** returns a 
16f60 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62  pointer to its b
16f70 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66  uffer instead of
16f80 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
16f90 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63 74  * characters act
16fa0 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e  ually written in
16fb0 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e  to the buffer.)^
16fc0 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a    We admit that.
16fd0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
16fe0 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69 74   characters writ
16ff0 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d  ten would be a m
17000 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75 72  ore useful retur
17010 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77  n.** value but w
17020 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20  e cannot change 
17030 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
17040 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e  on of sqlite3_sn
17050 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20  printf().** now 
17060 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67  without breaking
17070 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
17080 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61  **.** ^As long a
17090 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69 7a  s the buffer siz
170a0 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61  e is greater tha
170b0 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f  n zero, sqlite3_
170c0 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75  snprintf().** gu
170d0 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
170e0 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 61  e buffer is alwa
170f0 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  ys zero-terminat
17100 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a  ed.  ^The first.
17110 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22  ** parameter "n"
17120 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69   is the total si
17130 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  ze of the buffer
17140 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63  , including spac
17150 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72  e for.** the zer
17160 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53  o terminator.  S
17170 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74  o the longest st
17180 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65  ring that can be
17190 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77   completely.** w
171a0 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e  ritten will be n
171b0 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  -1 characters..*
171c0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
171d0 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 72 6f  3_vsnprintf() ro
171e0 75 74 69 6e 65 20 69 73 20 61 20 76 61 72 61 72  utine is a varar
171f0 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 71  gs version of sq
17200 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
17210 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
17220 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65  utines all imple
17230 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69  ment some additi
17240 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a  onal formatting.
17250 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20  ** options that 
17260 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63  are useful for c
17270 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20  onstructing SQL 
17280 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41  statements..** A
17290 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20  ll of the usual 
172a0 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74  printf() formatt
172b0 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c  ing options appl
172c0 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c  y.  In addition,
172d0 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65   there.** is are
172e0 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64   "%q", "%Q", and
172f0 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a   "%z" options..*
17300 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f 70  *.** ^(The %q op
17310 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
17320 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 73 75  %s in that it su
17330 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c 6c  bstitutes a null
17340 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73  -terminated.** s
17350 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61  tring from the a
17360 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42  rgument list.  B
17370 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c  ut %q also doubl
17380 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 68  es every '\'' ch
17390 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69  aracter..** %q i
173a0 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75  s designed for u
173b0 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 69  se inside a stri
173c0 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42  ng literal.)^  B
173d0 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20  y doubling each 
173e0 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65  '\''.** characte
173f0 72 20 69 74 20 65 73 63 61 70 65 73 20 74 68 61  r it escapes tha
17400 74 20 63 68 61 72 61 63 74 65 72 20 61 6e 64 20  t character and 
17410 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20  allows it to be 
17420 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a  inserted into.**
17430 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a   the string..**.
17440 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  ** For example, 
17450 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e  assume the strin
17460 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74  g variable zText
17470 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61   contains text a
17480 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
17490 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
174a0 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65  e>.**  char *zTe
174b0 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 61 70  xt = "It's a hap
174c0 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70  py day!";.** </p
174d0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
174e0 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75  .**.** One can u
174f0 73 65 20 74 68 69 73 20 74 65 78 74 20 69 6e 20  se this text in 
17500 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
17510 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
17520 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
17530 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
17540 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70  SQL = sqlite3_mp
17550 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e  rintf("INSERT IN
17560 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28  TO table VALUES(
17570 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a  '%q')", zText);.
17580 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63  **  sqlite3_exec
17590 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c  (db, zSQL, 0, 0,
175a0 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33   0);.**  sqlite3
175b0 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20  _free(zSQL);.** 
175c0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
175d0 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73  te>.**.** Becaus
175e0 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20  e the %q format 
175f0 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20  string is used, 
17600 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 63 74  the '\'' charact
17610 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69  er in zText.** i
17620 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 74 68  s escaped and th
17630 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20  e SQL generated 
17640 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  is as follows:.*
17650 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
17660 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52  ><pre>.**  INSER
17670 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41  T INTO table1 VA
17680 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 68 61  LUES('It''s a ha
17690 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f  ppy day!').** </
176a0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
176b0 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20  >.**.** This is 
176c0 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77 65  correct.  Had we
176d0 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 61 64   used %s instead
176e0 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65   of %q, the gene
176f0 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75  rated SQL.** wou
17700 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c  ld have looked l
17710 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20  ike this:.**.** 
17720 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
17730 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54  >.**  INSERT INT
17740 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28  O table1 VALUES(
17750 27 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61  'It's a happy da
17760 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  y!');.** </pre><
17770 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
17780 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65  ** This second e
17790 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c  xample is an SQL
177a0 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20   syntax error.  
177b0 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c  As a general rul
177c0 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20  e you should.** 
177d0 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 69 6e  always use %q in
177e0 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e  stead of %s when
177f0 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20   inserting text 
17800 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69  into a string li
17810 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  teral..**.** ^(T
17820 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72  he %Q option wor
17830 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70  ks like %q excep
17840 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73  t it also adds s
17850 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f  ingle quotes aro
17860 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69  und.** the outsi
17870 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20  de of the total 
17880 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f  string.  Additio
17890 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61  nally, if the pa
178a0 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a  rameter in the.*
178b0 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20  * argument list 
178c0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
178d0 72 2c 20 25 51 20 73 75 62 73 74 69 74 75 74 65  r, %Q substitute
178e0 73 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c  s the text "NULL
178f0 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69  " (without.** si
17900 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e 20  ngle quotes).)^ 
17910 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65   So, for example
17920 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a  , one could say:
17930 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
17940 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
17950 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65  r *zSQL = sqlite
17960 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52  3_mprintf("INSER
17970 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c  T INTO table VAL
17980 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29  UES(%Q)", zText)
17990 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78  ;.**  sqlite3_ex
179a0 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20  ec(db, zSQL, 0, 
179b0 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  0, 0);.**  sqlit
179c0 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a  e3_free(zSQL);.*
179d0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
179e0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  uote>.**.** The 
179f0 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20  code above will 
17a00 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74  render a correct
17a10 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
17a20 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61  n the zSQL.** va
17a30 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74  riable even if t
17a40 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c  he zText variabl
17a50 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  e is a NULL poin
17a60 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ter..**.** ^(The
17a70 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67   "%z" formatting
17a80 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
17a90 6b 65 20 22 25 73 22 20 62 75 74 20 77 69 74 68  ke "%s" but with
17aa0 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   the.** addition
17ab0 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65 20   that after the 
17ac0 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20  string has been 
17ad0 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20  read and copied 
17ae0 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75  into.** the resu
17af0 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  lt, [sqlite3_fre
17b00 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f  e()] is called o
17b10 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  n the input stri
17b20 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73  ng.)^.*/.char *s
17b30 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63  qlite3_mprintf(c
17b40 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b  onst char*,...);
17b50 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76  .char *sqlite3_v
17b60 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
17b70 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63  ar*, va_list);.c
17b80 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70  har *sqlite3_snp
17b90 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c  rintf(int,char*,
17ba0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e  const char*, ...
17bb0 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
17bc0 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63  _vsnprintf(int,c
17bd0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
17be0 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a  , va_list);../*.
17bf0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
17c00 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53  ory Allocation S
17c10 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54  ubsystem.**.** T
17c20 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75  he SQLite core u
17c30 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65 20  ses these three 
17c40 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c  routines for all
17c50 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69   of its own.** i
17c60 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61  nternal memory a
17c70 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
17c80 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70   "Core" in the p
17c90 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65  revious sentence
17ca0 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  .** does not inc
17cb0 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73  lude operating-s
17cc0 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 56  ystem specific V
17cd0 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
17ce0 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f  n.  The.** Windo
17cf0 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 69  ws VFS uses nati
17d00 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  ve malloc() and 
17d10 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20  free() for some 
17d20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  operations..**.*
17d30 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  * ^The sqlite3_m
17d40 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20  alloc() routine 
17d50 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
17d60 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20  r to a block.** 
17d70 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61  of memory at lea
17d80 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65  st N bytes in le
17d90 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73  ngth, where N is
17da0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
17db0 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d  ** ^If sqlite3_m
17dc0 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c  alloc() is unabl
17dd0 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66  e to obtain suff
17de0 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d  icient free.** m
17df0 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e  emory, it return
17e00 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
17e10 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d  .  ^If the param
17e20 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c  eter N to.** sql
17e30 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73  ite3_malloc() is
17e40 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76   zero or negativ
17e50 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d  e then sqlite3_m
17e60 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a  alloc() returns.
17e70 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
17e80 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  r..**.** ^Callin
17e90 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  g sqlite3_free()
17ea0 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20   with a pointer 
17eb0 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72  previously retur
17ec0 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  ned.** by sqlite
17ed0 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71  3_malloc() or sq
17ee0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
17ef0 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65  releases that me
17f00 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20  mory so.** that 
17f10 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73  it might be reus
17f20 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ed.  ^The sqlite
17f30 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65  3_free() routine
17f40 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69   is.** a no-op i
17f50 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  f is called with
17f60 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
17f70 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c    Passing a NULL
17f80 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73   pointer.** to s
17f90 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73  qlite3_free() is
17fa0 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65   harmless.  Afte
17fb0 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d  r being freed, m
17fc0 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20  emory.** should 
17fd0 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64 20  neither be read 
17fe0 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76  nor written.  Ev
17ff0 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 69  en reading previ
18000 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d  ously freed.** m
18010 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75  emory might resu
18020 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61  lt in a segmenta
18030 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74  tion fault or ot
18040 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72  her severe error
18050 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72  ..** Memory corr
18060 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e  uption, a segmen
18070 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72  tation fault, or
18080 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72   other severe er
18090 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73  ror.** might res
180a0 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66  ult if sqlite3_f
180b0 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20  ree() is called 
180c0 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  with a non-NULL 
180d0 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20  pointer that.** 
180e0 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64  was not obtained
180f0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61   from sqlite3_ma
18100 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65  lloc() or sqlite
18110 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a  3_realloc()..**.
18120 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33  ** ^(The sqlite3
18130 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72  _realloc() inter
18140 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
18150 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69   resize a.** pri
18160 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  or memory alloca
18170 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65  tion to be at le
18180 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65  ast N bytes, whe
18190 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73  re N is the.** s
181a0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  econd parameter.
181b0 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c    The memory all
181c0 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65  ocation to be re
181d0 73 69 7a 65 64 20 69 73 20 74 68 65 20 66 69 72  sized is the fir
181e0 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e  st.** parameter.
181f0 29 5e 20 5e 20 49 66 20 74 68 65 20 66 69 72 73  )^ ^ If the firs
18200 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
18210 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
18220 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  .** is a NULL po
18230 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62  inter then its b
18240 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74  ehavior is ident
18250 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a  ical to calling.
18260 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
18270 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69 73 20  c(N) where N is 
18280 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
18290 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
182a0 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 49  realloc()..** ^I
182b0 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  f the second par
182c0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
182d0 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a  3_realloc() is z
182e0 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69  ero or.** negati
182f0 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ve then the beha
18300 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20  vior is exactly 
18310 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c  the same as call
18320 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66  ing.** sqlite3_f
18330 72 65 65 28 50 29 20 77 68 65 72 65 20 50 20 69  ree(P) where P i
18340 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  s the first para
18350 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
18360 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e  _realloc()..** ^
18370 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
18380 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  ) returns a poin
18390 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20  ter to a memory 
183a0 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66  allocation.** of
183b0 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
183c0 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c  s in size or NUL
183d0 4c 20 69 66 20 73 75 66 66 69 63 69 65 6e 74 20  L if sufficient 
183e0 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 61 69  memory is unavai
183f0 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20  lable..** ^If M 
18400 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  is the size of t
18410 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
18420 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c  ion, then min(N,
18430 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74  M) bytes.** of t
18440 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
18450 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69  ion are copied i
18460 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e  nto the beginnin
18470 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75  g of buffer retu
18480 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
18490 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64  e3_realloc() and
184a0 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
184b0 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a  ation is freed..
184c0 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72  ** ^If sqlite3_r
184d0 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73  ealloc() returns
184e0 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20   NULL, then the 
184f0 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
18500 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 65 64  .** is not freed
18510 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d  ..**.** ^The mem
18520 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 20  ory returned by 
18530 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
18540 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61   and sqlite3_rea
18550 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77  lloc().** is alw
18560 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  ays aligned to a
18570 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74  t least an 8 byt
18580 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74  e boundary, or t
18590 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f  o a.** 4 byte bo
185a0 75 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b 53  undary if the [S
185b0 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49  QLITE_4_BYTE_ALI
185c0 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d  GNED_MALLOC] com
185d0 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74  pile-time.** opt
185e0 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  ion is used..**.
185f0 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72  ** In SQLite ver
18600 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33  sion 3.5.0 and 3
18610 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73  .5.1, it was pos
18620 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a  sible to define.
18630 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d  ** the SQLITE_OM
18640 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41  IT_MEMORY_ALLOCA
18650 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64  TION which would
18660 20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74   cause the built
18670 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  -in.** implement
18680 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72  ation of these r
18690 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d  outines to be om
186a0 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70  itted.  That cap
186b0 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f  ability.** is no
186c0 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64   longer provided
186d0 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e  .  Only built-in
186e0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
186f0 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a  rs can be used..
18700 2a 2a 0a 2a 2a 20 54 68 65 20 57 69 6e 64 6f 77  **.** The Window
18710 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c  s OS interface l
18720 61 79 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68  ayer calls.** th
18730 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28  e system malloc(
18740 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72  ) and free() dir
18750 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65  ectly when conve
18760 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d  rting.** filenam
18770 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55  es between the U
18780 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73  TF-8 encoding us
18790 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ed by SQLite.** 
187a0 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c  and whatever fil
187b0 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69  ename encoding i
187c0 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61  s used by the pa
187d0 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73  rticular Windows
187e0 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e  .** installation
187f0 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  .  Memory alloca
18800 74 69 6f 6e 20 65 72 72 6f 72 73 20 61 72 65 20  tion errors are 
18810 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a  detected, but.**
18820 20 74 68 65 79 20 61 72 65 20 72 65 70 6f 72 74   they are report
18830 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49  ed back as [SQLI
18840 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a  TE_CANTOPEN] or.
18850 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  ** [SQLITE_IOERR
18860 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53  ] rather than [S
18870 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a  QLITE_NOMEM]..**
18880 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20  .** The pointer 
18890 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71  arguments to [sq
188a0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e  lite3_free()] an
188b0 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d [sqlite3_reall
188c0 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65  oc()].** must be
188d0 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20   either NULL or 
188e0 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62  else pointers ob
188f0 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72  tained from a pr
18900 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f  ior.** invocatio
18910 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  n of [sqlite3_ma
18920 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69  lloc()] or [sqli
18930 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74  te3_realloc()] t
18940 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20  hat have.** not 
18950 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65  yet been release
18960 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70  d..**.** The app
18970 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
18980 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20  t read or write 
18990 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61  any part of.** a
189a0 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79   block of memory
189b0 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65   after it has be
189c0 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e  en released usin
189d0 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  g.** [sqlite3_fr
189e0 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ee()] or [sqlite
189f0 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f  3_realloc()]..*/
18a00 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d  .void *sqlite3_m
18a10 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64  alloc(int);.void
18a20 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   *sqlite3_reallo
18a30 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76  c(void*, int);.v
18a40 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65  oid sqlite3_free
18a50 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  (void*);../*.** 
18a60 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
18a70 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69   Allocator Stati
18a80 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  stics.**.** SQLi
18a90 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65 73  te provides thes
18aa0 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73  e two interfaces
18ab0 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f   for reporting o
18ac0 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20  n the status.** 
18ad0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
18ae0 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69  malloc()], [sqli
18af0 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64  te3_free()], and
18b00 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
18b10 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  c()].** routines
18b20 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65  , which form the
18b30 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79   built-in memory
18b40 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73   allocation subs
18b50 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ystem..**.** ^Th
18b60 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  e [sqlite3_memor
18b70 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e  y_used()] routin
18b80 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
18b90 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a  mber of bytes.**
18ba0 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65   of memory curre
18bb0 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67  ntly outstanding
18bc0 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e   (malloced but n
18bd0 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54  ot freed)..** ^T
18be0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
18bf0 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
18c00 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
18c10 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76  the maximum.** v
18c20 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33  alue of [sqlite3
18c30 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
18c40 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77  since the high-w
18c50 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73  ater mark.** was
18c60 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54   last reset.  ^T
18c70 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
18c80 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d  ed by [sqlite3_m
18c90 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e  emory_used()] an
18ca0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  d.** [sqlite3_me
18cb0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
18cc0 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76  ] include any ov
18cd0 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20  erhead.** added 
18ce0 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73  by SQLite in its
18cf0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
18d00 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  of [sqlite3_mall
18d10 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f  oc()],.** but no
18d20 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 65 64  t overhead added
18d30 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65   by the any unde
18d40 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69  rlying system li
18d50 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65  brary.** routine
18d60 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  s that [sqlite3_
18d70 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61  malloc()] may ca
18d80 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d  ll..**.** ^The m
18d90 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72  emory high-water
18da0 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20 74   mark is reset t
18db0 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61  o the current va
18dc0 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74  lue of.** [sqlit
18dd0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
18de0 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  ] if and only if
18df0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 74   the parameter t
18e00 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  o.** [sqlite3_me
18e10 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
18e20 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65  ] is true.  ^The
18e30 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a   value returned.
18e40 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d  ** by [sqlite3_m
18e50 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
18e60 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d  1)] is the high-
18e70 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72  water mark.** pr
18e80 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 74  ior to the reset
18e90 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74  ..*/.sqlite3_int
18ea0 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  64 sqlite3_memor
18eb0 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71  y_used(void);.sq
18ec0 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
18ed0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
18ee0 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c  ater(int resetFl
18ef0 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ag);../*.** CAPI
18f00 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e  3REF: Pseudo-Ran
18f10 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72  dom Number Gener
18f20 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ator.**.** SQLit
18f30 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67  e contains a hig
18f40 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f  h-quality pseudo
18f50 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67  -random number g
18f60 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20  enerator (PRNG) 
18f70 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63  used to.** selec
18f80 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20  t random [ROWID 
18f90 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69  | ROWIDs] when i
18fa0 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63  nserting new rec
18fb0 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c  ords into a tabl
18fc0 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64  e that.** alread
18fd0 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65  y uses the large
18fe0 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57  st possible [ROW
18ff0 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69  ID].  The PRNG i
19000 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a  s also used for.
19010 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20  ** the build-in 
19020 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e  random() and ran
19030 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75  domblob() SQL fu
19040 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69  nctions.  This i
19050 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a  nterface allows.
19060 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** applications 
19070 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61  to access the sa
19080 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65  me PRNG for othe
19090 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a  r purposes..**.*
190a0 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69  * ^A call to thi
190b0 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73  s routine stores
190c0 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64   N bytes of rand
190d0 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66  omness into buff
190e0 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  er P..**.** ^The
190f0 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 69 73   first time this
19100 20 72 6f 75 74 69 6e 65 20 69 73 20 69 6e 76 6f   routine is invo
19110 6b 65 64 20 28 65 69 74 68 65 72 20 69 6e 74 65  ked (either inte
19120 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20  rnally or by.** 
19130 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29  the application)
19140 20 74 68 65 20 50 52 4e 47 20 69 73 20 73 65 65   the PRNG is see
19150 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d  ded using random
19160 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  ness obtained.**
19170 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f   from the xRando
19180 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20  mness method of 
19190 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
191a0 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
191b0 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73 75 62  ..** ^On all sub
191c0 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69  sequent invocati
191d0 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64 6f 2d  ons, the pseudo-
191e0 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65  randomness is ge
191f0 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72  nerated.** inter
19200 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75  nally and withou
19210 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68  t recourse to th
19220 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  e [sqlite3_vfs] 
19230 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d  xRandomness.** m
19240 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73  ethod..*/.void s
19250 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73  qlite3_randomnes
19260 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50  s(int N, void *P
19270 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
19280 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65  EF: Compile-Time
19290 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43   Authorization C
192a0 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e  allbacks.**.** ^
192b0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67  This routine reg
192c0 69 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72  isters an author
192d0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69  izer callback wi
192e0 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  th a particular.
192f0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
19300 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69  nection], suppli
19310 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ed in the first 
19320 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  argument..** ^Th
19330 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
19340 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
19350 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   as SQL statemen
19360 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d  ts are being com
19370 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c  piled.** by [sql
19380 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
19390 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20  or its variants 
193a0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
193b0 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  _v2()],.** [sqli
193c0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
193d0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
193e0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20  epare16_v2()].  
193f0 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70  ^At various.** p
19400 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65  oints during the
19410 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f   compilation pro
19420 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69  cess, as logic i
19430 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a  s being created.
19440 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61  ** to perform va
19450 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74  rious actions, t
19460 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
19470 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
19480 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74  d to.** see if t
19490 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65  hose actions are
194a0 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20   allowed.  ^The 
194b0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
194c0 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65  ack should.** re
194d0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
194e0 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63   to allow the ac
194f0 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47  tion, [SQLITE_IG
19500 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f  NORE] to disallo
19510 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69  w the.** specifi
19520 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c  c action but all
19530 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  ow the SQL state
19540 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65  ment to continue
19550 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c   to be.** compil
19560 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  ed, or [SQLITE_D
19570 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68  ENY] to cause th
19580 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61  e entire SQL sta
19590 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20  tement to be.** 
195a0 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e  rejected with an
195b0 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65   error.  ^If the
195c0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
195d0 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20  back returns.** 
195e0 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20  any value other 
195f0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e  than [SQLITE_IGN
19600 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b  ORE], [SQLITE_OK
19610 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45  ], or [SQLITE_DE
19620 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  NY].** then the 
19630 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
19640 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61  _v2()] or equiva
19650 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74  lent call that t
19660 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20  riggered.** the 
19670 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20  authorizer will 
19680 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72  fail with an err
19690 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a  or message..**.*
196a0 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  * When the callb
196b0 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
196c0 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65  ITE_OK], that me
196d0 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f  ans the operatio
196e0 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69  n.** requested i
196f0 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65  s ok.  ^When the
19700 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
19710 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c  s [SQLITE_DENY],
19720 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
19730 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
19740 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c  r equivalent cal
19750 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
19760 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
19770 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74  er will fail wit
19780 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  h an error messa
19790 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68  ge explaining th
197a0 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20  at.** access is 
197b0 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e  denied. .**.** ^
197c0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
197d0 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ter to the autho
197e0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
197f0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
19800 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74  third.** paramet
19810 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
19820 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
19830 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54  () interface. ^T
19840 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
19850 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61  ter.** to the ca
19860 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74  llback is an int
19870 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50  eger [SQLITE_COP
19880 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d  Y | action code]
19890 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a   that specifies.
198a0 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  ** the particula
198b0 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  r action to be a
198c0 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20  uthorized. ^The 
198d0 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69  third through si
198e0 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  xth parameters.*
198f0 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  * to the callbac
19900 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69  k are zero-termi
19910 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68  nated strings th
19920 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74  at contain addit
19930 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73  ional.** details
19940 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f   about the actio
19950 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a  n to be authoriz
19960 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
19970 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73  e action code is
19980 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a   [SQLITE_READ].*
19990 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61  * and the callba
199a0 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
199b0 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20  TE_IGNORE] then 
199c0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
199d0 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74   statement] stat
199e0 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75  ement is constru
199f0 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 74 75  cted to substitu
19a00 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c  te.** a NULL val
19a10 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74  ue in place of t
19a20 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  he table column 
19a30 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a  that would have.
19a40 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 20  ** been read if 
19a50 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20  [SQLITE_OK] had 
19a60 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20  been returned.  
19a70 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  The [SQLITE_IGNO
19a80 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61  RE].** return ca
19a90 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e  n be used to den
19aa0 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75  y an untrusted u
19ab0 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e  ser access to in
19ac0 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75  dividual.** colu
19ad0 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a  mns of a table..
19ae0 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f  ** ^If the actio
19af0 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54  n code is [SQLIT
19b00 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68  E_DELETE] and th
19b10 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
19b20 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47  ns.** [SQLITE_IG
19b30 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b  NORE] then the [
19b40 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f  DELETE] operatio
19b50 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 20 74  n proceeds but t
19b60 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20  he.** [truncate 
19b70 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73  optimization] is
19b80 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c   disabled and al
19b90 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74  l rows are delet
19ba0 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e  ed individually.
19bb0 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72  .**.** An author
19bc0 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65  izer is used whe
19bd0 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
19be0 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a  re | preparing].
19bf0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
19c00 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73  s from an untrus
19c10 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65  ted source, to e
19c20 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53  nsure that the S
19c30 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
19c40 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61   do not try to a
19c50 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20  ccess data they 
19c60 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20  are not allowed 
19c70 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20  to see, or that 
19c80 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74  they do not.** t
19c90 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61  ry to execute ma
19ca0 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e  licious statemen
19cb0 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74  ts that damage t
19cc0 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f  he database.  Fo
19cd0 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e  r.** example, an
19ce0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79   application may
19cf0 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f   allow a user to
19d00 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79   enter arbitrary
19d10 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20  .** SQL queries 
19d20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62  for evaluation b
19d30 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42  y a database.  B
19d40 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ut the applicati
19d50 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77  on does.** not w
19d60 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20  ant the user to 
19d70 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20  be able to make 
19d80 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65  arbitrary change
19d90 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61  s to the.** data
19da0 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72  base.  An author
19db0 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20  izer could then 
19dc0 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20  be put in place 
19dd0 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65  while the.** use
19de0 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73  r-entered SQL is
19df0 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   being [sqlite3_
19e00 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72  prepare | prepar
19e10 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61  ed] that.** disa
19e20 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67  llows everything
19e30 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d   except [SELECT]
19e40 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
19e50 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
19e60 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f  that need to pro
19e70 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e  cess SQL from un
19e80 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a  trusted sources.
19e90 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f  ** might also co
19ea0 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20  nsider lowering 
19eb0 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20  resource limits 
19ec0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c  using [sqlite3_l
19ed0 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c  imit()].** and l
19ee0 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65  imiting database
19ef0 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20   size using the 
19f00 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d  [max_page_count]
19f10 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20   [PRAGMA].** in 
19f20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e  addition to usin
19f30 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e  g an authorizer.
19f40 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20  .**.** ^(Only a 
19f50 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65  single authorize
19f60 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63  r can be in plac
19f70 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20  e on a database 
19f80 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74  connection.** at
19f90 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63   a time.  Each c
19fa0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
19fb0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76  et_authorizer ov
19fc0 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70  errides the.** p
19fd0 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20  revious call.)^ 
19fe0 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61 75   ^Disable the au
19ff0 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74  thorizer by inst
1a000 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61  alling a NULL ca
1a010 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61  llback..** The a
1a020 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73  uthorizer is dis
1a030 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
1a040 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68  ..**.** The auth
1a050 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1a060 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
1a070 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
1a080 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
1a090 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1a0a0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
1a0b0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1a0c0 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74  lback..** Note t
1a0d0 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hat [sqlite3_pre
1a0e0 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
1a0f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1a100 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69  both modify thei
1a110 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
1a120 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68  nnections for th
1a130 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f  e meaning of "mo
1a140 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61  dify" in this pa
1a150 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e  ragraph..**.** ^
1a160 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  When [sqlite3_pr
1a170 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75  epare_v2()] is u
1a180 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 61  sed to prepare a
1a190 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a   statement, the.
1a1a0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67  ** statement mig
1a1b0 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 72 65  ht be re-prepare
1a1c0 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65  d during [sqlite
1a1d0 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f  3_step()] due to
1a1e0 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68   a .** schema ch
1a1f0 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68  ange.  Hence, th
1a200 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
1a210 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74  ould ensure that
1a220 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20   the.** correct 
1a230 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1a240 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70  ack remains in p
1a250 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20  lace during the 
1a260 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1a270 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68  ..**.** ^Note th
1a280 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  at the authorize
1a290 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
1a2a0 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e  voked only durin
1a2b0 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  g.** [sqlite3_pr
1a2c0 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20  epare()] or its 
1a2d0 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f  variants.  Autho
1a2e0 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a  rization is not.
1a2f0 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72  ** performed dur
1a300 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76  ing statement ev
1a310 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c  aluation in [sql
1a320 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e  ite3_step()], un
1a330 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65  less.** as state
1a340 64 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75  d in the previou
1a350 73 20 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c  s paragraph, sql
1a360 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f  ite3_step() invo
1a370 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70  kes.** sqlite3_p
1a380 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72  repare_v2() to r
1a390 65 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65  eprepare a state
1a3a0 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73 63 68  ment after a sch
1a3b0 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69  ema change..*/.i
1a3c0 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  nt sqlite3_set_a
1a3d0 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c  uthorizer(.  sql
1a3e0 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78  ite3*,.  int (*x
1a3f0 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  Auth)(void*,int,
1a400 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
1a410 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
1a420 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  ar*,const char*)
1a430 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44  ,.  void *pUserD
1a440 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ata.);../*.** CA
1a450 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a  PI3REF: Authoriz
1a460 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a  er Return Codes.
1a470 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  **.** The [sqlit
1a480 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1a490 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63  r | authorizer c
1a4a0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1a4b0 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e  ] must.** return
1a4c0 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
1a4d0 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68  OK] or one of th
1a4e0 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74  ese two constant
1a4f0 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f  s in order.** to
1a500 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77   signal SQLite w
1a510 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
1a520 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d  e action is perm
1a530 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a  itted.  See the.
1a540 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  ** [sqlite3_set_
1a550 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
1a560 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74  horizer document
1a570 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74  ation] for addit
1a580 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61  ional.** informa
1a590 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  tion..**.** Note
1a5a0 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49 47 4e   that SQLITE_IGN
1a5b0 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73 65 64  ORE is also used
1a5c0 20 61 73 20 61 20 5b 53 51 4c 49 54 45 5f 52 4f   as a [SQLITE_RO
1a5d0 4c 4c 42 41 43 4b 20 7c 20 72 65 74 75 72 6e 20  LLBACK | return 
1a5e0 63 6f 64 65 5d 0a 2a 2a 20 66 72 6f 6d 20 74 68  code].** from th
1a5f0 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  e [sqlite3_vtab_
1a600 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69  on_conflict()] i
1a610 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65  nterface..*/.#de
1a620 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59  fine SQLITE_DENY
1a630 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20     1   /* Abort 
1a640 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
1a650 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  t with an error 
1a660 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1a670 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20  E_IGNORE 2   /* 
1a680 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65  Don't allow acce
1a690 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65  ss, but don't ge
1a6a0 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20  nerate an error 
1a6b0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
1a6c0 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41  EF: Authorizer A
1a6d0 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a  ction Codes.**.*
1a6e0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  * The [sqlite3_s
1a6f0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d  et_authorizer()]
1a700 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
1a710 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  ters a callback 
1a720 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74  function.** that
1a730 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61   is invoked to a
1a740 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e  uthorize certain
1a750 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
1a760 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20  ctions.  The.** 
1a770 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1a780 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
1a790 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63   is an integer c
1a7a0 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69  ode that specifi
1a7b0 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f  es.** what actio
1a7c0 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f  n is being autho
1a7d0 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72  rized.  These ar
1a7e0 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63  e the integer ac
1a7f0 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a  tion codes that.
1a800 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ** the authorize
1a810 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62  r callback may b
1a820 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  e passed..**.** 
1a830 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64  These action cod
1a840 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79  e values signify
1a850 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70   what kind of op
1a860 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65  eration is to be
1a870 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20  .** authorized. 
1a880 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68   The 3rd and 4th
1a890 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74   parameters to t
1a8a0 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e  he authorization
1a8b0 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  .** callback fun
1a8c0 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61  ction will be pa
1a8d0 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c  rameters or NULL
1a8e0 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68   depending on wh
1a8f0 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  ich of these.** 
1a900 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73  codes is used as
1a910 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
1a920 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74  meter.  ^(The 5t
1a930 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
1a940 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72  he.** authorizer
1a950 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65   callback is the
1a960 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
1a970 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22  abase ("main", "
1a980 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20  temp",.** etc.) 
1a990 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e  if applicable.)^
1a9a0 20 20 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d    ^The 6th param
1a9b0 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
1a9c0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a  orizer callback.
1a9d0 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ** is the name o
1a9e0 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74  f the inner-most
1a9f0 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77   trigger or view
1aa00 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73   that is respons
1aa10 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  ible for.** the 
1aa20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f  access attempt o
1aa30 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61  r NULL if this a
1aa40 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73  ccess attempt is
1aa50 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a   directly from.*
1aa60 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20  * top-level SQL 
1aa70 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a  code..*/./******
1aa80 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1aa90 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1aaa0 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a  ***** 3rd ******
1aab0 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a  ****** 4th *****
1aac0 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20  ******/.#define 
1aad0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e  SQLITE_CREATE_IN
1aae0 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20  DEX          1  
1aaf0 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
1ab00 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1ab10 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1ab20 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42  QLITE_CREATE_TAB
1ab30 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20  LE          2   
1ab40 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1ab50 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1ab60 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1ab70 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
1ab80 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f  _INDEX     3   /
1ab90 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
1aba0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1abb0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1abc0 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
1abd0 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a  TABLE     4   /*
1abe0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1abf0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1ac00 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1ac10 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54  TE_CREATE_TEMP_T
1ac20 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20  RIGGER   5   /* 
1ac30 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
1ac40 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1ac50 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1ac60 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49  E_CREATE_TEMP_VI
1ac70 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56  EW      6   /* V
1ac80 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
1ac90 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1aca0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1acb0 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20  _CREATE_TRIGGER 
1acc0 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72         7   /* Tr
1acd0 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
1ace0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1acf0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1ad00 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20  CREATE_VIEW     
1ad10 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65        8   /* Vie
1ad20 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
1ad30 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1ad40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1ad50 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20  ELETE           
1ad60 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c       9   /* Tabl
1ad70 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1ad80 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1ad90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1ada0 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  OP_INDEX        
1adb0 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78     10   /* Index
1adc0 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
1add0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1ade0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1adf0 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  P_TABLE         
1ae00 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20    11   /* Table 
1ae10 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1ae20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1ae30 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1ae40 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
1ae50 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   12   /* Index N
1ae60 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
1ae70 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1ae80 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1ae90 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20  TEMP_TABLE      
1aea0 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  13   /* Table Na
1aeb0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1aec0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1aed0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
1aee0 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31  EMP_TRIGGER    1
1aef0 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  4   /* Trigger N
1af00 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
1af10 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1af20 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
1af30 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35  MP_VIEW       15
1af40 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
1af50 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1af60 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1af70 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49   SQLITE_DROP_TRI
1af80 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20  GGER         16 
1af90 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
1afa0 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
1afb0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1afc0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57  SQLITE_DROP_VIEW
1afd0 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20              17  
1afe0 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
1aff0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1b000 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1b010 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20  QLITE_INSERT    
1b020 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20             18   
1b030 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1b040 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1b050 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1b060 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20  LITE_PRAGMA     
1b070 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f            19   /
1b080 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20  * Pragma Name   
1b090 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c    1st arg or NUL
1b0a0 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  L */.#define SQL
1b0b0 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20  ITE_READ        
1b0c0 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a           20   /*
1b0d0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1b0e0 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
1b0f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1b100 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20  TE_SELECT       
1b110 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20          21   /* 
1b120 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1b130 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1b140 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1b150 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20  E_TRANSACTION   
1b160 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f         22   /* O
1b170 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e  peration       N
1b180 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1b190 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1b1a0 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20  _UPDATE         
1b1b0 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61        23   /* Ta
1b1c0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f  ble Name      Co
1b1d0 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f  lumn Name     */
1b1e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1b1f0 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20  ATTACH          
1b200 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c       24   /* Fil
1b210 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c  ename        NUL
1b220 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1b230 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1b240 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20  ETACH           
1b250 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61      25   /* Data
1b260 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c  base Name   NULL
1b270 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1b280 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c  define SQLITE_AL
1b290 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20  TER_TABLE       
1b2a0 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62     26   /* Datab
1b2b0 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65  ase Name   Table
1b2c0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1b2d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49  efine SQLITE_REI
1b2e0 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20  NDEX            
1b2f0 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20    27   /* Index 
1b300 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1b310 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1b320 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c  fine SQLITE_ANAL
1b330 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  YZE             
1b340 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   28   /* Table N
1b350 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1b360 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1b370 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1b380 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  E_VTABLE        
1b390 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  29   /* Table Na
1b3a0 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e  me      Module N
1b3b0 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
1b3c0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
1b3d0 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33  TABLE          3
1b3e0 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  0   /* Table Nam
1b3f0 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61  e      Module Na
1b400 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
1b410 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f  e SQLITE_FUNCTIO
1b420 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31  N             31
1b430 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
1b440 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e        Function N
1b450 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  ame   */.#define
1b460 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e   SQLITE_SAVEPOIN
1b470 54 20 20 20 20 20 20 20 20 20 20 20 20 33 32 20  T            32 
1b480 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20    /* Operation  
1b490 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e       Savepoint N
1b4a0 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ame  */.#define 
1b4b0 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20  SQLITE_COPY     
1b4c0 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20               0  
1b4d0 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73   /* No longer us
1b4e0 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ed */../*.** CAP
1b4f0 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41  I3REF: Tracing A
1b500 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e  nd Profiling Fun
1b510 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ctions.**.** The
1b520 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69  se routines regi
1b530 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  ster callback fu
1b540 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e  nctions that can
1b550 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20   be used for.** 
1b560 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66  tracing and prof
1b570 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74  iling the execut
1b580 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65  ion of SQL state
1b590 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
1b5a0 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
1b5b0 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
1b5c0 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  y sqlite3_trace(
1b5d0 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a  ) is invoked at.
1b5e0 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73  ** various times
1b5f0 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61   when an SQL sta
1b600 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20  tement is being 
1b610 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  run by [sqlite3_
1b620 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65  step()]..** ^The
1b630 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
1b640 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
1b650 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 46 2d  oked with a UTF-
1b660 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  8 rendering of t
1b670 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  he.** SQL statem
1b680 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 65 20  ent text as the 
1b690 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20  statement first 
1b6a0 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67  begins executing
1b6b0 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61  ..** ^(Additiona
1b6c0 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  l sqlite3_trace(
1b6d0 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68  ) callbacks migh
1b6e0 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61  t occur.** as ea
1b6f0 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75 62  ch triggered sub
1b700 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72  program is enter
1b710 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63  ed.  The callbac
1b720 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a  ks for triggers.
1b730 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46  ** contain a UTF
1b740 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74  -8 SQL comment t
1b750 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 74  hat identifies t
1b760 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a  he trigger.)^.**
1b770 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63  .** ^The callbac
1b780 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
1b790 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
1b7a0 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e  _profile() is in
1b7b0 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68  voked.** as each
1b7c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66   SQL statement f
1b7d0 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70  inishes.  ^The p
1b7e0 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20  rofile callback 
1b7f0 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20  contains.** the 
1b800 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65  original stateme
1b810 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65  nt text and an e
1b820 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d  stimate of wall-
1b830 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66  clock time.** of
1b840 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73   how long that s
1b850 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f  tatement took to
1b860 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66   run.  ^The prof
1b870 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  ile callback.** 
1b880 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73  time is in units
1b890 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c   of nanoseconds,
1b8a0 20 68 6f 77 65 76 65 72 20 74 68 65 20 63 75 72   however the cur
1b8b0 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74  rent implementat
1b8c0 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63  ion.** is only c
1b8d0 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73  apable of millis
1b8e0 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e  econd resolution
1b8f0 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73   so the six leas
1b900 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a  t significant.**
1b910 20 64 69 67 69 74 73 20 69 6e 20 74 68 65 20 74   digits in the t
1b920 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c  ime are meaningl
1b930 65 73 73 2e 20 20 46 75 74 75 72 65 20 76 65 72  ess.  Future ver
1b940 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a  sions of SQLite.
1b950 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65  ** might provide
1b960 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74   greater resolut
1b970 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69  ion on the profi
1b980 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54  ler callback.  T
1b990 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72  he.** sqlite3_pr
1b9a0 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e  ofile() function
1b9b0 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65   is considered e
1b9c0 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20  xperimental and 
1b9d0 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f  is.** subject to
1b9e0 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72   change in futur
1b9f0 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
1ba00 4c 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  Lite..*/.void *s
1ba10 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c  qlite3_trace(sql
1ba20 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72  ite3*, void(*xTr
1ba30 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74  ace)(void*,const
1ba40 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b   char*), void*);
1ba50 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45  .SQLITE_EXPERIME
1ba60 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74  NTAL void *sqlit
1ba70 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74  e3_profile(sqlit
1ba80 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50  e3*,.   void(*xP
1ba90 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f  rofile)(void*,co
1baa0 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65  nst char*,sqlite
1bab0 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a  3_uint64), void*
1bac0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1bad0 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65  EF: Query Progre
1bae0 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a  ss Callbacks.**.
1baf0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1bb00 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
1bb10 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66  (D,N,X,P) interf
1bb20 61 63 65 20 63 61 75 73 65 73 20 74 68 65 20 63  ace causes the c
1bb30 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74  allback.** funct
1bb40 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f  ion X to be invo
1bb50 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79  ked periodically
1bb60 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e   during long run
1bb70 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ning calls to.**
1bb80 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
1bb90 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ], [sqlite3_step
1bba0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
1bbb0 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f  _get_table()] fo
1bbc0 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
1bbd0 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20  nnection D.  An 
1bbe0 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20  example use for 
1bbf0 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63  this.** interfac
1bc00 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47  e is to keep a G
1bc10 55 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e  UI updated durin
1bc20 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e  g a large query.
1bc30 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61  .**.** ^The para
1bc40 6d 65 74 65 72 20 50 20 69 73 20 70 61 73 73 65  meter P is passe
1bc50 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65  d through as the
1bc60 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20   only parameter 
1bc70 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62  to the .** callb
1bc80 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20  ack function X. 
1bc90 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20   ^The parameter 
1bca0 4e 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  N is the number 
1bcb0 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20  of .** [virtual 
1bcc0 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74  machine instruct
1bcd0 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65  ions] that are e
1bce0 76 61 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e  valuated between
1bcf0 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69   successive.** i
1bd00 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
1bd10 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 0a 2a 2a  e callback X..**
1bd20 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67  .** ^Only a sing
1bd30 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  le progress hand
1bd40 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66 69 6e  ler may be defin
1bd50 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 70  ed at one time p
1bd60 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  er.** [database 
1bd70 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74  connection]; set
1bd80 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 72  ting a new progr
1bd90 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6e 63  ess handler canc
1bda0 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f  els the.** old o
1bdb0 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 61  ne.  ^Setting pa
1bdc0 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 4c  rameter X to NUL
1bdd0 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 70  L disables the p
1bde0 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e  rogress handler.
1bdf0 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 73  .** ^The progres
1be00 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61 6c 73  s handler is als
1be10 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20 73 65  o disabled by se
1be20 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c  tting N to a val
1be30 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20  ue less.** than 
1be40 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  1..**.** ^If the
1be50 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
1be60 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
1be70 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69  ero, the operati
1be80 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75  on is.** interru
1be90 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 61 74  pted.  This feat
1bea0 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ure can be used 
1beb0 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a  to implement a.*
1bec0 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f  * "Cancel" butto
1bed0 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72  n on a GUI progr
1bee0 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a  ess dialog box..
1bef0 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65  **.** The progre
1bf00 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  ss handler callb
1bf10 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20  ack must not do 
1bf20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69  anything that wi
1bf30 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65  ll modify.** the
1bf40 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1bf50 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
1bf60 64 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68  d the progress h
1bf70 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20  andler..** Note 
1bf80 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72  that [sqlite3_pr
1bf90 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
1bfa0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1bfb0 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65   both modify the
1bfc0 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  ir.** database c
1bfd0 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74  onnections for t
1bfe0 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d  he meaning of "m
1bff0 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70  odify" in this p
1c000 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a  aragraph..**.*/.
1c010 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f  void sqlite3_pro
1c020 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71  gress_handler(sq
1c030 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74  lite3*, int, int
1c040 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64  (*)(void*), void
1c050 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1c060 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e  REF: Opening A N
1c070 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  ew Database Conn
1c080 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ection.**.** ^Th
1c090 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65  ese routines ope
1c0a0 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61  n an SQLite data
1c0b0 62 61 73 65 20 66 69 6c 65 20 61 73 20 73 70 65  base file as spe
1c0c0 63 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a  cified by the .*
1c0d0 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  * filename argum
1c0e0 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61  ent. ^The filena
1c0f0 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69  me argument is i
1c100 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54  nterpreted as UT
1c110 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  F-8 for.** sqlit
1c120 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
1c130 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
1c140 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  and as UTF-16 in
1c150 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
1c160 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71  .** order for sq
1c170 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20  lite3_open16(). 
1c180 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ^(A [database co
1c190 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
1c1a0 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72   is usually.** r
1c1b0 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62  eturned in *ppDb
1c1c0 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72  , even if an err
1c1d0 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20  or occurs.  The 
1c1e0 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69  only exception i
1c1f0 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c  s that.** if SQL
1c200 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ite is unable to
1c210 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
1c220 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71   to hold the [sq
1c230 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a  lite3] object,.*
1c240 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65  * a NULL will be
1c250 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70   written into *p
1c260 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61  pDb instead of a
1c270 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
1c280 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a  [sqlite3].** obj
1c290 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20  ect.)^ ^(If the 
1c2a0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
1c2b0 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74  ed (and/or creat
1c2c0 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79  ed) successfully
1c2d0 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54  , then.** [SQLIT
1c2e0 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65  E_OK] is returne
1c2f0 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e  d.  Otherwise an
1c300 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
1c310 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68   returned.)^ ^Th
1c320 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72  e.** [sqlite3_er
1c330 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69  rmsg()] or [sqli
1c340 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20  te3_errmsg16()] 
1c350 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20  routines can be 
1c360 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a  used to obtain.*
1c370 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e  * an English lan
1c380 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f  guage descriptio
1c390 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66  n of the error f
1c3a0 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75  ollowing a failu
1c3b0 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20  re of any.** of 
1c3c0 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  the sqlite3_open
1c3d0 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  () routines..**.
1c3e0 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
1c3f0 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65  encoding for the
1c400 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
1c410 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71  e UTF-8 if.** sq
1c420 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
1c430 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1c440 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a  ) is called and.
1c450 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65  ** UTF-16 in the
1c460 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
1c470 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f 6f 70  er if sqlite3_op
1c480 65 6e 31 36 28 29 20 69 73 20 75 73 65 64 2e 0a  en16() is used..
1c490 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72  **.** Whether or
1c4a0 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63   not an error oc
1c4b0 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20  curs when it is 
1c4c0 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65  opened, resource
1c4d0 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  s.** associated 
1c4e0 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
1c4f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
1c500 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20  andle should be 
1c510 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70  released by.** p
1c520 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71  assing it to [sq
1c530 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77  lite3_close()] w
1c540 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e  hen it is no lon
1c550 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a  ger required..**
1c560 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1c570 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66  open_v2() interf
1c580 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73  ace works like s
1c590 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a  qlite3_open().**
1c5a0 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20   except that it 
1c5b0 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69  accepts two addi
1c5c0 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72  tional parameter
1c5d0 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  s for additional
1c5e0 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72   control.** over
1c5f0 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73   the new databas
1c600 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e  e connection.  ^
1c610 28 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d  (The flags param
1c620 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  eter to.** sqlit
1c630 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e  e3_open_v2() can
1c640 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20   take one of.** 
1c650 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  the following th
1c660 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69  ree values, opti
1c670 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20  onally combined 
1c680 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51  with the .** [SQ
1c690 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
1c6a0 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  X], [SQLITE_OPEN
1c6b0 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51  _FULLMUTEX], [SQ
1c6c0 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
1c6d0 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  CACHE],.** [SQLI
1c6e0 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
1c6f0 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53  ACHE], and/or [S
1c700 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
1c710 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c  flags:)^.**.** <
1c720 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  dl>.** ^(<dt>[SQ
1c730 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
1c740 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LY]</dt>.** <dd>
1c750 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
1c760 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f  opened in read-o
1c770 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68  nly mode.  If th
1c780 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20  e database does 
1c790 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65  not.** already e
1c7a0 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69  xist, an error i
1c7b0 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e  s returned.</dd>
1c7c0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b  )^.**.** ^(<dt>[
1c7d0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
1c7e0 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  WRITE]</dt>.** <
1c7f0 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
1c800 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
1c810 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e  ading and writin
1c820 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f  g if possible, o
1c830 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c  r reading.** onl
1c840 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73  y if the file is
1c850 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64   write protected
1c860 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e   by the operatin
1c870 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69  g system.  In ei
1c880 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65  ther.** case the
1c890 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61   database must a
1c8a0 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74  lready exist, ot
1c8b0 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72  herwise an error
1c8c0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64   is returned.</d
1c8d0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74  d>)^.**.** ^(<dt
1c8e0 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
1c8f0 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49  ADWRITE] | [SQLI
1c900 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c  TE_OPEN_CREATE]<
1c910 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1c920 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
1c930 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  ed for reading a
1c940 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20  nd writing, and 
1c950 69 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a  is created if.**
1c960 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72   it does not alr
1c970 65 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73  eady exist. This
1c980 20 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72   is the behavior
1c990 20 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20   that is always 
1c9a0 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  used for.** sqli
1c9b0 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
1c9c0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e  qlite3_open16().
1c9d0 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e  </dd>)^.** </dl>
1c9e0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72  .**.** If the 3r
1c9f0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
1ca00 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1ca10 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74   is not one of t
1ca20 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f  he.** combinatio
1ca30 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f  ns shown above o
1ca40 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e  ptionally combin
1ca50 65 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a  ed with other.**
1ca60 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
1ca70 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f  ADONLY | SQLITE_
1ca80 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20  OPEN_* bits].** 
1ca90 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
1caa0 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
1cab0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53  **.** ^If the [S
1cac0 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
1cad0 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c  EX] flag is set,
1cae0 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
1caf0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
1cb00 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75   opens in the mu
1cb10 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65  lti-thread [thre
1cb20 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c  ading mode] as l
1cb30 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c  ong as the singl
1cb40 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65  e-thread.** mode
1cb50 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65   has not been se
1cb60 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  t at compile-tim
1cb70 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e  e or start-time.
1cb80 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51    ^If the.** [SQ
1cb90 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
1cba0 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74  TEX] flag is set
1cbb0 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
1cbc0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70  se connection op
1cbd0 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65  ens.** in the se
1cbe0 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
1cbf0 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73  ing mode] unless
1cc00 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77   single-thread w
1cc10 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  as.** previously
1cc20 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d   selected at com
1cc30 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61  pile-time or sta
1cc40 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65  rt-time..** ^The
1cc50 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48   [SQLITE_OPEN_SH
1cc60 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20  AREDCACHE] flag 
1cc70 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62  causes the datab
1cc80 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
1cc90 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65  o be.** eligible
1cca0 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20   to use [shared 
1ccb0 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67  cache mode], reg
1ccc0 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
1ccd0 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64  er or not shared
1cce0 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61  .** cache is ena
1ccf0 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  bled using [sqli
1cd00 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65  te3_enable_share
1cd10 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68  d_cache()].  ^Th
1cd20 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  e.** [SQLITE_OPE
1cd30 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20  N_PRIVATECACHE] 
1cd40 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20  flag causes the 
1cd50 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1cd60 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61  ion to not.** pa
1cd70 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68  rticipate in [sh
1cd80 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d  ared cache mode]
1cd90 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 65   even if it is e
1cda0 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  nabled..**.** ^T
1cdb0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
1cdc0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
1cdd0 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20  pen_v2() is the 
1cde0 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  name of the.** [
1cdf0 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
1ce00 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73  ect that defines
1ce10 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
1ce20 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20  ystem interface 
1ce30 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20  that.** the new 
1ce40 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1ce50 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20  ion should use. 
1ce60 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20   ^If the fourth 
1ce70 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
1ce80 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
1ce90 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20  hen the default 
1cea0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
1ceb0 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a  ject is used..**
1cec0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65  .** ^If the file
1ced0 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79  name is ":memory
1cee0 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61  :", then a priva
1cef0 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e  te, temporary in
1cf00 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
1cf10 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 66  .** is created f
1cf20 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  or the connectio
1cf30 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d  n.  ^This in-mem
1cf40 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c  ory database wil
1cf50 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a  l vanish when.**
1cf60 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1cf70 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
1cf80 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  ed.  Future vers
1cf90 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
1cfa0 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65  ight.** make use
1cfb0 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73   of additional s
1cfc0 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73  pecial filenames
1cfd0 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68   that begin with
1cfe0 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74   the ":" charact
1cff0 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63  er..** It is rec
1d000 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68  ommended that wh
1d010 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69  en a database fi
1d020 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20  lename actually 
1d030 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a  does begin with.
1d040 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74  ** a ":" charact
1d050 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72  er you should pr
1d060 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d  efix the filenam
1d070 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d  e with a pathnam
1d080 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f  e such as.** "./
1d090 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67  " to avoid ambig
1d0a0 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  uity..**.** ^If 
1d0b0 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
1d0c0 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c  an empty string,
1d0d0 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c   then a private,
1d0e0 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e   temporary.** on
1d0f0 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77  -disk database w
1d100 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20  ill be created. 
1d110 20 5e 54 68 69 73 20 70 72 69 76 61 74 65 20 64   ^This private d
1d120 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a  atabase will be.
1d130 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
1d140 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e   deleted as soon
1d150 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65   as the database
1d160 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
1d170 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55  losed..**.** [[U
1d180 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20  RI filenames in 
1d190 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d  sqlite3_open()]]
1d1a0 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d   <h3>URI Filenam
1d1b0 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49  es</h3>.**.** ^I
1d1c0 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d  f [URI filename]
1d1d0 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
1d1e0 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20  is enabled, and 
1d1f0 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  the filename arg
1d200 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20  ument.** begins 
1d210 77 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68  with "file:", th
1d220 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  en the filename 
1d230 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
1d240 73 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a  s a URI. ^URI.**
1d250 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70   filename interp
1d260 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62  retation is enab
1d270 6c 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49  led if the [SQLI
1d280 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61  TE_OPEN_URI] fla
1d290 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74  g is.** set in t
1d2a0 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
1d2b0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  nt to sqlite3_op
1d2c0 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69  en_v2(), or if i
1d2d0 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e  t has.** been en
1d2e0 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75  abled globally u
1d2f0 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
1d300 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74  _CONFIG_URI] opt
1d310 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  ion with the.** 
1d320 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
1d330 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20  )] method or by 
1d340 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f  the [SQLITE_USE_
1d350 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  URI] compile-tim
1d360 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20  e option..** As 
1d370 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  of SQLite versio
1d380 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c  n 3.7.7, URI fil
1d390 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61  ename interpreta
1d3a0 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f  tion is turned o
1d3b0 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74  ff.** by default
1d3c0 2c 20 62 75 74 20 66 75 74 75 72 65 20 72 65 6c  , but future rel
1d3d0 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20  eases of SQLite 
1d3e0 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49  might enable URI
1d3f0 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74   filename.** int
1d400 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64  erpretation by d
1d410 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55  efault.  See "[U
1d420 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66  RI filenames]" f
1d430 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  or additional.**
1d440 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
1d450 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  .** URI filename
1d460 73 20 61 72 65 20 70 61 72 73 65 64 20 61 63 63  s are parsed acc
1d470 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39  ording to RFC 39
1d480 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20  86. ^If the URI 
1d490 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61  contains an.** a
1d4a0 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69  uthority, then i
1d4b0 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  t must be either
1d4c0 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
1d4d0 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a   or the string .
1d4e0 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20  ** "localhost". 
1d4f0 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 74  ^If the authorit
1d500 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74  y is not an empt
1d510 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63  y string or "loc
1d520 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20  alhost", an .** 
1d530 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
1d540 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e  d to the caller.
1d550 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63   ^The fragment c
1d560 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52  omponent of a UR
1d570 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e  I, if .** presen
1d580 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a  t, is ignored..*
1d590 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65  *.** ^SQLite use
1d5a0 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f  s the path compo
1d5b0 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20  nent of the URI 
1d5c0 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  as the name of t
1d5d0 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20  he disk file.** 
1d5e0 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74  which contains t
1d5f0 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66  he database. ^If
1d600 20 74 68 65 20 70 61 74 68 20 62 65 67 69 6e 73   the path begins
1d610 20 77 69 74 68 20 61 20 27 2f 27 20 63 68 61 72   with a '/' char
1d620 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20  acter, .** then 
1d630 69 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  it is interprete
1d640 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65  d as an absolute
1d650 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70   path. ^If the p
1d660 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67  ath does not beg
1d670 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f  in .** with a '/
1d680 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20  ' (meaning that 
1d690 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 73 65  the authority se
1d6a0 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64  ction is omitted
1d6b0 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a   from the URI).*
1d6c0 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74 68 20  * then the path 
1d6d0 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
1d6e0 73 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74  s a relative pat
1d6f0 68 2e 20 0a 2a 2a 20 5e 4f 6e 20 77 69 6e 64 6f  h. .** ^On windo
1d700 77 73 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f  ws, the first co
1d710 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62  mponent of an ab
1d720 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20  solute path .** 
1d730 69 73 20 61 20 64 72 69 76 65 20 73 70 65 63 69  is a drive speci
1d740 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22  fication (e.g. "
1d750 43 3a 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f  C:")..**.** [[co
1d760 72 65 20 55 52 49 20 71 75 65 72 79 20 70 61 72  re URI query par
1d770 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65  ameters]].** The
1d780 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74   query component
1d790 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f   of a URI may co
1d7a0 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73  ntain parameters
1d7b0 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 70   that are interp
1d7c0 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20  reted.** either 
1d7d0 62 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66  by SQLite itself
1d7e0 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c  , or by a [VFS |
1d7f0 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c   custom VFS impl
1d800 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20  ementation]..** 
1d810 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74  SQLite interpret
1d820 73 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  s the following 
1d830 74 68 72 65 65 20 71 75 65 72 79 20 70 61 72 61  three query para
1d840 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  meters:.**.** <u
1d850 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e  l>.**   <li> <b>
1d860 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76  vfs</b>: ^The "v
1d870 66 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61  fs" parameter ma
1d880 79 20 62 65 20 75 73 65 64 20 74 6f 20 73 70 65  y be used to spe
1d890 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66  cify the name of
1d8a0 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62  .**     a VFS ob
1d8b0 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76 69 64  ject that provid
1d8c0 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  es the operating
1d8d0 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63   system interfac
1d8e0 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a  e that should.**
1d8f0 20 20 20 20 20 62 65 20 75 73 65 64 20 74 6f 20       be used to 
1d900 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62  access the datab
1d910 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b  ase file on disk
1d920 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f  . ^If this optio
1d930 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20  n is set to.**  
1d940 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69     an empty stri
1d950 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74 20 56  ng the default V
1d960 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  FS object is use
1d970 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61  d. ^Specifying a
1d980 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20  n unknown.**    
1d990 20 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72   VFS is an error
1d9a0 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70  . ^If sqlite3_op
1d9b0 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20  en_v2() is used 
1d9c0 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74 69  and the vfs opti
1d9d0 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65  on is.**     pre
1d9e0 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56  sent, then the V
1d9f0 46 53 20 73 70 65 63 69 66 69 65 64 20 62 79 20  FS specified by 
1da00 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  the option takes
1da10 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72   precedence over
1da20 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75  .**     the valu
1da30 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
1da40 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
1da50 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
1da60 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c  _v2()..**.**   <
1da70 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a  li> <b>mode</b>:
1da80 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61   ^(The mode para
1da90 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74  meter may be set
1daa0 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c   to either "ro",
1dab0 20 22 72 77 22 20 6f 72 0a 2a 2a 20 20 20 20 20   "rw" or.**     
1dac0 22 72 77 63 22 2e 20 41 74 74 65 6d 70 74 69 6e  "rwc". Attemptin
1dad0 67 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20 61  g to set it to a
1dae0 6e 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20 69  ny other value i
1daf0 73 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a  s an error)^. .*
1db00 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20 69  *     ^If "ro" i
1db10 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 68 65  s specified, the
1db20 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
1db30 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
1db40 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61  d-only .**     a
1db50 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20 69  ccess, just as i
1db60 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
1db70 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61  EN_READONLY] fla
1db80 67 20 68 61 64 20 62 65 65 6e 20 73 65 74 20 69  g had been set i
1db90 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74 68  n the .**     th
1dba0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ird argument to 
1dbb0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1dbc0 76 32 28 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f  v2(). ^If the mo
1dbd0 64 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74  de option is set
1dbe0 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 22   to .**     "rw"
1dbf0 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
1dc00 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
1dc10 72 20 72 65 61 64 2d 77 72 69 74 65 20 28 62 75  r read-write (bu
1dc20 74 20 6e 6f 74 20 63 72 65 61 74 65 29 20 0a 2a  t not create) .*
1dc30 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 61 73  *     access, as
1dc40 20 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   if SQLITE_OPEN_
1dc50 52 45 41 44 57 52 49 54 45 20 28 62 75 74 20 6e  READWRITE (but n
1dc60 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  ot SQLITE_OPEN_C
1dc70 52 45 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 20  REATE) had .**  
1dc80 20 20 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 61     been set. ^Va
1dc90 6c 75 65 20 22 72 77 63 22 20 69 73 20 65 71 75  lue "rwc" is equ
1dca0 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69  ivalent to setti
1dcb0 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20  ng both .**     
1dcc0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
1dcd0 57 52 49 54 45 20 61 6e 64 20 53 51 4c 49 54 45  WRITE and SQLITE
1dce0 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 5e 49  _OPEN_CREATE. ^I
1dcf0 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  f sqlite3_open_v
1dd00 32 28 29 20 69 73 20 0a 2a 2a 20 20 20 20 20 75  2() is .**     u
1dd10 73 65 64 2c 20 69 74 20 69 73 20 61 6e 20 65 72  sed, it is an er
1dd20 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79 20 61  ror to specify a
1dd30 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 6d   value for the m
1dd40 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 74 68  ode parameter th
1dd50 61 74 20 69 73 20 0a 2a 2a 20 20 20 20 20 6c 65  at is .**     le
1dd60 73 73 20 72 65 73 74 72 69 63 74 69 76 65 20 74  ss restrictive t
1dd70 68 61 6e 20 74 68 61 74 20 73 70 65 63 69 66 69  han that specifi
1dd80 65 64 20 62 79 20 74 68 65 20 66 6c 61 67 73 20  ed by the flags 
1dd90 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68  passed as the th
1dda0 69 72 64 20 0a 2a 2a 20 20 20 20 20 70 61 72 61  ird .**     para
1ddb0 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c  meter..**.**   <
1ddc0 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e  li> <b>cache</b>
1ddd0 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70 61 72  : ^The cache par
1dde0 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65  ameter may be se
1ddf0 74 20 74 6f 20 65 69 74 68 65 72 20 22 73 68 61  t to either "sha
1de00 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22  red" or.**     "
1de10 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69  private". ^Setti
1de20 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72 65 64  ng it to "shared
1de30 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20  " is equivalent 
1de40 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a  to setting the.*
1de50 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45  *     SQLITE_OPE
1de60 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 62 69  N_SHAREDCACHE bi
1de70 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61  t in the flags a
1de80 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74  rgument passed t
1de90 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33  o.**     sqlite3
1dea0 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74  _open_v2(). ^Set
1deb0 74 69 6e 67 20 74 68 65 20 63 61 63 68 65 20 70  ting the cache p
1dec0 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69  arameter to "pri
1ded0 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20  vate" is .**    
1dee0 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73   equivalent to s
1def0 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54  etting the SQLIT
1df00 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
1df10 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20  CHE bit..**     
1df20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ^If sqlite3_open
1df30 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e  _v2() is used an
1df40 64 20 74 68 65 20 22 63 61 63 68 65 22 20 70 61  d the "cache" pa
1df50 72 61 6d 65 74 65 72 20 69 73 20 70 72 65 73 65  rameter is prese
1df60 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55  nt in.**     a U
1df70 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73  RI filename, its
1df80 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73   value overrides
1df90 20 61 6e 79 20 62 65 68 61 76 69 6f 75 72 20 72   any behaviour r
1dfa0 65 71 75 65 73 74 65 64 20 62 79 20 73 65 74 74  equested by sett
1dfb0 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  ing.**     SQLIT
1dfc0 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
1dfd0 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50  CHE or SQLITE_OP
1dfe0 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 66  EN_SHAREDCACHE f
1dff0 6c 61 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  lag..** </ul>.**
1e000 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20  .** ^Specifying 
1e010 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d  an unknown param
1e020 65 74 65 72 20 69 6e 20 74 68 65 20 71 75 65 72  eter in the quer
1e030 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  y component of a
1e040 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a   URI is not an.*
1e050 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65  * error.  Future
1e060 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
1e070 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73  ite might unders
1e080 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20  tand additional 
1e090 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74  query.** paramet
1e0a0 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72  ers.  See "[quer
1e0b0 79 20 70 61 72 61 6d 65 74 65 72 73 20 77 69 74  y parameters wit
1e0c0 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e  h special meanin
1e0d0 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f  g to SQLite]" fo
1e0e0 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20  r.** additional 
1e0f0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
1e100 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ** [[URI filenam
1e110 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33  e examples]] <h3
1e120 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78  >URI filename ex
1e130 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a  amples</h3>.**.*
1e140 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d  * <table border=
1e150 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72  "1" align=center
1e160 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a   cellpadding=5>.
1e170 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20  ** <tr><th> URI 
1e180 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52  filenames <th> R
1e190 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74  esults.** <tr><t
1e1a0 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20  d> file:data.db 
1e1b0 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
1e1c0 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20    Open the file 
1e1d0 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65  "data.db" in the
1e1e0 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f   current directo
1e1f0 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ry..** <tr><td> 
1e200 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f  file:/home/fred/
1e210 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20  data.db<br>.**  
1e220 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f          file:///
1e230 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
1e240 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20  b <br> .**      
1e250 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c      file://local
1e260 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  host/home/fred/d
1e270 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e  ata.db <br> <td>
1e280 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70   .**          Op
1e290 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
1e2a0 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64  file "/home/fred
1e2b0 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74  /data.db"..** <t
1e2c0 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61  r><td> file://da
1e2d0 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64  rkstar/home/fred
1e2e0 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a  /data.db <td> .*
1e2f0 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72  *          An er
1e300 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20  ror. "darkstar" 
1e310 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69  is not a recogni
1e320 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a  zed authority..*
1e330 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d  * <tr><td style=
1e340 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77  "white-space:now
1e350 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20  rap"> .**       
1e360 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f     file:///C:/Do
1e370 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30  cuments%20and%20
1e380 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65  Settings/fred/De
1e390 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a  sktop/data.db.**
1e3a0 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77       <td> Window
1e3b0 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65  s only: Open the
1e3c0 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20   file "data.db" 
1e3d0 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f  on fred's deskto
1e3e0 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20  p on drive.**   
1e3f0 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20         C:. Note 
1e400 74 68 61 74 20 74 68 65 20 25 32 30 20 65 73 63  that the %20 esc
1e410 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78  aping in this ex
1e420 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72  ample is not str
1e430 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20  ictly .**       
1e440 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73     necessary - s
1e450 70 61 63 65 20 63 68 61 72 61 63 74 65 72 73 20  pace characters 
1e460 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65  can be used lite
1e470 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20  rally.**        
1e480 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d    in URI filenam
1e490 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  es..** <tr><td> 
1e4a0 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64  file:data.db?mod
1e4b0 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61  e=ro&cache=priva
1e4c0 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  te <td> .**     
1e4d0 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22       Open file "
1e4e0 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20  data.db" in the 
1e4f0 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72  current director
1e500 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20  y for read-only 
1e510 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20  access..**      
1e520 20 20 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f      Regardless o
1e530 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
1e540 20 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f   shared-cache mo
1e550 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79  de is enabled by
1e560 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 66  .**          def
1e570 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76  ault, use a priv
1e580 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74  ate cache..** <t
1e590 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d  r><td> file:/hom
1e5a0 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76  e/fred/data.db?v
1e5b0 66 73 3d 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 20 3c  fs=unix-nolock <
1e5c0 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  td>.**          
1e5d0 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65  Open file "/home
1e5e0 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20  /fred/data.db". 
1e5f0 55 73 65 20 74 68 65 20 73 70 65 63 69 61 6c 20  Use the special 
1e600 56 46 53 20 22 75 6e 69 78 2d 6e 6f 6c 6f 63 6b  VFS "unix-nolock
1e610 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  "..** <tr><td> f
1e620 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65  ile:data.db?mode
1e630 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a  =readonly <td> .
1e640 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65  **          An e
1e650 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22  rror. "readonly"
1e660 20 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20   is not a valid 
1e670 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22  option for the "
1e680 6d 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e  mode" parameter.
1e690 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a  .** </table>.**.
1e6a0 2a 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63 69  ** ^URI hexadeci
1e6b0 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65  mal escape seque
1e6c0 6e 63 65 73 20 28 25 48 48 29 20 61 72 65 20 73  nces (%HH) are s
1e6d0 75 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20  upported within 
1e6e0 74 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20  the path and.** 
1e6f0 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73  query components
1e700 20 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65 78   of a URI. A hex
1e710 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20  adecimal escape 
1e720 73 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74  sequence consist
1e730 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e  s of a.** percen
1e740 74 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66  t sign - "%" - f
1e750 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74  ollowed by exact
1e760 6c 79 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d  ly two hexadecim
1e770 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70  al digits .** sp
1e780 65 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65  ecifying an octe
1e790 74 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65  t value. ^Before
1e7a0 20 74 68 65 20 70 61 74 68 20 6f 72 20 71 75 65   the path or que
1e7b0 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66  ry components of
1e7c0 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61   a.** URI filena
1e7d0 6d 65 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  me are interpret
1e7e0 65 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63  ed, they are enc
1e7f0 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38  oded using UTF-8
1e800 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78   and all .** hex
1e810 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20  adecimal escape 
1e820 73 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63  sequences replac
1e830 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62  ed by a single b
1e840 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  yte containing t
1e850 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64  he.** correspond
1e860 69 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68  ing octet. If th
1e870 69 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72  is process gener
1e880 61 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20  ates an invalid 
1e890 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a  UTF-8 encoding,.
1e8a0 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  ** the results a
1e8b0 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
1e8c0 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57  .** <b>Note to W
1e8d0 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62  indows users:</b
1e8e0 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20  >  The encoding 
1e8f0 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c  used for the fil
1e900 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ename argument.*
1e910 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65  * of sqlite3_ope
1e920 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
1e930 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62  open_v2() must b
1e940 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61  e UTF-8, not wha
1e950 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67  tever.** codepag
1e960 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64  e is currently d
1e970 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d  efined.  Filenam
1e980 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e  es containing in
1e990 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63  ternational.** c
1e9a0 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62  haracters must b
1e9b0 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55  e converted to U
1e9c0 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61  TF-8 prior to pa
1e9d0 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a  ssing them into.
1e9e0 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
1e9f0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
1ea00 6e 5f 76 32 28 29 2e 0a 2a 2f 0a 69 6e 74 20 73  n_v2()..*/.int s
1ea10 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63  qlite3_open(.  c
1ea20 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e  onst char *filen
1ea30 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61  ame,   /* Databa
1ea40 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46  se filename (UTF
1ea50 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  -8) */.  sqlite3
1ea60 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20   **ppDb         
1ea70 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
1ea80 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a  db handle */.);.
1ea90 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
1eaa0 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64  16(.  const void
1eab0 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
1eac0 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
1ead0 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20  me (UTF-16) */. 
1eae0 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20   sqlite3 **ppDb 
1eaf0 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
1eb00 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
1eb10 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  e */.);.int sqli
1eb20 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63  te3_open_v2(.  c
1eb30 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e  onst char *filen
1eb40 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61  ame,   /* Databa
1eb50 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46  se filename (UTF
1eb60 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  -8) */.  sqlite3
1eb70 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20   **ppDb,        
1eb80 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
1eb90 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69  db handle */.  i
1eba0 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20  nt flags,       
1ebb0 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20         /* Flags 
1ebc0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
1ebd0 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20  *zVfs        /* 
1ebe0 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75  Name of VFS modu
1ebf0 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a  le to use */.);.
1ec00 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1ec10 20 4f 62 74 61 69 6e 20 56 61 6c 75 65 73 20 46   Obtain Values F
1ec20 6f 72 20 55 52 49 20 50 61 72 61 6d 65 74 65 72  or URI Parameter
1ec30 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20  s.**.** This is 
1ec40 61 20 75 74 69 6c 69 74 79 20 72 6f 75 74 69 6e  a utility routin
1ec50 65 2c 20 75 73 65 66 75 6c 20 74 6f 20 56 46 53  e, useful to VFS
1ec60 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
1ec70 2c 20 74 68 61 74 20 63 68 65 63 6b 73 0a 2a 2a  , that checks.**
1ec80 20 74 6f 20 73 65 65 20 69 66 20 61 20 64 61 74   to see if a dat
1ec90 61 62 61 73 65 20 66 69 6c 65 20 77 61 73 20 61  abase file was a
1eca0 20 55 52 49 20 74 68 61 74 20 63 6f 6e 74 61 69   URI that contai
1ecb0 6e 65 64 20 61 20 73 70 65 63 69 66 69 63 20 71  ned a specific q
1ecc0 75 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74  uery .** paramet
1ecd0 65 72 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f 62  er, and if so ob
1ece0 74 61 69 6e 73 20 74 68 65 20 76 61 6c 75 65 20  tains the value 
1ecf0 6f 66 20 74 68 65 20 71 75 65 72 79 20 70 61 72  of the query par
1ed00 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  ameter..**.** Th
1ed10 65 20 7a 46 69 6c 65 6e 61 6d 65 20 61 72 67 75  e zFilename argu
1ed20 6d 65 6e 74 20 69 73 20 74 68 65 20 66 69 6c 65  ment is the file
1ed30 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 73  name pointer pas
1ed40 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70  sed into the xOp
1ed50 65 6e 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f  en().** method o
1ed60 66 20 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  f a VFS implemen
1ed70 74 61 74 69 6f 6e 2e 20 20 54 68 65 20 7a 50 61  tation.  The zPa
1ed80 72 61 6d 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ram argument is 
1ed90 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a  the name of the.
1eda0 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  ** query paramet
1edb0 65 72 20 77 65 20 73 65 65 6b 2e 20 20 54 68 69  er we seek.  Thi
1edc0 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
1edd0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
1ede0 68 65 20 7a 50 61 72 61 6d 0a 2a 2a 20 70 61 72  he zParam.** par
1edf0 61 6d 65 74 65 72 20 69 66 20 69 74 20 65 78 69  ameter if it exi
1ee00 73 74 73 2e 20 20 49 66 20 74 68 65 20 70 61 72  sts.  If the par
1ee10 61 6d 65 74 65 72 20 64 6f 65 73 20 6e 6f 74 20  ameter does not 
1ee20 65 78 69 73 74 2c 20 74 68 69 73 20 72 6f 75 74  exist, this rout
1ee30 69 6e 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61  ine.** returns a
1ee40 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
1ee50 2a 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c  *.** If the zFil
1ee60 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 74  ename argument t
1ee70 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  o this function 
1ee80 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72  is not a pointer
1ee90 20 74 68 61 74 20 53 51 4c 69 74 65 0a 2a 2a 20   that SQLite.** 
1eea0 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20  passed into the 
1eeb0 78 4f 70 65 6e 20 56 46 53 20 6d 65 74 68 6f 64  xOpen VFS method
1eec0 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
1eed0 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ior of this rout
1eee0 69 6e 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69  ine.** is undefi
1eef0 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79  ned and probably
1ef00 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f   undesirable..*/
1ef10 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1ef20 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
1ef30 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  er(const char *z
1ef40 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20  Filename, const 
1ef50 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 0a  char *zParam);..
1ef60 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1ef70 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64   Error Codes And
1ef80 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20   Messages.**.** 
1ef90 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72  ^The sqlite3_err
1efa0 63 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63 65  code() interface
1efb0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
1efc0 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64  eric [result cod
1efd0 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64  e] or.** [extend
1efe0 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  ed result code] 
1eff0 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63  for the most rec
1f000 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74  ent failed sqlit
1f010 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a  e3_* API call.**
1f020 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
1f030 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
1f040 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70  nection]. If a p
1f050 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61  rior API call fa
1f060 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 65 20  iled.** but the 
1f070 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20  most recent API 
1f080 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20  call succeeded, 
1f090 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
1f0a0 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33   from.** sqlite3
1f0b0 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e  _errcode() is un
1f0c0 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 73  defined.  ^The s
1f0d0 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
1f0e0 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74  errcode().** int
1f0f0 65 72 66 61 63 65 20 69 73 20 74 68 65 20 73 61  erface is the sa
1f100 6d 65 20 65 78 63 65 70 74 20 74 68 61 74 20 69  me except that i
1f110 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  t always returns
1f120 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64   the .** [extend
1f130 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  ed result code] 
1f140 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64  even when extend
1f150 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
1f160 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e  are.** disabled.
1f170 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1f180 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64  te3_errmsg() and
1f190 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31   sqlite3_errmsg1
1f1a0 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69  6() return Engli
1f1b0 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74  sh-language.** t
1f1c0 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62  ext that describ
1f1d0 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73  es the error, as
1f1e0 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72   either UTF-8 or
1f1f0 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 69   UTF-16 respecti
1f200 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72  vely..** ^(Memor
1f210 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72  y to hold the er
1f220 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69  ror message stri
1f230 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e  ng is managed in
1f240 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65  ternally..** The
1f250 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65   application doe
1f260 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f  s not need to wo
1f270 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e  rry about freein
1f280 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a  g the result..**
1f290 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72   However, the er
1f2a0 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74  ror string might
1f2b0 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20   be overwritten 
1f2c0 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62  or deallocated b
1f2d0 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20  y.** subsequent 
1f2e0 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53  calls to other S
1f2f0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 20  QLite interface 
1f300 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a  functions.)^.**.
1f310 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69  ** When the seri
1f320 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
1f330 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73  g mode] is in us
1f340 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74  e, it might be t
1f350 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20  he.** case that 
1f360 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f  a second error o
1f370 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72  ccurs on a separ
1f380 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65  ate thread in be
1f390 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d  tween.** the tim
1f3a0 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65  e of the first e
1f3b0 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c  rror and the cal
1f3c0 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72  l to these inter
1f3d0 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74  faces..** When t
1f3e0 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65  hat happens, the
1f3f0 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69   second error wi
1f400 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73  ll be reported s
1f410 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e  ince these.** in
1f420 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20  terfaces always 
1f430 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20  report the most 
1f440 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20  recent result.  
1f450 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73  To avoid.** this
1f460 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61  , each thread ca
1f470 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69  n obtain exclusi
1f480 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64  ve use of the [d
1f490 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1f4a0 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f  on] D.** by invo
1f4b0 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  king [sqlite3_mu
1f4c0 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69  tex_enter]([sqli
1f4d0 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29  te3_db_mutex](D)
1f4e0 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69  ) before beginni
1f4f0 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61  ng.** to use D a
1f500 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c  nd invoking [sql
1f510 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65  ite3_mutex_leave
1f520 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75  ]([sqlite3_db_mu
1f530 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a  tex](D)) after.*
1f540 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74  * all calls to t
1f550 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69  he interfaces li
1f560 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f  sted here are co
1f570 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  mpleted..**.** I
1f580 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66  f an interface f
1f590 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45  ails with SQLITE
1f5a0 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65  _MISUSE, that me
1f5b0 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  ans the interfac
1f5c0 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64  e.** was invoked
1f5d0 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20   incorrectly by 
1f5e0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e  the application.
1f5f0 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20    In that case, 
1f600 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64  the.** error cod
1f610 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61  e and message ma
1f620 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20  y or may not be 
1f630 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  set..*/.int sqli
1f640 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69  te3_errcode(sqli
1f650 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71  te3 *db);.int sq
1f660 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65  lite3_extended_e
1f670 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a  rrcode(sqlite3 *
1f680 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  db);.const char 
1f690 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  *sqlite3_errmsg(
1f6a0 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74  sqlite3*);.const
1f6b0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65   void *sqlite3_e
1f6c0 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a  rrmsg16(sqlite3*
1f6d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1f6e0 45 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65 6e  EF: SQL Statemen
1f6f0 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57  t Object.** KEYW
1f700 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20  ORDS: {prepared 
1f710 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70  statement} {prep
1f720 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d  ared statements}
1f730 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
1f740 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
1f750 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 20 73  t represents a s
1f760 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d  ingle SQL statem
1f770 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a  ent..** This obj
1f780 65 63 74 20 69 73 20 76 61 72 69 6f 75 73 6c 79  ect is variously
1f790 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70 72 65   known as a "pre
1f7a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 22  pared statement"
1f7b0 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c   or a.** "compil
1f7c0 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
1f7d0 22 20 6f 72 20 73 69 6d 70 6c 79 20 61 73 20 61  " or simply as a
1f7e0 20 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a   "statement"..**
1f7f0 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f 66 20  .** The life of 
1f800 61 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65  a statement obje
1f810 63 74 20 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e  ct goes somethin
1f820 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a  g like this:.**.
1f830 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ol>.** <li> 
1f840 43 72 65 61 74 65 20 74 68 65 20 6f 62 6a 65 63  Create the objec
1f850 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
1f860 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
1f870 72 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20  r a related.**  
1f880 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a      function..**
1f890 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65   <li> Bind value
1f8a0 73 20 74 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d  s to [host param
1f8b0 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65  eters] using the
1f8c0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
1f8d0 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66  ).**      interf
1f8e0 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75  aces..** <li> Ru
1f8f0 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c  n the SQL by cal
1f900 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74  ling [sqlite3_st
1f910 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72  ep()] one or mor
1f920 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  e times..** <li>
1f930 20 52 65 73 65 74 20 74 68 65 20 73 74 61 74 65   Reset the state
1f940 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ment using [sqli
1f950 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65  te3_reset()] the
1f960 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20  n go back.**    
1f970 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f    to step 2.  Do
1f980 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f   this zero or mo
1f990 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69  re times..** <li
1f9a0 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62  > Destroy the ob
1f9b0 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ject using [sqli
1f9c0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e  te3_finalize()].
1f9d0 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ol>.**.** 
1f9e0 52 65 66 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e  Refer to documen
1f9f0 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69  tation on indivi
1fa00 64 75 61 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f  dual methods abo
1fa10 76 65 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  ve for additiona
1fa20 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  l.** information
1fa30 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
1fa40 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  uct sqlite3_stmt
1fa50 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a   sqlite3_stmt;..
1fa60 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1fa70 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a  Run-time Limits.
1fa80 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74  **.** ^(This int
1fa90 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68  erface allows th
1faa0 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75  e size of variou
1fab0 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20  s constructs to 
1fac0 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e  be limited.** on
1fad0 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79   a connection by
1fae0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69   connection basi
1faf0 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61  s.  The first pa
1fb00 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
1fb10 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
1fb20 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69  ection] whose li
1fb30 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73 65 74  mit is to be set
1fb40 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54 68   or queried.  Th
1fb50 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
1fb60 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20  meter is one of 
1fb70 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67  the [limit categ
1fb80 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65 66 69  ories] that defi
1fb90 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66  ne a.** class of
1fba0 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62   constructs to b
1fbb0 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20  e size limited. 
1fbc0 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   The third param
1fbd0 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e  eter is the.** n
1fbe0 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61  ew limit for tha
1fbf0 74 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a  t construct.)^.*
1fc00 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77  *.** ^If the new
1fc10 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61   limit is a nega
1fc20 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65  tive number, the
1fc30 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e   limit is unchan
1fc40 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61  ged..** ^(For ea
1fc50 63 68 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  ch limit categor
1fc60 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c  y SQLITE_LIMIT_<
1fc70 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65  i>NAME</i> there
1fc80 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74   is a .** [limit
1fc90 73 20 7c 20 68 61 72 64 20 75 70 70 65 72 20 62  s | hard upper b
1fca0 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20  ound].** set at 
1fcb0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20  compile-time by 
1fcc0 61 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  a C preprocessor
1fcd0 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a   macro called.**
1fce0 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54   [limits | SQLIT
1fcf0 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69  E_MAX_<i>NAME</i
1fd00 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49  >]..** (The "_LI
1fd10 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d  MIT_" in the nam
1fd20 65 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20  e is changed to 
1fd30 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e  "_MAX_".))^.** ^
1fd40 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72  Attempts to incr
1fd50 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f  ease a limit abo
1fd60 76 65 20 69 74 73 20 68 61 72 64 20 75 70 70 65  ve its hard uppe
1fd70 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73  r bound are.** s
1fd80 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65  ilently truncate
1fd90 64 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 70  d to the hard up
1fda0 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a  per bound..**.**
1fdb0 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20   ^Regardless of 
1fdc0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
1fdd0 68 65 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61  he limit was cha
1fde0 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73  nged, the .** [s
1fdf0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20  qlite3_limit()] 
1fe00 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
1fe10 73 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75  s the prior valu
1fe20 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a  e of the limit..
1fe30 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69  ** ^Hence, to fi
1fe40 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74 20 76  nd the current v
1fe50 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20  alue of a limit 
1fe60 77 69 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67  without changing
1fe70 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69   it,.** simply i
1fe80 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72  nvoke this inter
1fe90 66 61 63 65 20 77 69 74 68 20 74 68 65 20 74 68  face with the th
1fea0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 73 65  ird parameter se
1feb0 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52  t to -1..**.** R
1fec0 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61  un-time limits a
1fed0 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
1fee0 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69  use in applicati
1fef0 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a  ons that manage.
1ff00 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77  ** both their ow
1ff10 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62  n internal datab
1ff20 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74  ase and also dat
1ff30 61 62 61 73 65 73 20 74 68 61 74 20 61 72 65 20  abases that are 
1ff40 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79  controlled.** by
1ff50 20 75 6e 74 72 75 73 74 65 64 20 65 78 74 65 72   untrusted exter
1ff60 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e  nal sources.  An
1ff70 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61   example applica
1ff80 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a  tion might be a.
1ff90 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20 74  ** web browser t
1ffa0 68 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20  hat has its own 
1ffb0 64 61 74 61 62 61 73 65 73 20 66 6f 72 20 73 74  databases for st
1ffc0 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e  oring history an
1ffd0 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61  d.** separate da
1ffe0 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c  tabases controll
1fff0 65 64 20 62 79 20 4a 61 76 61 53 63 72 69 70 74  ed by JavaScript
20000 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f   applications do
20010 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20  wnloaded.** off 
20020 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54  the Internet.  T
20030 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  he internal data
20040 62 61 73 65 73 20 63 61 6e 20 62 65 20 67 69 76  bases can be giv
20050 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c  en the.** large,
20060 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e   default limits.
20070 20 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61    Databases mana
20080 67 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20  ged by external 
20090 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62  sources can.** b
200a0 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61  e given much sma
200b0 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69  ller limits desi
200c0 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20  gned to prevent 
200d0 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76  a denial of serv
200e0 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20  ice.** attack.  
200f0 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74  Developers might
20100 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73   also want to us
20110 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  e the [sqlite3_s
20120 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d  et_authorizer()]
20130 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f  .** interface to
20140 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c   further control
20150 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20   untrusted SQL. 
20160 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   The size of the
20170 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65   database.** cre
20180 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75  ated by an untru
20190 73 74 65 64 20 73 63 72 69 70 74 20 63 61 6e 20  sted script can 
201a0 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69  be contained usi
201b0 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70  ng the.** [max_p
201c0 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47  age_count] [PRAG
201d0 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72  MA]..**.** New r
201e0 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61  un-time limit ca
201f0 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20  tegories may be 
20200 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
20210 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74  releases..*/.int
20220 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73   sqlite3_limit(s
20230 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c  qlite3*, int id,
20240 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f   int newVal);../
20250 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
20260 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61  un-Time Limit Ca
20270 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57  tegories.** KEYW
20280 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74  ORDS: {limit cat
20290 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63  egory} {*limit c
202a0 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a  ategories}.**.**
202b0 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
202c0 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20   define various 
202d0 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69  performance limi
202e0 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62  ts.** that can b
202f0 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e  e lowered at run
20300 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c  -time using [sql
20310 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a  ite3_limit()]..*
20320 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f  * The synopsis o
20330 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f  f the meanings o
20340 66 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69  f the various li
20350 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65  mits is shown be
20360 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e  low..** Addition
20370 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  al information i
20380 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b  s available at [
20390 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20  limits | Limits 
203a0 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a  in SQLite]..**.*
203b0 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49  * <dl>.** [[SQLI
203c0 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d  TE_LIMIT_LENGTH]
203d0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
203e0 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  IMIT_LENGTH</dt>
203f0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
20400 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20  mum size of any 
20410 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f  string or BLOB o
20420 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20  r table row, in 
20430 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a  bytes.<dd>)^.**.
20440 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
20450 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e  T_SQL_LENGTH]] ^
20460 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
20470 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74  T_SQL_LENGTH</dt
20480 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
20490 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61  imum length of a
204a0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  n SQL statement,
204b0 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29   in bytes.</dd>)
204c0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
204d0 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20  _LIMIT_COLUMN]] 
204e0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
204f0 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a  IT_COLUMN</dt>.*
20500 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
20510 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  m number of colu
20520 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64  mns in a table d
20530 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20  efinition or in 
20540 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65  the.** result se
20550 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20  t of a [SELECT] 
20560 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e  or the maximum n
20570 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
20580 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20   in an index.** 
20590 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42  or in an ORDER B
205a0 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c  Y or GROUP BY cl
205b0 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ause.</dd>)^.**.
205c0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
205d0 54 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e  T_EXPR_DEPTH]] ^
205e0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
205f0 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74  T_EXPR_DEPTH</dt
20600 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
20610 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68  imum depth of th
20620 65 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20  e parse tree on 
20630 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c  any expression.<
20640 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
20650 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
20660 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28  OUND_SELECT]] ^(
20670 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
20680 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54  _COMPOUND_SELECT
20690 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
206a0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
206b0 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f  of terms in a co
206c0 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74  mpound SELECT st
206d0 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a  atement.</dd>)^.
206e0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
206f0 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e  IMIT_VDBE_OP]] ^
20700 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
20710 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a  T_VDBE_OP</dt>.*
20720 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
20730 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74  m number of inst
20740 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69  ructions in a vi
20750 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72  rtual machine pr
20760 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f  ogram.** used to
20770 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51   implement an SQ
20780 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68  L statement.  Th
20790 69 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20  is limit is not 
207a0 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66  currently.** enf
207b0 6f 72 63 65 64 2c 20 74 68 6f 75 67 68 20 74 68  orced, though th
207c0 61 74 20 6d 69 67 68 74 20 62 65 20 61 64 64 65  at might be adde
207d0 64 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65  d in some future
207e0 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53   release of.** S
207f0 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  QLite.</dd>)^.**
20800 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
20810 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d  IT_FUNCTION_ARG]
20820 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
20830 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
20840 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  G</dt>.** <dd>Th
20850 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
20860 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e   of arguments on
20870 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64   a function.</dd
20880 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
20890 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
208a0 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  D]] ^(<dt>SQLITE
208b0 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c  _LIMIT_ATTACHED<
208c0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
208d0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
208e0 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61  f [ATTACH | atta
208f0 63 68 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e  ched databases].
20900 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  )^</dd>.**.** [[
20910 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b  SQLITE_LIMIT_LIK
20920 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48  E_PATTERN_LENGTH
20930 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  ]].** ^(<dt>SQLI
20940 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41  TE_LIMIT_LIKE_PA
20950 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74  TTERN_LENGTH</dt
20960 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
20970 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74  imum length of t
20980 68 65 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d  he pattern argum
20990 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45  ent to the [LIKE
209a0 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f  ] or.** [GLOB] o
209b0 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e  perators.</dd>)^
209c0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
209d0 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
209e0 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74  UMBER]].** ^(<dt
209f0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  >SQLITE_LIMIT_VA
20a00 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64  RIABLE_NUMBER</d
20a10 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
20a20 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62  ximum index numb
20a30 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d  er of any [param
20a40 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20  eter] in an SQL 
20a50 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a  statement.)^.**.
20a60 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
20a70 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 5d  T_TRIGGER_DEPTH]
20a80 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
20a90 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50  IMIT_TRIGGER_DEP
20aa0 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
20ab0 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68  he maximum depth
20ac0 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f   of recursion fo
20ad0 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e  r triggers.</dd>
20ae0 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  )^.** </dl>.*/.#
20af0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
20b00 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  MIT_LENGTH      
20b10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0a                0.
20b20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
20b30 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20  IMIT_SQL_LENGTH 
20b40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
20b50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20b60 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20  LIMIT_COLUMN    
20b70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
20b80 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
20b90 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54  _LIMIT_EXPR_DEPT
20ba0 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
20bb0 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
20bc0 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44  E_LIMIT_COMPOUND
20bd0 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20  _SELECT         
20be0 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
20bf0 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50  TE_LIMIT_VDBE_OP
20c00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
20c10 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c     5.#define SQL
20c20 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
20c30 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20 20  ON_ARG          
20c40 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51      6.#define SQ
20c50 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43  LITE_LIMIT_ATTAC
20c60 48 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20  HED             
20c70 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53       7.#define S
20c80 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45  QLITE_LIMIT_LIKE
20c90 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20  _PATTERN_LENGTH 
20ca0 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20        8.#define 
20cb0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
20cc0 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20  IABLE_NUMBER    
20cd0 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65         9.#define
20ce0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52   SQLITE_LIMIT_TR
20cf0 49 47 47 45 52 5f 44 45 50 54 48 20 20 20 20 20  IGGER_DEPTH     
20d00 20 20 20 20 20 20 20 31 30 0a 0a 2f 2a 0a 2a 2a         10../*.**
20d10 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
20d20 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74  ling An SQL Stat
20d30 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44  ement.** KEYWORD
20d40 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e  S: {SQL statemen
20d50 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a  t compiler}.**.*
20d60 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20  * To execute an 
20d70 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75  SQL query, it mu
20d80 73 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70  st first be comp
20d90 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65  iled into a byte
20da0 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d  -code.** program
20db0 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68   using one of th
20dc0 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ese routines..**
20dd0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
20de0 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 73  gument, "db", is
20df0 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
20e00 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65  nection] obtaine
20e10 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f  d from a.** prio
20e20 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  r successful cal
20e30 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  l to [sqlite3_op
20e40 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
20e50 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a  open_v2()] or.**
20e60 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
20e70 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61 62 61  ()].  The databa
20e80 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75  se connection mu
20e90 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65 65 6e  st not have been
20ea0 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   closed..**.** T
20eb0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
20ec0 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74  nt, "zSql", is t
20ed0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  he statement to 
20ee0 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63  be compiled, enc
20ef0 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65  oded.** as eithe
20f00 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  r UTF-8 or UTF-1
20f10 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  6.  The sqlite3_
20f20 70 72 65 70 61 72 65 28 29 20 61 6e 64 20 73 71  prepare() and sq
20f30 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
20f40 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  ().** interfaces
20f50 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20   use UTF-8, and 
20f60 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
20f70 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  6() and sqlite3_
20f80 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a  prepare16_v2().*
20f90 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a  * use UTF-16..**
20fa0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 74  .** ^If the nByt
20fb0 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6c 65  e argument is le
20fc0 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68  ss than zero, th
20fd0 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20  en zSql is read 
20fe0 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72  up to the.** fir
20ff0 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
21000 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73  or. ^If nByte is
21010 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
21020 68 65 6e 20 69 74 20 69 73 20 74 68 65 20 6d 61  hen it is the ma
21030 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20  ximum.** number 
21040 6f 66 20 20 62 79 74 65 73 20 72 65 61 64 20 66  of  bytes read f
21050 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 57 68 65 6e  rom zSql.  ^When
21060 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65   nByte is non-ne
21070 67 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a  gative, the.** z
21080 53 71 6c 20 73 74 72 69 6e 67 20 65 6e 64 73 20  Sql string ends 
21090 61 74 20 65 69 74 68 65 72 20 74 68 65 20 66 69  at either the fi
210a0 72 73 74 20 27 5c 30 30 30 27 20 6f 72 20 27 5c  rst '\000' or '\
210b0 75 30 30 30 30 27 20 63 68 61 72 61 63 74 65 72  u0000' character
210c0 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65   or.** the nByte
210d0 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63 68 65  -th byte, whiche
210e0 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e  ver comes first.
210f0 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b   If the caller k
21100 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74 68 65  nows.** that the
21110 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67   supplied string
21120 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74   is nul-terminat
21130 65 64 2c 20 74 68 65 6e 20 74 68 65 72 65 20 69  ed, then there i
21140 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72  s a small.** per
21150 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61  formance advanta
21160 67 65 20 74 6f 20 62 65 20 67 61 69 6e 65 64 20  ge to be gained 
21170 62 79 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42  by passing an nB
21180 79 74 65 20 70 61 72 61 6d 65 74 65 72 20 74 68  yte parameter th
21190 61 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20 74  at.** is equal t
211a0 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  o the number of 
211b0 62 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70  bytes in the inp
211c0 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63  ut string <i>inc
211d0 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68  luding</i>.** th
211e0 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72  e nul-terminator
211f0 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49   bytes..**.** ^I
21200 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20  f pzTail is not 
21210 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69  NULL then *pzTai
21220 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69  l is made to poi
21230 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  nt to the first 
21240 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65  byte.** past the
21250 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73   end of the firs
21260 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
21270 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20  in zSql.  These 
21280 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a  routines only.**
21290 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72   compile the fir
212a0 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  st statement in 
212b0 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c  zSql, so *pzTail
212c0 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
212d0 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d  g to.** what rem
212e0 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e  ains uncompiled.
212f0 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20  .**.** ^*ppStmt 
21300 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
21310 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b   to a compiled [
21320 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
21330 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a  nt] that can be.
21340 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e  ** executed usin
21350 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
21360 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69  )].  ^If there i
21370 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53  s an error, *ppS
21380 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f  tmt is set.** to
21390 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20   NULL.  ^If the 
213a0 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61  input text conta
213b0 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74  ins no SQL (if t
213c0 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65  he input is an e
213d0 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  mpty.** string o
213e0 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65  r a comment) the
213f0 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  n *ppStmt is set
21400 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65   to NULL..** The
21410 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75   calling procedu
21420 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  re is responsibl
21430 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74  e for deleting t
21440 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53  he compiled.** S
21450 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  QL statement usi
21460 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
21470 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74  lize()] after it
21480 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
21490 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74  th it..** ppStmt
214a0 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c   may not be NULL
214b0 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63  ..**.** ^On succ
214c0 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ess, the sqlite3
214d0 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c  _prepare() famil
214e0 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65  y of routines re
214f0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
21500 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61  ;.** otherwise a
21510 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
21520 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
21530 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72  * The sqlite3_pr
21540 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73  epare_v2() and s
21550 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
21560 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 73  _v2() interfaces
21570 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e   are.** recommen
21580 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20  ded for all new 
21590 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77  programs. The tw
215a0 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63  o older interfac
215b0 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a  es are retained.
215c0 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ** for backwards
215d0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20   compatibility, 
215e0 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73  but their use is
215f0 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a   discouraged..**
21600 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e   ^In the "v2" in
21610 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72  terfaces, the pr
21620 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
21630 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75  .** that is retu
21640 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74  rned (the [sqlit
21650 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29  e3_stmt] object)
21660 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79   contains a copy
21670 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69   of the.** origi
21680 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68  nal SQL text. Th
21690 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73  is causes the [s
216a0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69  qlite3_step()] i
216b0 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62  nterface to.** b
216c0 65 68 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c  ehave differentl
216d0 79 20 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a  y in three ways:
216e0 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
216f0 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64  li>.** ^If the d
21700 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63  atabase schema c
21710 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20  hanges, instead 
21720 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51  of returning [SQ
21730 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20  LITE_SCHEMA] as 
21740 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65  it.** always use
21750 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65  d to do, [sqlite
21760 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61  3_step()] will a
21770 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63  utomatically rec
21780 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a  ompile the SQL.*
21790 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  * statement and 
217a0 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67  try to run it ag
217b0 61 69 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  ain..** </li>.**
217c0 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65  .** <li>.** ^Whe
217d0 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  n an error occur
217e0 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  s, [sqlite3_step
217f0 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
21800 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69  one of the detai
21810 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f  led.** [error co
21820 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65  des] or [extende
21830 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20  d error codes]. 
21840 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65 68   ^The legacy beh
21850 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a  avior was that.*
21860 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
21870 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65  )] would only re
21880 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b  turn a generic [
21890 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65  SQLITE_ERROR] re
218a0 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64  sult code.** and
218b0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
218c0 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d   would have to m
218d0 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c  ake a second cal
218e0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  l to [sqlite3_re
218f0 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64  set()].** in ord
21900 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75  er to find the u
21910 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20  nderlying cause 
21920 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20  of the problem. 
21930 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72  With the "v2" pr
21940 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61  epare.** interfa
21950 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79  ces, the underly
21960 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74  ing reason for t
21970 68 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  he error is retu
21980 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  rned immediately
21990 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  ..** </li>.**.**
219a0 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65   <li>.** ^If the
219b0 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20   specific value 
219c0 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65  bound to [parame
219d0 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d  ter | host param
219e0 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a  eter] in the .**
219f0 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69   WHERE clause mi
21a00 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68  ght influence th
21a10 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72  e choice of quer
21a20 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61  y plan for a sta
21a30 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20  tement,.** then 
21a40 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69  the statement wi
21a50 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61  ll be automatica
21a60 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20  lly recompiled, 
21a70 61 73 20 69 66 20 74 68 65 72 65 20 68 61 64 20  as if there had 
21a80 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d  been .** a schem
21a90 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65  a change, on the
21aa0 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33   first  [sqlite3
21ab0 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f  _step()] call fo
21ac0 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e  llowing any chan
21ad0 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  ge.** to the [sq
21ae0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20  lite3_bind_text 
21af0 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74  | bindings] of t
21b00 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e  hat [parameter].
21b10 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66   .** ^The specif
21b20 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52  ic value of WHER
21b30 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65  E-clause [parame
21b40 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75  ter] might influ
21b50 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f  ence the .** cho
21b60 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61  ice of query pla
21b70 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  n if the paramet
21b80 65 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68  er is the left-h
21b90 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c  and side of a [L
21ba0 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42  IKE].** or [GLOB
21bb0 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66  ] operator or if
21bc0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
21bd0 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e  s compared to an
21be0 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a   indexed column.
21bf0 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49  ** and the [SQLI
21c00 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 32 5d  TE_ENABLE_STAT2]
21c10 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
21c20 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e  tion is enabled.
21c30 0a 2a 2a 20 74 68 65 20 0a 2a 2a 20 3c 2f 6c 69  .** the .** </li
21c40 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e  >.** </ol>.*/.in
21c50 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
21c60 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  e(.  sqlite3 *db
21c70 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
21c80 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
21c90 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
21ca0 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
21cb0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
21cc0 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
21cd0 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
21ce0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
21cf0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
21d00 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
21d10 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
21d20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
21d30 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
21d40 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
21d50 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
21d60 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
21d70 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
21d80 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
21d90 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
21da0 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74  pare_v2(.  sqlit
21db0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
21dc0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
21dd0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
21de0 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
21df0 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
21e00 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64  ent, UTF-8 encod
21e10 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
21e20 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
21e30 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
21e40 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
21e50 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
21e60 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
21e70 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
21e80 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
21e90 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61  onst char **pzTa
21ea0 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
21eb0 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
21ec0 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
21ed0 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
21ee0 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20  e3_prepare16(.  
21ef0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
21f00 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
21f10 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
21f20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c  const void *zSql
21f30 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
21f40 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36  tatement, UTF-16
21f50 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
21f60 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
21f70 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
21f80 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
21f90 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
21fa0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
21fb0 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
21fc0 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
21fd0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
21fe0 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
21ff0 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
22000 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
22010 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
22020 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
22030 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  16_v2(.  sqlite3
22040 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
22050 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
22060 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
22070 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
22080 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
22090 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
220a0 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
220b0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
220c0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
220d0 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
220e0 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
220f0 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
22100 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
22110 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
22120 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69  nst void **pzTai
22130 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
22140 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
22150 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
22160 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
22170 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e  I3REF: Retrievin
22180 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a  g Statement SQL.
22190 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65  **.** ^This inte
221a0 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
221b0 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 61 20  d to retrieve a 
221c0 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68  saved copy of th
221d0 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51  e original.** SQ
221e0 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 63  L text used to c
221f0 72 65 61 74 65 20 61 20 5b 70 72 65 70 61 72 65  reate a [prepare
22200 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20  d statement] if 
22210 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77  that statement w
22220 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75  as.** compiled u
22230 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c  sing either [sql
22240 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
22250 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
22260 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a  repare16_v2()]..
22270 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
22280 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74  qlite3_sql(sqlit
22290 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
222a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
222b0 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
222c0 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
222d0 57 72 69 74 65 73 20 54 68 65 20 44 61 74 61 62  Writes The Datab
222e0 61 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ase.**.** ^The s
222f0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
22300 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66 61 63  only(X) interfac
22310 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28  e returns true (
22320 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20  non-zero) if.** 
22330 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  and only if the 
22340 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
22350 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20  ent] X makes no 
22360 64 69 72 65 63 74 20 63 68 61 6e 67 65 73 20 74  direct changes t
22370 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74  o.** the content
22380 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
22390 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74   file..**.** Not
223a0 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63 61 74  e that [applicat
223b0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
223c0 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a  functions] or.**
223d0 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73   [virtual tables
223e0 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74  ] might change t
223f0 68 65 20 64 61 74 61 62 61 73 65 20 69 6e 64 69  he database indi
22400 72 65 63 74 6c 79 20 61 73 20 61 20 73 69 64 65  rectly as a side
22410 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28   effect.  .** ^(
22420 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20  For example, if 
22430 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  an application d
22440 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74 69 6f  efines a functio
22450 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61 74 20  n "eval()" that 
22460 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74  .** calls [sqlit
22470 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68 65 6e  e3_exec()], then
22480 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53   the following S
22490 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75  QL statement wou
224a0 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65  ld.** change the
224b0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74   database file t
224c0 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66 66 65  hrough side-effe
224d0 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  cts:.**.** <bloc
224e0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
224f0 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c 28 27     SELECT eval('
22500 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31 27 29  DELETE FROM t1')
22510 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70   FROM t2;.** </p
22520 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
22530 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61 75  .**.** But becau
22540 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20  se the [SELECT] 
22550 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e  statement does n
22560 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61  ot change the da
22570 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64  tabase file.** d
22580 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74 65 33  irectly, sqlite3
22590 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29  _stmt_readonly()
225a0 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65 74   would still ret
225b0 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a  urn true.)^.**.*
225c0 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20 63  * ^Transaction c
225d0 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74  ontrol statement
225e0 73 20 73 75 63 68 20 61 73 20 5b 42 45 47 49 4e  s such as [BEGIN
225f0 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f  ], [COMMIT], [RO
22600 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56  LLBACK],.** [SAV
22610 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45  EPOINT], and [RE
22620 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73 71 6c  LEASE] cause sql
22630 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
22640 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74  ly() to return t
22650 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68  rue,.** since th
22660 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 65  e statements the
22670 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61  mselves do not a
22680 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74  ctually modify t
22690 68 65 20 64 61 74 61 62 61 73 65 20 62 75 74 0a  he database but.
226a0 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79 20 63  ** rather they c
226b0 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e  ontrol the timin
226c0 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65 72 20  g of when other 
226d0 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66  statements modif
226e0 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61 62 61  y the .** databa
226f0 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54 41 43  se.  ^The [ATTAC
22700 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48 5d 20  H] and [DETACH] 
22710 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20  statements also 
22720 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33  cause.** sqlite3
22730 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29  _stmt_readonly()
22740 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 20   to return true 
22750 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74 68 6f  since, while tho
22760 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  se statements.**
22770 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f 6e 66   change the conf
22780 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 64  iguration of a d
22790 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
227a0 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74 20  on, they do not 
227b0 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73  make .** changes
227c0 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 20   to the content 
227d0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
227e0 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a  files on disk..*
227f0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  /.int sqlite3_st
22800 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69  mt_readonly(sqli
22810 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
22820 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
22830 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54  F: Dynamically T
22840 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63  yped Value Objec
22850 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  t.** KEYWORDS: {
22860 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
22870 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74  3_value} {unprot
22880 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
22890 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  lue}.**.** SQLit
228a0 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74  e uses the sqlit
228b0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
228c0 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c  to represent all
228d0 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20   values.** that 
228e0 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e  can be stored in
228f0 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c   a database tabl
22900 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64  e. SQLite uses d
22910 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a  ynamic typing.**
22920 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20   for the values 
22930 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c  it stores.  ^Val
22940 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71  ues stored in sq
22950 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
22960 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e  cts.** can be in
22970 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67  tegers, floating
22980 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73   point values, s
22990 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f  trings, BLOBs, o
229a0 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e  r NULL..**.** An
229b0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
229c0 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74  bject may be eit
229d0 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20  her "protected" 
229e0 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22  or "unprotected"
229f0 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66  ..** Some interf
22a00 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70  aces require a p
22a10 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
22a20 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69  _value.  Other i
22a30 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c  nterfaces.** wil
22a40 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20  l accept either 
22a50 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61  a protected or a
22a60 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
22a70 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20  lite3_value..** 
22a80 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20  Every interface 
22a90 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c  that accepts sql
22aa0 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d  ite3_value argum
22ab0 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a  ents specifies.*
22ac0 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  * whether or not
22ad0 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70   it requires a p
22ae0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
22af0 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  _value..**.** Th
22b00 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74  e terms "protect
22b10 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65  ed" and "unprote
22b20 63 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77  cted" refer to w
22b30 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a  hether or not.**
22b40 20 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64   a mutex is held
22b50 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d  .  An internal m
22b60 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72  utex is held for
22b70 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   a protected.** 
22b80 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
22b90 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65  ject but no mute
22ba0 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e  x is held for an
22bb0 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
22bc0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
22bd0 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65  ject.  If SQLite
22be0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20   is compiled to 
22bf0 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  be single-thread
22c00 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c  ed.** (with [SQL
22c10 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
22c20 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69  ] and with [sqli
22c30 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
22c40 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a  ] returning 0).*
22c50 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69  * or if SQLite i
22c60 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20  s run in one of 
22c70 72 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f  reduced mutex mo
22c80 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  des .** [SQLITE_
22c90 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
22ca0 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  EAD] or [SQLITE_
22cb0 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
22cc0 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72  AD].** then ther
22cd0 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74  e is no distinct
22ce0 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74  ion between prot
22cf0 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74  ected and unprot
22d00 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
22d10 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61  _value objects a
22d20 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75  nd they can be u
22d30 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61  sed interchangea
22d40 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a  bly.  However,.*
22d50 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f  * for maximum co
22d60 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69  de portability i
22d70 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
22d80 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f   that applicatio
22d90 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65  ns.** still make
22da0 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e   the distinction
22db0 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74   between protect
22dc0 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74  ed and unprotect
22dd0 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
22de0 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e  lue objects even
22df0 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74   when not strict
22e00 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  ly required..**.
22e10 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
22e20 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68  value objects th
22e30 61 74 20 61 72 65 20 70 61 73 73 65 64 20 61 73  at are passed as
22e40 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f   parameters into
22e50 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   the.** implemen
22e60 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69  tation of [appli
22e70 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
22e80 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72  QL functions] ar
22e90 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20  e protected..** 
22ea0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
22eb0 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ue object return
22ec0 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
22ed0 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
22ee0 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64  ] is unprotected
22ef0 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64  ..** Unprotected
22f00 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
22f10 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20  bjects may only 
22f20 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20  be used with.** 
22f30 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
22f40 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71  value()] and [sq
22f50 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
22f60 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  ()]..** The [sql
22f70 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20  ite3_value_blob 
22f80 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  | sqlite3_value_
22f90 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f  type()] family o
22fa0 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  f.** interfaces 
22fb0 72 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65  require protecte
22fc0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
22fd0 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65  objects..*/.type
22fe0 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73  def struct Mem s
22ff0 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f  qlite3_value;../
23000 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
23010 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74  QL Function Cont
23020 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ext Object.**.**
23030 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20   The context in 
23040 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e  which an SQL fun
23050 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69  ction executes i
23060 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a  s stored in an.*
23070 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  * sqlite3_contex
23080 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f  t object.  ^A po
23090 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69  inter to an sqli
230a0 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65  te3_context obje
230b0 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20  ct.** is always 
230c0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
230d0 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  to [application-
230e0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
230f0 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61  tions]..** The a
23100 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
23110 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ed SQL function 
23120 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
23130 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a  ill pass this.**
23140 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68   pointer through
23150 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b   into calls to [
23160 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
23170 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73  nt | sqlite3_res
23180 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ult()],.** [sqli
23190 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
231a0 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74  ntext()], [sqlit
231b0 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c  e3_user_data()],
231c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
231d0 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29  text_db_handle()
231e0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  ], [sqlite3_get_
231f0 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61  auxdata()],.** a
23200 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73  nd/or [sqlite3_s
23210 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a  et_auxdata()]..*
23220 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
23230 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
23240 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
23250 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
23260 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65  F: Binding Value
23270 73 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74  s To Prepared St
23280 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57  atements.** KEYW
23290 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61  ORDS: {host para
232a0 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72  meter} {host par
232b0 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70  ameters} {host p
232c0 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a  arameter name}.*
232d0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c  * KEYWORDS: {SQL
232e0 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c   parameter} {SQL
232f0 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61   parameters} {pa
23300 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d  rameter binding}
23310 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20  .**.** ^(In the 
23320 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  SQL statement te
23330 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  xt input to [sql
23340 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
23350 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61  )] and its varia
23360 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73  nts,.** literals
23370 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64   may be replaced
23380 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72   by a [parameter
23390 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f  ] that matches o
233a0 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a  ne of following.
233b0 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a  ** templates:.**
233c0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
233d0 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e    ?.** <li>  ?NN
233e0 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a  N.** <li>  :VVV.
233f0 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a  ** <li>  @VVV.**
23400 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c   <li>  $VVV.** <
23410 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68  /ul>.**.** In th
23420 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76  e templates abov
23430 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74  e, NNN represent
23440 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74  s an integer lit
23450 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56  eral,.** and VVV
23460 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61   represents an a
23470 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e  lphanumeric iden
23480 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20  tifier.)^  ^The 
23490 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a  values of these.
234a0 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 61  ** parameters (a
234b0 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74  lso called "host
234c0 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73   parameter names
234d0 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65  " or "SQL parame
234e0 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65  ters").** can be
234f0 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73   set using the s
23500 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
23510 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64  routines defined
23520 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   here..**.** ^Th
23530 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
23540 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
23550 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
23560 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61  s is always.** a
23570 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
23580 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f  [sqlite3_stmt] o
23590 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66  bject returned f
235a0 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  rom.** [sqlite3_
235b0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
235c0 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a   its variants..*
235d0 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64  *.** ^The second
235e0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
235f0 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51   index of the SQ
23600 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  L parameter to b
23610 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c  e set..** ^The l
23620 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61  eftmost SQL para
23630 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64  meter has an ind
23640 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20  ex of 1.  ^When 
23650 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a  the same named.*
23660 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  * SQL parameter 
23670 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61  is used more tha
23680 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61  n once, second a
23690 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a  nd subsequent.**
236a0 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76   occurrences hav
236b0 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78  e the same index
236c0 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63   as the first oc
236d0 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68  currence..** ^Th
236e0 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65  e index for name
236f0 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e  d parameters can
23700 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73   be looked up us
23710 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ing the.** [sqli
23720 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
23730 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20  er_index()] API 
23740 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68  if desired.  ^Th
23750 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22  e index.** for "
23760 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73  ?NNN" parameters
23770 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
23780 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e   NNN..** ^The NN
23790 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20  N value must be 
237a0 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68  between 1 and th
237b0 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  e [sqlite3_limit
237c0 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ()].** parameter
237d0 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56   [SQLITE_LIMIT_V
237e0 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20  ARIABLE_NUMBER] 
237f0 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20  (default value: 
23800 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  999)..**.** ^The
23810 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
23820 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20  is the value to 
23830 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61  bind to the para
23840 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  meter..**.** ^(I
23850 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73  n those routines
23860 20 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75   that have a fou
23870 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74  rth argument, it
23880 73 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a  s value is the.*
23890 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  * number of byte
238a0 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74  s in the paramet
238b0 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72  er.  To be clear
238c0 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74  : the value is t
238d0 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
238e0 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20  <u>bytes</u> in 
238f0 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74  the value, not t
23900 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
23910 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49  racters.)^.** ^I
23920 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
23930 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74 69  ameter is negati
23940 76 65 2c 20 74 68 65 20 6c 65 6e 67 74 68 20 6f  ve, the length o
23950 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a  f the string is.
23960 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
23970 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65   bytes up to the
23980 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d   first zero term
23990 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  inator..**.** ^T
239a0 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
239b0 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  t to sqlite3_bin
239c0 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65  d_blob(), sqlite
239d0 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61  3_bind_text(), a
239e0 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69  nd.** sqlite3_bi
239f0 6e 64 5f 74 65 78 74 31 36 28 29 20 69 73 20 61  nd_text16() is a
23a00 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64   destructor used
23a10 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74   to dispose of t
23a20 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74  he BLOB or.** st
23a30 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74  ring after SQLit
23a40 65 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  e has finished w
23a50 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65  ith it.  ^The de
23a60 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c  structor is call
23a70 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65  ed.** to dispose
23a80 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20   of the BLOB or 
23a90 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74  string even if t
23aa0 68 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  he call to sqlit
23ab0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 0a  e3_bind_blob(),.
23ac0 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ** sqlite3_bind_
23ad0 74 65 78 74 28 29 2c 20 6f 72 20 73 71 6c 69 74  text(), or sqlit
23ae0 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29  e3_bind_text16()
23af0 20 66 61 69 6c 73 2e 20 20 0a 2a 2a 20 5e 49 66   fails.  .** ^If
23b00 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
23b10 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70  ent is.** the sp
23b20 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c  ecial value [SQL
23b30 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65  ITE_STATIC], the
23b40 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73  n SQLite assumes
23b50 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66   that the.** inf
23b60 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73  ormation is in s
23b70 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64  tatic, unmanaged
23b80 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20   space and does 
23b90 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66  not need to be f
23ba0 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  reed..** ^If the
23bb0 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
23bc0 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53  has the value [S
23bd0 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d  QLITE_TRANSIENT]
23be0 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65  , then.** SQLite
23bf0 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70   makes its own p
23c00 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
23c10 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74  he data immediat
23c20 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74  ely, before.** t
23c30 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
23c40 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  *() routine retu
23c50 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rns..**.** ^The 
23c60 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
23c70 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20  oblob() routine 
23c80 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20  binds a BLOB of 
23c90 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a  length N that.**
23ca0 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
23cb0 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f  zeroes.  ^A zero
23cc0 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65  blob uses a fixe
23cd0 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f  d amount of memo
23ce0 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69  ry.** (just an i
23cf0 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69  nteger to hold i
23d00 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69  ts size) while i
23d10 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65  t is being proce
23d20 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f  ssed..** Zeroblo
23d30 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  bs are intended 
23d40 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63  to serve as plac
23d50 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f  eholders for BLO
23d60 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74  Bs whose.** cont
23d70 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69  ent is later wri
23d80 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  tten using.** [s
23d90 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
23da0 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42   | incremental B
23db0 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65  LOB I/O] routine
23dc0 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76  s..** ^A negativ
23dd0 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20  e value for the 
23de0 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73  zeroblob results
23df0 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74   in a zero-lengt
23e00 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49  h BLOB..**.** ^I
23e10 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c  f any of the sql
23e20 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
23e30 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
23e40 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f  d with a NULL po
23e50 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65  inter.** for the
23e60 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
23e70 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20  ment] or with a 
23e80 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
23e90 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20  nt for which.** 
23ea0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
23eb0 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64   has been called
23ec0 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74   more recently t
23ed0 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  han [sqlite3_res
23ee0 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74  et()],.** then t
23ef0 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74  he call will ret
23f00 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  urn [SQLITE_MISU
23f10 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c  SE].  If any sql
23f20 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20  ite3_bind_().** 
23f30 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73 65  routine is passe
23f40 64 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  d a [prepared st
23f50 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61  atement] that ha
23f60 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64  s been finalized
23f70 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  , the.** result 
23f80 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
23f90 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75   probably harmfu
23fa0 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e  l..**.** ^Bindin
23fb0 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72  gs are not clear
23fc0 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
23fd0 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74  e3_reset()] rout
23fe0 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64  ine..** ^Unbound
23ff0 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
24000 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e  interpreted as N
24010 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ULL..**.** ^The 
24020 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72  sqlite3_bind_* r
24030 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b  outines return [
24040 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75  SQLITE_OK] on su
24050 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b  ccess or an.** [
24060 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61  error code] if a
24070 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f  nything goes wro
24080 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  ng..** ^[SQLITE_
24090 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e  RANGE] is return
240a0 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  ed if the parame
240b0 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20  ter.** index is 
240c0 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e  out of range.  ^
240d0 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69  [SQLITE_NOMEM] i
240e0 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61  s returned if ma
240f0 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a  lloc() fails..**
24100 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
24110 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
24120 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a  meter_count()],.
24130 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
24140 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
24150 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
24160 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
24170 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  index()]..*/.int
24180 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
24190 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
241a0 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
241b0 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28  d*, int n, void(
241c0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
241d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75  sqlite3_bind_dou
241e0 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ble(sqlite3_stmt
241f0 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b  *, int, double);
24200 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
24210 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  d_int(sqlite3_st
24220 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a  mt*, int, int);.
24230 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
24240 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73  _int64(sqlite3_s
24250 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74  tmt*, int, sqlit
24260 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73  e3_int64);.int s
24270 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c  qlite3_bind_null
24280 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
24290 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  int);.int sqlite
242a0 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69  3_bind_text(sqli
242b0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
242c0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
242d0 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   n, void(*)(void
242e0 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
242f0 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c  _bind_text16(sql
24300 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
24310 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
24320 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
24330 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
24340 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74  bind_value(sqlit
24350 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
24360 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  onst sqlite3_val
24370 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
24380 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28  3_bind_zeroblob(
24390 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
243a0 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a  nt, int n);../*.
243b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
243c0 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d  ber Of SQL Param
243d0 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  eters.**.** ^Thi
243e0 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65  s routine can be
243f0 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68   used to find th
24400 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c  e number of [SQL
24410 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20   parameters].** 
24420 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  in a [prepared s
24430 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20  tatement].  SQL 
24440 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74  parameters are t
24450 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20  okens of the.** 
24460 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22  form "?", "?NNN"
24470 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22  , ":AAA", "$AAA"
24480 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74  , or "@AAA" that
24490 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61   serve as.** pla
244a0 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61  ceholders for va
244b0 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73  lues that are [s
244c0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
244d0 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20   | bound].** to 
244e0 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61  the parameters a
244f0 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a  t a later time..
24500 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75  **.** ^(This rou
24510 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65  tine actually re
24520 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20  turns the index 
24530 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28  of the largest (
24540 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61  rightmost).** pa
24550 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c  rameter. For all
24560 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e   forms except ?N
24570 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f  NN, this will co
24580 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a  rrespond to the.
24590 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69  ** number of uni
245a0 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20  que parameters. 
245b0 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f   If parameters o
245c0 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20  f the ?NNN form 
245d0 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65  are used,.** the
245e0 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69  re may be gaps i
245f0 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a  n the list.)^.**
24600 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
24610 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
24620 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
24630 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
24640 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
24650 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  e()], and.** [sq
24660 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
24670 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
24680 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  /.int sqlite3_bi
24690 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
246a0 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
246b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
246c0 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f  EF: Name Of A Ho
246d0 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a  st Parameter.**.
246e0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
246f0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
24700 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61  ame(P,N) interfa
24710 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68  ce returns.** th
24720 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d  e name of the N-
24730 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  th [SQL paramete
24740 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61  r] in the [prepa
24750 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50  red statement] P
24760 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d  ..** ^(SQL param
24770 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72  eters of the for
24780 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41  m "?NNN" or ":AA
24790 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20  A" or "@AAA" or 
247a0 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61  "$AAA".** have a
247b0 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20 74   name which is t
247c0 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22  he string "?NNN"
247d0 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40   or ":AAA" or "@
247e0 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a  AAA" or "$AAA".*
247f0 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  * respectively..
24800 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  ** In other word
24810 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22  s, the initial "
24820 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22  :" or "$" or "@"
24830 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e   or "?".** is in
24840 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 6f  cluded as part o
24850 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a  f the name.)^.**
24860 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20   ^Parameters of 
24870 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74  the form "?" wit
24880 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67  hout a following
24890 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f   integer have no
248a0 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65   name.** and are
248b0 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73 20   referred to as 
248c0 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61  "nameless" or "a
248d0 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74  nonymous paramet
248e0 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ers"..**.** ^The
248f0 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72 61   first host para
24900 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64  meter has an ind
24910 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a  ex of 1, not 0..
24920 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61  **.** ^If the va
24930 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20  lue N is out of 
24940 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20  range or if the 
24950 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  N-th parameter i
24960 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74  s.** nameless, t
24970 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75  hen NULL is retu
24980 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75  rned.  ^The retu
24990 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a  rned string is.*
249a0 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d  * always in UTF-
249b0 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20  8 encoding even 
249c0 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72  if the named par
249d0 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72  ameter was.** or
249e0 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69  iginally specifi
249f0 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  ed as UTF-16 in 
24a00 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
24a10 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  16()] or.** [sql
24a20 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
24a30 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  2()]..**.** See 
24a40 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
24a50 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
24a60 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
24a70 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
24a80 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61  eter_count()], a
24a90 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
24aa0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
24ab0 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74  dex()]..*/.const
24ac0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62   char *sqlite3_b
24ad0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
24ae0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
24af0 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , int);../*.** C
24b00 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f  API3REF: Index O
24b10 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69  f A Parameter Wi
24b20 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a  th A Given Name.
24b30 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68  **.** ^Return th
24b40 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51  e index of an SQ
24b50 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 65  L parameter give
24b60 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68  n its name.  ^Th
24b70 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65  e.** index value
24b80 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69   returned is sui
24b90 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73  table for use as
24ba0 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70   the second.** p
24bb0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
24bc0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
24bd0 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20  qlite3_bind()]. 
24be0 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72   ^A zero.** is r
24bf0 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61  eturned if no ma
24c00 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72  tching parameter
24c10 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65   is found.  ^The
24c20 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61   parameter.** na
24c30 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e  me must be given
24c40 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69   in UTF-8 even i
24c50 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73  f the original s
24c60 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20  tatement.** was 
24c70 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54  prepared from UT
24c80 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20  F-16 text using 
24c90 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
24ca0 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  16_v2()]..**.** 
24cb0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
24cc0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
24cd0 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
24ce0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
24cf0 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
24d00 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
24d10 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
24d20 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69  r_index()]..*/.i
24d30 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
24d40 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
24d50 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63  sqlite3_stmt*, c
24d60 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
24d70 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
24d80 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69  EF: Reset All Bi
24d90 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70  ndings On A Prep
24da0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a  ared Statement.*
24db0 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74  *.** ^Contrary t
24dc0 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20  o the intuition 
24dd0 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65  of many, [sqlite
24de0 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20  3_reset()] does 
24df0 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65  not reset.** the
24e00 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
24e10 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20  lob | bindings] 
24e20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  on a [prepared s
24e30 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55  tatement]..** ^U
24e40 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  se this routine 
24e50 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73  to reset all hos
24e60 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  t parameters to 
24e70 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  NULL..*/.int sql
24e80 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69  ite3_clear_bindi
24e90 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ngs(sqlite3_stmt
24ea0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
24eb0 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43  REF: Number Of C
24ec0 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75  olumns In A Resu
24ed0 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65  lt Set.**.** ^Re
24ee0 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20  turn the number 
24ef0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
24f00 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74  e result set ret
24f10 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  urned by the.** 
24f20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
24f30 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74  ent]. ^This rout
24f40 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66  ine returns 0 if
24f50 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c   pStmt is an SQL
24f60 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68  .** statement th
24f70 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75  at does not retu
24f80 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78 61  rn data (for exa
24f90 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d  mple an [UPDATE]
24fa0 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )..**.** See als
24fb0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61  o: [sqlite3_data
24fc0 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74  _count()].*/.int
24fd0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
24fe0 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
24ff0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
25000 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c  ** CAPI3REF: Col
25010 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52  umn Names In A R
25020 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20  esult Set.**.** 
25030 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
25040 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20  return the name 
25050 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61  assigned to a pa
25060 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a  rticular column.
25070 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ** in the result
25080 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43   set of a [SELEC
25090 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  T] statement.  ^
250a0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
250b0 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74  mn_name().** int
250c0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
250d0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65   pointer to a ze
250e0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
250f0 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e  F-8 string.** an
25100 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
25110 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e  _name16() return
25120 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
25130 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
25140 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e  .** UTF-16 strin
25150 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 70  g.  ^The first p
25160 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
25170 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
25180 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70  ent].** that imp
25190 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c  lements the [SEL
251a0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20  ECT] statement. 
251b0 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
251c0 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
251d0 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20  column number.  
251e0 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f  ^The leftmost co
251f0 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30  lumn is number 0
25200 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ..**.** ^The ret
25210 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69  urned string poi
25220 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e  nter is valid un
25230 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b  til either the [
25240 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
25250 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f  nt].** is destro
25260 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  yed by [sqlite3_
25270 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75  finalize()] or u
25280 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65  ntil the stateme
25290 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61  nt is automatica
252a0 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65  lly.** reprepare
252b0 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63  d by the first c
252c0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
252d0 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61  step()] for a pa
252e0 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20  rticular run.** 
252f0 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78  or until the nex
25300 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c  t call to.** sql
25310 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
25320 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  () or sqlite3_co
25330 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e  lumn_name16() on
25340 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e   the same column
25350 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ..**.** ^If sqli
25360 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69  te3_malloc() fai
25370 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72  ls during the pr
25380 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68  ocessing of eith
25390 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66  er routine.** (f
253a0 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e  or example durin
253b0 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66  g a conversion f
253c0 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46  rom UTF-8 to UTF
253d0 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e  -16) then a.** N
253e0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
253f0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
25400 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65  The name of a re
25410 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74  sult column is t
25420 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
25430 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a  "AS" clause for.
25440 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20  ** that column, 
25450 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41  if there is an A
25460 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68  S clause.  If th
25470 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61  ere is no AS cla
25480 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  use.** then the 
25490 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75  name of the colu
254a0 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65  mn is unspecifie
254b0 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65  d and may change
254c0 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c   from.** one rel
254d0 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74  ease of SQLite t
254e0 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63  o the next..*/.c
254f0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
25500 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73  e3_column_name(s
25510 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
25520 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  t N);.const void
25530 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
25540 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
25550 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a  stmt*, int N);..
25560 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
25570 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49  Source Of Data I
25580 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74  n A Query Result
25590 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
255a0 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61  utines provide a
255b0 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d   means to determ
255c0 69 6e 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ine the database
255d0 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20  , table, and.** 
255e0 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61  table column tha
255f0 74 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20  t is the origin 
25600 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  of a particular 
25610 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e  result column in
25620 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  .** [SELECT] sta
25630 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  tement..** ^The 
25640 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
25650 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72  base or table or
25660 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72   column can be r
25670 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69  eturned as.** ei
25680 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20  ther a UTF-8 or 
25690 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20  UTF-16 string.  
256a0 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20  ^The _database_ 
256b0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a  routines return.
256c0 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
256d0 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65  name, the _table
256e0 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
256f0 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65  n the table name
25700 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69  , and.** the ori
25710 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  gin_ routines re
25720 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20  turn the column 
25730 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65  name..** ^The re
25740 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
25750 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65   valid until the
25760 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
25770 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79  ment] is destroy
25780 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c  ed.** using [sql
25790 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
257a0 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74   or until the st
257b0 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d  atement is autom
257c0 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72  atically.** repr
257d0 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69  epared by the fi
257e0 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  rst call to [sql
257f0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72  ite3_step()] for
25800 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75   a particular ru
25810 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68  n.** or until th
25820 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69  e same informati
25830 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a  on is requested.
25840 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69  ** again in a di
25850 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67  fferent encoding
25860 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ..**.** ^The nam
25870 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20  es returned are 
25880 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d  the original un-
25890 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66  aliased names of
258a0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
258b0 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c  , table, and col
258c0 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  umn..**.** ^The 
258d0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
258e0 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  o these interfac
258f0 65 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65  es is a [prepare
25900 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
25910 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e   ^These function
25920 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61  s return informa
25930 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e  tion about the N
25940 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  th result column
25950 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
25960 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77  the statement, w
25970 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65  here N is the se
25980 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72  cond function ar
25990 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  gument..** ^The 
259a0 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e  left-most column
259b0 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72   is column 0 for
259c0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
259d0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e  .**.** ^If the N
259e0 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e  th column return
259f0 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d  ed by the statem
25a00 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73  ent is an expres
25a10 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75  sion or.** subqu
25a20 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ery and is not a
25a30 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74   column value, t
25a40 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65  hen all of these
25a50 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
25a60 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65  n.** NULL.  ^The
25a70 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74  se routine might
25a80 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c   also return NUL
25a90 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  L if a memory al
25aa0 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a  location error.*
25ab0 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65  * occurs.  ^Othe
25ac0 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75  rwise, they retu
25ad0 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  rn the name of t
25ae0 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61  he attached data
25af0 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20  base, table,.** 
25b00 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71  or column that q
25b10 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75  uery result colu
25b20 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64  mn was extracted
25b30 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73   from..**.** ^As
25b40 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20   with all other 
25b50 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f  SQLite APIs, tho
25b60 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65  se whose names e
25b70 6e 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74  nd with "16" ret
25b80 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e  urn.** UTF-16 en
25b90 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e  coded strings an
25ba0 64 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63  d the other func
25bb0 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46  tions return UTF
25bc0 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  -8..**.** ^These
25bd0 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61   APIs are only a
25be0 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20  vailable if the 
25bf0 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70  library was comp
25c00 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  iled with the.**
25c10 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
25c20 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d  COLUMN_METADATA]
25c30 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C-preprocessor 
25c40 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66  symbol..**.** If
25c50 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72   two or more thr
25c60 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72  eads call one or
25c70 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72   more of these r
25c80 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20  outines against 
25c90 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70  the same.** prep
25ca0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61  ared statement a
25cb0 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65  nd column at the
25cc0 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20   same time then 
25cd0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a  the results are.
25ce0 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  ** undefined..**
25cf0 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f  .** If two or mo
25d00 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20  re threads call 
25d10 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b  one or more.** [
25d20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
25d30 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63  atabase_name | c
25d40 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69  olumn metadata i
25d50 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f  nterfaces].** fo
25d60 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70  r the same [prep
25d70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
25d80 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  and result colum
25d90 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65  n.** at the same
25da0 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72   time then the r
25db0 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
25dc0 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  ined..*/.const c
25dd0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
25de0 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
25df0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
25e00 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
25e10 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
25e20 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36  _database_name16
25e30 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
25e40 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  nt);.const char 
25e50 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
25e60 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74  table_name(sqlit
25e70 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
25e80 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
25e90 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
25ea0 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
25eb0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
25ec0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
25ed0 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d  olumn_origin_nam
25ee0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
25ef0 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
25f00 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
25f10 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73  _origin_name16(s
25f20 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
25f30 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
25f40 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74  EF: Declared Dat
25f50 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79  atype Of A Query
25f60 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28   Result.**.** ^(
25f70 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
25f80 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72  ter is a [prepar
25f90 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
25fa0 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d  * If this statem
25fb0 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54  ent is a [SELECT
25fc0 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  ] statement and 
25fd0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
25fe0 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65  f the.** returne
25ff0 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  d result set of 
26000 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73  that [SELECT] is
26010 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20   a table column 
26020 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65  (not an.** expre
26030 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72  ssion or subquer
26040 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c  y) then the decl
26050 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65  ared type of the
26060 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e   table.** column
26070 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20   is returned.)^ 
26080 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c   ^If the Nth col
26090 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
260a0 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65  t set is an.** e
260b0 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
260c0 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55  query, then a NU
260d0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
260e0 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  turned..** ^The 
260f0 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
26100 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20  is always UTF-8 
26110 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  encoded..**.** ^
26120 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69  (For example, gi
26130 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  ven the database
26140 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43   schema:.**.** C
26150 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63  REATE TABLE t1(c
26160 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a  1 VARIANT);.**.*
26170 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77  * and the follow
26180 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  ing statement to
26190 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a   be compiled:.**
261a0 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20  .** SELECT c1 + 
261b0 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a  1, c1 FROM t1;.*
261c0 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e  *.** this routin
261d0 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74  e would return t
261e0 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41  he string "VARIA
261f0 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f  NT" for the seco
26200 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c  nd result.** col
26210 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20  umn (i==1), and 
26220 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66  a NULL pointer f
26230 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73  or the first res
26240 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30  ult column (i==0
26250 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  ).)^.**.** ^SQLi
26260 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
26270 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e  run-time typing.
26280 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75    ^So just becau
26290 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  se a column.** i
262a0 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f  s declared to co
262b0 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c  ntain a particul
262c0 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74  ar type does not
262d0 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a   mean that the.*
262e0 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e  * data stored in
262f0 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20   that column is 
26300 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  of the declared 
26310 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73  type.  SQLite is
26320 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70  .** strongly typ
26330 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69  ed, but the typi
26340 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f  ng is dynamic no
26350 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65  t static.  ^Type
26360 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65  .** is associate
26370 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61  d with individua
26380 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69  l values, not wi
26390 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72  th the container
263a0 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c  s.** used to hol
263b0 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a  d those values..
263c0 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
263d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
263e0 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73  cltype(sqlite3_s
263f0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
26400 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
26410 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36  olumn_decltype16
26420 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
26430 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
26440 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41  3REF: Evaluate A
26450 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a  n SQL Statement.
26460 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70  **.** After a [p
26470 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
26480 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70  t] has been prep
26490 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 65  ared using eithe
264a0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  r.** [sqlite3_pr
264b0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
264c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
264d0 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f  6_v2()] or one o
264e0 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  f the legacy.** 
264f0 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69  interfaces [sqli
26500 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
26510 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
26520 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75  re16()], this fu
26530 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62  nction.** must b
26540 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20  e called one or 
26550 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76  more times to ev
26560 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65  aluate the state
26570 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ment..**.** The 
26580 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62  details of the b
26590 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73  ehavior of the s
265a0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
265b0 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a  terface depend.*
265c0 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65  * on whether the
265d0 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70   statement was p
265e0 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68  repared using th
265f0 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74  e newer "v2" int
26600 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74  erface.** [sqlit
26610 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
26620 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
26630 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72  epare16_v2()] or
26640 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63   the older legac
26650 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b  y.** interface [
26660 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
26670 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
26680 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54  prepare16()].  T
26690 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a  he use of the.**
266a0 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 66   new "v2" interf
266b0 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ace is recommend
266c0 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69  ed for new appli
266d0 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20  cations but the 
266e0 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
266f0 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75  ace will continu
26700 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  e to be supporte
26710 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65  d..**.** ^In the
26720 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
26730 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  e, the return va
26740 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68  lue will be eith
26750 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  er [SQLITE_BUSY]
26760 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ,.** [SQLITE_DON
26770 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  E], [SQLITE_ROW]
26780 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  , [SQLITE_ERROR]
26790 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53  , or [SQLITE_MIS
267a0 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74  USE]..** ^With t
267b0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
267c0 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74  e, any of the ot
267d0 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  her [result code
267e0 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64  s] or.** [extend
267f0 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
26800 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e   might be return
26810 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a  ed as well..**.*
26820 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  * ^[SQLITE_BUSY]
26830 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
26840 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20  database engine 
26850 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63  was unable to ac
26860 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74  quire the.** dat
26870 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e  abase locks it n
26880 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a  eeds to do its j
26890 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61  ob.  ^If the sta
268a0 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d  tement is a [COM
268b0 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72  MIT].** or occur
268c0 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20  s outside of an 
268d0 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
268e0 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63  tion, then you c
268f0 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20  an retry the.** 
26900 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74  statement.  If t
26910 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
26920 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61  not a [COMMIT] a
26930 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  nd occurs within
26940 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20   an.** explicit 
26950 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e  transaction then
26960 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c   you should roll
26970 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63  back the transac
26980 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63  tion before.** c
26990 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ontinuing..**.**
269a0 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20   ^[SQLITE_DONE] 
269b0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73  means that the s
269c0 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e  tatement has fin
269d0 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a  ished executing.
269e0 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e  ** successfully.
269f0 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
26a00 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
26a10 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74  alled again on t
26a20 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d  his virtual.** m
26a30 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66  achine without f
26a40 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71  irst calling [sq
26a50 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74  lite3_reset()] t
26a60 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74  o reset the virt
26a70 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62  ual.** machine b
26a80 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69  ack to its initi
26a90 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  al state..**.** 
26aa0 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74  ^If the SQL stat
26ab0 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63  ement being exec
26ac0 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79  uted returns any
26ad0 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c   data, then [SQL
26ae0 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72  ITE_ROW].** is r
26af0 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d  eturned each tim
26b00 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64  e a new row of d
26b10 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72  ata is ready for
26b20 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74   processing by t
26b30 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68  he.** caller. Th
26b40 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20  e values may be 
26b50 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74  accessed using t
26b60 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  he [column acces
26b70 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  s functions]..**
26b80 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
26b90 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  is called again 
26ba0 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20  to retrieve the 
26bb0 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61  next row of data
26bc0 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
26bd0 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68  _ERROR] means th
26be0 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72  at a run-time er
26bf0 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63  ror (such as a c
26c00 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f  onstraint.** vio
26c10 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75  lation) has occu
26c20 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73  rred.  sqlite3_s
26c30 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74  tep() should not
26c40 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   be called again
26c50 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d   on.** the VM. M
26c60 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ore information 
26c70 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20  may be found by 
26c80 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
26c90 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e  _errmsg()]..** ^
26ca0 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20  With the legacy 
26cb0 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72  interface, a mor
26cc0 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
26cd0 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70   code (for examp
26ce0 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  le,.** [SQLITE_I
26cf0 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49  NTERRUPT], [SQLI
26d00 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c  TE_SCHEMA], [SQL
26d10 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e  ITE_CORRUPT], an
26d20 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63  d so forth).** c
26d30 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62  an be obtained b
26d40 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
26d50 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74  e3_reset()] on t
26d60 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
26d70 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e  statement].  ^In
26d80 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
26d90 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65  ace,.** the more
26da0 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20   specific error 
26db0 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64  code is returned
26dc0 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c   directly by sql
26dd0 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a  ite3_step()..**.
26de0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  ** [SQLITE_MISUS
26df0 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
26e00 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  e this routine w
26e10 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72  as called inappr
26e20 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65  opriately..** Pe
26e30 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c  rhaps it was cal
26e40 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  led on a [prepar
26e50 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
26e60 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64  at has.** alread
26e70 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f  y been [sqlite3_
26e80 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c  finalize | final
26e90 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20  ized] or on one 
26ea0 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76  that had.** prev
26eb0 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20  iously returned 
26ec0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f  [SQLITE_ERROR] o
26ed0 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  r [SQLITE_DONE].
26ee0 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a    Or it could.**
26ef0 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61   be the case tha
26f00 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  t the same datab
26f10 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
26f20 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20  s being used by 
26f30 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74  two or.** more t
26f40 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61  hreads at the sa
26f50 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d  me moment in tim
26f60 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c  e..**.** For all
26f70 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
26f80 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e  ite up to and in
26f90 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31  cluding 3.6.23.1
26fa0 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  , a call to.** [
26fb0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
26fc0 20 77 61 73 20 72 65 71 75 69 72 65 64 20 61 66   was required af
26fd0 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ter sqlite3_step
26fe0 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74  () returned anyt
26ff0 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68  hing.** other th
27000 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  an [SQLITE_ROW] 
27010 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65  before any subse
27020 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e  quent invocation
27030 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73   of.** sqlite3_s
27040 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20  tep().  Failure 
27050 74 6f 20 72 65 73 65 74 20 74 68 65 20 70 72 65  to reset the pre
27060 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
27070 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74  using .** [sqlit
27080 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c  e3_reset()] woul
27090 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b  d result in an [
270a0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72  SQLITE_MISUSE] r
270b0 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71  eturn from.** sq
270c0 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42  lite3_step().  B
270d0 75 74 20 61 66 74 65 72 20 76 65 72 73 69 6f 6e  ut after version
270e0 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74   3.6.23.1, sqlit
270f0 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a  e3_step() began.
27100 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  ** calling [sqli
27110 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74  te3_reset()] aut
27120 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68  omatically in th
27130 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20  is circumstance 
27140 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72  rather.** than r
27150 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45  eturning [SQLITE
27160 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20  _MISUSE].  This 
27170 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65  is not considere
27180 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  d a compatibilit
27190 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75  y.** break becau
271a0 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69  se any applicati
271b0 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 63  on that ever rec
271c0 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f  eives an SQLITE_
271d0 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20  MISUSE error.** 
271e0 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66  is broken by def
271f0 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53  inition.  The [S
27200 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52  QLITE_OMIT_AUTOR
27210 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  ESET] compile-ti
27220 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e  me option.** can
27230 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 74   be used to rest
27240 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 62  ore the legacy b
27250 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c  ehavior..**.** <
27260 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63  b>Goofy Interfac
27270 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20  e Alert:</b> In 
27280 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
27290 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65  face, the sqlite
272a0 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20  3_step().** API 
272b0 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61  always returns a
272c0 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63   generic error c
272d0 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  ode, [SQLITE_ERR
272e0 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  OR], following a
272f0 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65  ny.** error othe
27300 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42  r than [SQLITE_B
27310 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45  USY] and [SQLITE
27320 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d  _MISUSE].  You m
27330 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c  ust call.** [sql
27340 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
27350 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
27360 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74  ze()] in order t
27370 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68  o find one of th
27380 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65  e.** specific [e
27390 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74  rror codes] that
273a0 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65   better describe
273b0 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  s the error..** 
273c0 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68  We admit that th
273d0 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65  is is a goofy de
273e0 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c  sign.  The probl
273f0 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65  em has been fixe
27400 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76  d.** with the "v
27410 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49  2" interface.  I
27420 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c  f you prepare al
27430 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74  l of your SQL st
27440 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e  atements.** usin
27450 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65  g either [sqlite
27460 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
27470 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
27480 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74  are16_v2()] inst
27490 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65  ead.** of the le
274a0 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  gacy [sqlite3_pr
274b0 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
274c0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
274d0 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a  )] interfaces,.*
274e0 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20  * then the more 
274f0 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
27500 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72  codes] are retur
27510 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  ned directly.** 
27520 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
27530 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ).  The use of t
27540 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
27550 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e is recommended
27560 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
27570 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74  _step(sqlite3_st
27580 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
27590 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66  I3REF: Number of
275a0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65   columns in a re
275b0 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e  sult set.**.** ^
275c0 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
275d0 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66  _count(P) interf
275e0 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
275f0 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
27600 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72  s in the.** curr
27610 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72  ent row of the r
27620 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72  esult set of [pr
27630 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
27640 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70  ] P..** ^If prep
27650 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50  ared statement P
27660 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72   does not have r
27670 65 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20  esults ready to 
27680 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63  return.** (via c
27690 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c  alls to the [sql
276a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20  ite3_column_int 
276b0 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  | sqlite3_column
276c0 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65  _*()] of.** inte
276d0 72 66 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c  rfaces) then sql
276e0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
276f0 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a  P) returns 0..**
27700 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
27710 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74  ta_count(P) rout
27720 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73  ine also returns
27730 20 30 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c   0 if P is a NUL
27740 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
27750 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
27760 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
27770 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ()].*/.int sqlit
27780 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71  e3_data_count(sq
27790 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
277a0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
277b0 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c  REF: Fundamental
277c0 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45   Datatypes.** KE
277d0 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54  YWORDS: SQLITE_T
277e0 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72  EXT.**.** ^(Ever
277f0 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74  y value in SQLit
27800 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76  e has one of fiv
27810 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61  e fundamental da
27820 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  tatypes:.**.** <
27830 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62  ul>.** <li> 64-b
27840 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
27850 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74  r.** <li> 64-bit
27860 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70   IEEE floating p
27870 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c  oint number.** <
27880 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c  li> string.** <l
27890 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20  i> BLOB.** <li> 
278a0 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a  NULL.** </ul>)^.
278b0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
278c0 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20  tants are codes 
278d0 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73  for each of thos
278e0 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e  e types..**.** N
278f0 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51 4c  ote that the SQL
27900 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e  ITE_TEXT constan
27910 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20  t was also used 
27920 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  in SQLite versio
27930 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d  n 2.** for a com
27940 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e  pletely differen
27950 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74  t meaning.  Soft
27960 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20  ware that links 
27970 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20  against both.** 
27980 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32  SQLite version 2
27990 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73   and SQLite vers
279a0 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65  ion 3 should use
279b0 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e   SQLITE3_TEXT, n
279c0 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58  ot.** SQLITE_TEX
279d0 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  T..*/.#define SQ
279e0 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a  LITE_INTEGER  1.
279f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
27a00 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e  LOAT    2.#defin
27a10 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20  e SQLITE_BLOB   
27a20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
27a30 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69  TE_NULL     5.#i
27a40 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54  fdef SQLITE_TEXT
27a50 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
27a60 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66  TEXT.#else.# def
27a70 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20  ine SQLITE_TEXT 
27a80 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65      3.#endif.#de
27a90 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58  fine SQLITE3_TEX
27aa0 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43  T     3../*.** C
27ab0 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20  API3REF: Result 
27ac0 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75  Values From A Qu
27ad0 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ery.** KEYWORDS:
27ae0 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   {column access 
27af0 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a  functions}.**.**
27b00 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
27b10 66 6f 72 6d 20 74 68 65 20 22 72 65 73 75 6c 74  form the "result
27b20 20 73 65 74 22 20 69 6e 74 65 72 66 61 63 65 2e   set" interface.
27b30 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
27b40 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e  utines return in
27b50 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
27b60 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20  a single column 
27b70 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  of the current.*
27b80 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20  * result row of 
27b90 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76  a query.  ^In ev
27ba0 65 72 79 20 63 61 73 65 20 74 68 65 20 66 69 72  ery case the fir
27bb0 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
27bc0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
27bd0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
27be0 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20  tement] that is 
27bf0 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20  being evaluated 
27c00 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  (the [sqlite3_st
27c10 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73  mt*].** that was
27c20 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b   returned from [
27c30 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
27c40 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  v2()] or one of 
27c50 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a  its variants).**
27c60 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
27c70 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
27c80 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c  index of the col
27c90 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e  umn for which in
27ca0 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f  formation.** sho
27cb0 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
27cc0 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63   ^The leftmost c
27cd0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
27ce0 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 20  ult set has the 
27cf0 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65  index 0..** ^The
27d00 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
27d10 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
27d20 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e   can be determin
27d30 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  ed using.** [sql
27d40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
27d50 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  t()]..**.** If t
27d60 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
27d70 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e   does not curren
27d80 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76  tly point to a v
27d90 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20  alid row, or if 
27da0 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e  the.** column in
27db0 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61  dex is out of ra
27dc0 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20  nge, the result 
27dd0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
27de0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
27df0 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  may only be call
27e00 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74  ed when the most
27e10 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a   recent call to.
27e20 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
27e30 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  ()] has returned
27e40 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e   [SQLITE_ROW] an
27e50 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71  d neither.** [sq
27e60 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e  lite3_reset()] n
27e70 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
27e80 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65  lize()] have bee
27e90 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75  n called subsequ
27ea0 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79  ently..** If any
27eb0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
27ec0 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66  es are called af
27ed0 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ter [sqlite3_res
27ee0 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  et()] or.** [sql
27ef0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
27f00 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74   or after [sqlit
27f10 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72  e3_step()] has r
27f20 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74  eturned.** somet
27f30 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20  hing other than 
27f40 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68  [SQLITE_ROW], th
27f50 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
27f60 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b  defined..** If [
27f70 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
27f80 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
27f90 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
27fa0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20  _finalize()].** 
27fb0 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  are called from 
27fc0 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  a different thre
27fd0 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20  ad while any of 
27fe0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  these routines.*
27ff0 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74  * are pending, t
28000 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
28010 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
28020 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
28030 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
28040 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
28050 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  the.** [SQLITE_I
28060 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70  NTEGER | datatyp
28070 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20  e code] for the 
28080 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70  initial data typ
28090 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75  e.** of the resu
280a0 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65  lt column.  ^The
280b0 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20   returned value 
280c0 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
280d0 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b  E_INTEGER],.** [
280e0 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b  SQLITE_FLOAT], [
280f0 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53  SQLITE_TEXT], [S
28100 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20  QLITE_BLOB], or 
28110 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20  [SQLITE_NULL].  
28120 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74  The value.** ret
28130 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
28140 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69  _column_type() i
28150 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75  s only meaningfu
28160 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20  l if no type.** 
28170 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65  conversions have
28180 20 6f 63 63 75 72 72 65 64 20 61 73 20 64 65 73   occurred as des
28190 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41  cribed below.  A
281a0 66 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76  fter a type conv
281b0 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76  ersion,.** the v
281c0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
281d0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
281e0 74 79 70 65 28 29 20 69 73 20 75 6e 64 65 66 69  type() is undefi
281f0 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20  ned.  Future.** 
28200 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
28210 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68  te may change th
28220 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71  e behavior of sq
28230 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
28240 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  e().** following
28250 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
28260 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  on..**.** ^If th
28270 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c  e result is a BL
28280 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69  OB or UTF-8 stri
28290 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  ng then the sqli
282a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
282b0 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65  ().** routine re
282c0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
282d0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
282e0 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  t BLOB or string
282f0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
28300 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 20  ult is a UTF-16 
28310 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c  string, then sql
28320 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
28330 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  s() converts.** 
28340 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54  the string to UT
28350 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74  F-8 and then ret
28360 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
28370 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66  of bytes..** ^If
28380 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
28390 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74   numeric value t
283a0 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
283b0 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a  mn_bytes() uses.
283c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ** [sqlite3_snpr
283d0 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65  intf()] to conve
283e0 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f  rt that value to
283f0 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20   a UTF-8 string 
28400 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  and returns.** t
28410 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
28420 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e  es in that strin
28430 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
28440 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  sult is NULL, th
28450 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
28460 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75 72 6e  n_bytes() return
28470 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49  s zero..**.** ^I
28480 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
28490 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36  a BLOB or UTF-16
284a0 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65   string then the
284b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
284c0 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75  bytes16().** rou
284d0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
284e0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
284f0 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72   in that BLOB or
28500 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
28510 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
28520 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68  UTF-8 string, th
28530 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
28540 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76  n_bytes16() conv
28550 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69  erts.** the stri
28560 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64  ng to UTF-16 and
28570 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68   then returns th
28580 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
28590 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  s..** ^If the re
285a0 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69  sult is a numeri
285b0 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c  c value then sql
285c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
285d0 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73  s16() uses.** [s
285e0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
285f0 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  )] to convert th
28600 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54  at value to a UT
28610 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20  F-16 string and 
28620 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
28630 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
28640 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
28650 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
28660 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73   is NULL, then s
28670 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
28680 74 65 73 31 36 28 29 20 72 65 74 75 72 6e 73 20  tes16() returns 
28690 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  zero..**.** ^The
286a0 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
286b0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
286c0 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64  umn_bytes()] and
286d0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f   .** [sqlite3_co
286e0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20  lumn_bytes16()] 
286f0 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74  do not include t
28700 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
28710 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a  ors at the end.*
28720 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e  * of the string.
28730 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20    ^For clarity: 
28740 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  the values retur
28750 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
28760 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
28770 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
28780 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
28790 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72  ] are the number
287a0 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20   of.** bytes in 
287b0 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20  the string, not 
287c0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
287d0 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
287e0 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65  ^Strings returne
287f0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
28800 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73  umn_text() and s
28810 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
28820 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20  xt16(),.** even 
28830 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61  empty strings, a
28840 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 20 74  re always zero t
28850 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65  erminated.  ^The
28860 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65   return.** value
28870 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f   from sqlite3_co
28880 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20  lumn_blob() for 
28890 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
288a0 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  OB is a NULL poi
288b0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nter..**.** ^The
288c0 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
288d0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
288e0 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
288f0 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  an.** [unprotect
28900 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
28910 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e  ] object.  An un
28920 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
28930 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a  3_value object.*
28940 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73  * may only be us
28950 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33  ed with [sqlite3
28960 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61  _bind_value()] a
28970 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  nd [sqlite3_resu
28980 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20  lt_value()]..** 
28990 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63  If the [unprotec
289a0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
289b0 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  e] object return
289c0 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
289d0 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
289e0 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79  ] is used in any
289f0 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c   other way, incl
28a00 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74  uding calls.** t
28a10 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20  o routines like 
28a20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69  [sqlite3_value_i
28a30 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  nt()], [sqlite3_
28a40 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a  value_text()],.*
28a50 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61  * or [sqlite3_va
28a60 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68  lue_bytes()], th
28a70 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
28a80 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
28a90 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
28aa0 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f  es attempt to co
28ab0 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20  nvert the value 
28ac0 77 68 65 72 65 20 61 70 70 72 6f 70 72 69 61 74  where appropriat
28ad0 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d  e.  ^For.** exam
28ae0 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65  ple, if the inte
28af0 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74  rnal representat
28b00 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64  ion is FLOAT and
28b10 20 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a   a text result.*
28b20 2a 20 69 73 20 72 65 71 75 65 73 74 65 64 2c 20  * is requested, 
28b30 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
28b40 66 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74  f()] is used int
28b50 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f  ernally to perfo
28b60 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72  rm the.** conver
28b70 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c  sion automatical
28b80 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f  ly.  ^(The follo
28b90 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69  wing table detai
28ba0 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f  ls the conversio
28bb0 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61  ns.** that are a
28bc0 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62  pplied:.**.** <b
28bd0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74  lockquote>.** <t
28be0 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e  able border="1">
28bf0 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74  .** <tr><th> Int
28c00 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74  ernal<br>Type <t
28c10 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e  h> Requested<br>
28c20 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65  Type <th>  Conve
28c30 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e  rsion.**.** <tr>
28c40 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
28c50 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
28c60 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a  > Result is 0.**
28c70 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
28c80 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
28c90 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
28ca0 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e   0.0.** <tr><td>
28cb0 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
28cc0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65   TEXT    <td> Re
28cd0 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69  sult is NULL poi
28ce0 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
28cf0 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
28d00 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65   BLOB    <td> Re
28d10 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69  sult is NULL poi
28d20 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
28d30 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
28d40 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f  FLOAT    <td> Co
28d50 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67  nvert from integ
28d60 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c  er to float.** <
28d70 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
28d80 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
28d90 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
28da0 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65  ring of the inte
28db0 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ger.** <tr><td> 
28dc0 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20  INTEGER  <td>   
28dd0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d  BLOB    <td> Sam
28de0 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45  e as INTEGER->TE
28df0 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  XT.** <tr><td>  
28e00 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54  FLOAT   <td> INT
28e10 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76  EGER   <td> Conv
28e20 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74  ert from float t
28e30 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72  o integer.** <tr
28e40 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
28e50 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
28e60 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69  d> ASCII renderi
28e70 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a  ng of the float.
28e80 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
28e90 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  AT   <td>   BLOB
28ea0 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73      <td> Same as
28eb0 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20   FLOAT->TEXT.** 
28ec0 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
28ed0 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
28ee0 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69 28 29   <td> Use atoi()
28ef0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
28f00 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  XT    <td>  FLOA
28f10 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74  T    <td> Use at
28f20 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  of().** <tr><td>
28f30 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20    TEXT    <td>  
28f40 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f   BLOB    <td> No
28f50 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c   change.** <tr><
28f60 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
28f70 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
28f80 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54   Convert to TEXT
28f90 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69 28 29   then use atoi()
28fa0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
28fb0 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  OB    <td>  FLOA
28fc0 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  T    <td> Conver
28fd0 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75  t to TEXT then u
28fe0 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72  se atof().** <tr
28ff0 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
29000 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
29010 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65  d> Add a zero te
29020 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64  rminator if need
29030 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a  ed.** </table>.*
29040 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29  * </blockquote>)
29050 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c  ^.**.** The tabl
29060 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65  e above makes re
29070 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64  ference to stand
29080 61 72 64 20 43 20 6c 69 62 72 61 72 79 20 66 75  ard C library fu
29090 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a  nctions atoi().*
290a0 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53  * and atof().  S
290b0 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72  QLite does not r
290c0 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20  eally use these 
290d0 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68  functions.  It h
290e0 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71  as its.** own eq
290f0 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61  uivalent interna
29100 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65  l routines.  The
29110 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66   atoi() and atof
29120 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20  () names are.** 
29130 75 73 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c  used in the tabl
29140 65 20 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e  e for brevity an
29150 64 20 62 65 63 61 75 73 65 20 74 68 65 79 20 61  d because they a
29160 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d  re familiar to m
29170 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d  ost.** C program
29180 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  mers..**.** Note
29190 20 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 20   that when type 
291a0 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75  conversions occu
291b0 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  r, pointers retu
291c0 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a  rned by prior.**
291d0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
291e0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c  3_column_blob(),
291f0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
29200 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a  text(), and/or.*
29210 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
29220 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 65  _text16() may be
29230 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a   invalidated..**
29240 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   Type conversion
29250 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e  s and pointer in
29260 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68  validations migh
29270 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68  t occur.** in th
29280 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65  e following case
29290 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
292a0 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
292b0 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42  l content is a B
292c0 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  LOB and sqlite3_
292d0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72  column_text() or
292e0 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
292f0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
29300 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a   is called.  A z
29310 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d  ero-terminator m
29320 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65  ight.**      nee
29330 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f  d to be added to
29340 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69   the string.</li
29350 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
29360 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
29370 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20   UTF-8 text and 
29380 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
29390 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20  ytes16() or.**  
293a0 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
293b0 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63  mn_text16() is c
293c0 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74  alled.  The cont
293d0 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ent must be conv
293e0 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f  erted.**      to
293f0 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a   UTF-16.</li>.**
29400 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
29410 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46  l content is UTF
29420 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c  -16 text and sql
29430 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
29440 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  s() or.**      s
29450 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
29460 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  xt() is called. 
29470 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73   The content mus
29480 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a  t be converted.*
29490 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e  *      to UTF-8.
294a0 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  </li>.** </ul>.*
294b0 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e  *.** ^Conversion
294c0 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36  s between UTF-16
294d0 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20  be and UTF-16le 
294e0 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20  are always done 
294f0 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a  in place and do.
29500 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74  ** not invalidat
29510 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  e a prior pointe
29520 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75  r, though of cou
29530 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  rse the content 
29540 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a  of the buffer.**
29550 20 74 68 61 74 20 74 68 65 20 70 72 69 6f 72 20   that the prior 
29560 70 6f 69 6e 74 65 72 20 72 65 66 65 72 65 6e 63  pointer referenc
29570 65 73 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65  es will have bee
29580 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68  n modified.  Oth
29590 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63  er kinds.** of c
295a0 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f  onversion are do
295b0 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e  ne in place when
295c0 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c   it is possible,
295d0 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74   but sometimes t
295e0 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70  hey.** are not p
295f0 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74  ossible and in t
29600 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f 72  hose cases prior
29610 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e   pointers are in
29620 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a  validated..**.**
29630 20 54 68 65 20 73 61 66 65 73 74 20 61 6e 64 20   The safest and 
29640 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d  easiest to remem
29650 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f  ber policy is to
29660 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f   invoke these ro
29670 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65  utines.** in one
29680 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
29690 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  g ways:.**.** <u
296a0 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  l>.**  <li>sqlit
296b0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
296c0 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
296d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
296e0 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69  s()</li>.**  <li
296f0 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
29700 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20  blob() followed 
29710 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
29720 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a  n_bytes()</li>.*
29730 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
29740 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66  olumn_text16() f
29750 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
29760 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
29770 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c  6()</li>.** </ul
29780 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72  >.**.** In other
29790 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75   words, you shou
297a0 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f  ld call sqlite3_
297b0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a  column_text(),.*
297c0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
297d0 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69  _blob(), or sqli
297e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
297f0 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72  6() first to for
29800 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a  ce the result.**
29810 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65   into the desire
29820 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69  d format, then i
29830 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f  nvoke sqlite3_co
29840 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a  lumn_bytes() or.
29850 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
29860 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20 66  n_bytes16() to f
29870 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ind the size of 
29880 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20  the result.  Do 
29890 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a  not mix calls.**
298a0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
298b0 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c  mn_text() or sql
298c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
298d0 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  () with calls to
298e0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
298f0 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e  mn_bytes16(), an
29900 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c  d do not mix cal
29910 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
29920 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a  lumn_text16().**
29930 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73   with calls to s
29940 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
29950 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tes()..**.** ^Th
29960 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  e pointers retur
29970 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e  ned are valid un
29980 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65  til a type conve
29990 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a  rsion occurs as.
299a0 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 6f  ** described abo
299b0 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71  ve, or until [sq
299c0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72  lite3_step()] or
299d0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
299e0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
299f0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73  3_finalize()] is
29a00 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d   called.  ^The m
29a10 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64  emory space used
29a20 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73   to hold strings
29a30 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73  .** and BLOBs is
29a40 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63   freed automatic
29a50 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74  ally.  Do <b>not
29a60 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f  </b> pass the po
29a70 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a  inters returned.
29a80 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
29a90 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c  mn_blob()], [sql
29aa0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
29ab0 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a  ()], etc. into.*
29ac0 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  * [sqlite3_free(
29ad0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61  )]..**.** ^(If a
29ae0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
29af0 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  on error occurs 
29b00 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75  during the evalu
29b10 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20  ation of any.** 
29b20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
29b30 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c  s, a default val
29b40 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  ue is returned. 
29b50 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c   The default val
29b60 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20  ue.** is either 
29b70 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74  the integer 0, t
29b80 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  he floating poin
29b90 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72  t number 0.0, or
29ba0 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
29bb0 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20  er.  Subsequent 
29bc0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
29bd0 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c  3_errcode()] wil
29be0 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c  l return.** [SQL
29bf0 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f  ITE_NOMEM].)^.*/
29c00 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
29c10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
29c20 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
29c30 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
29c40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
29c50 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  tes(sqlite3_stmt
29c60 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
29c70 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
29c80 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33  _bytes16(sqlite3
29c90 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
29ca0 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65  );.double sqlite
29cb0 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28  3_column_double(
29cc0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
29cd0 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
29ce0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
29cf0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
29d00 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74  int iCol);.sqlit
29d10 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
29d20 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71  _column_int64(sq
29d30 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
29d40 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e   iCol);.const un
29d50 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c  signed char *sql
29d60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
29d70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
29d80 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74  int iCol);.const
29d90 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
29da0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c  olumn_text16(sql
29db0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
29dc0 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
29dd0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73  e3_column_type(s
29de0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
29df0 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33  t iCol);.sqlite3
29e00 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f  _value *sqlite3_
29e10 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c  column_value(sql
29e20 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
29e30 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  iCol);../*.** CA
29e40 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20  PI3REF: Destroy 
29e50 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
29e60 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  ment Object.**.*
29e70 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66  * ^The sqlite3_f
29e80 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69  inalize() functi
29e90 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  on is called to 
29ea0 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72  delete a [prepar
29eb0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
29ec0 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
29ed0 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e  ecent evaluation
29ee0 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   of the statemen
29ef0 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f  t encountered no
29f00 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66   errors.** or if
29f10 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
29f20 73 20 6e 65 76 65 72 20 62 65 65 6e 20 65 76 61  s never been eva
29f30 6c 75 61 74 65 64 2c 20 74 68 65 6e 20 73 71 6c  luated, then sql
29f40 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
29f50 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54  returns.** SQLIT
29f60 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d  E_OK.  ^If the m
29f70 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75  ost recent evalu
29f80 61 74 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65  ation of stateme
29f90 6e 74 20 53 20 66 61 69 6c 65 64 2c 20 74 68 65  nt S failed, the
29fa0 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e  n.** sqlite3_fin
29fb0 61 6c 69 7a 65 28 53 29 20 72 65 74 75 72 6e 73  alize(S) returns
29fc0 20 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 65   the appropriate
29fd0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72   [error code] or
29fe0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 65 72  .** [extended er
29ff0 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a  ror code]..**.**
2a000 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69   ^The sqlite3_fi
2a010 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75 74 69 6e  nalize(S) routin
2a020 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  e can be called 
2a030 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72  at any point dur
2a040 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20  ing.** the life 
2a050 63 79 63 6c 65 20 6f 66 20 5b 70 72 65 70 61 72  cycle of [prepar
2a060 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a  ed statement] S:
2a070 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74 61 74 65  .** before state
2a080 6d 65 6e 74 20 53 20 69 73 20 65 76 65 72 20 65  ment S is ever e
2a090 76 61 6c 75 61 74 65 64 2c 20 61 66 74 65 72 0a  valuated, after.
2a0a0 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63  ** one or more c
2a0b0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
2a0c0 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72 20 61 66  _reset()], or af
2a0d0 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20  ter any call.** 
2a0e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
2a0f0 28 29 5d 20 72 65 67 61 72 64 6c 65 73 73 20 6f  ()] regardless o
2a100 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
2a110 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
2a120 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20  as.** completed 
2a130 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  execution..**.**
2a140 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74   ^Invoking sqlit
2a150 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e  e3_finalize() on
2a160 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
2a170 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
2a180 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  -op..**.** The a
2a190 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
2a1a0 66 69 6e 61 6c 69 7a 65 20 65 76 65 72 79 20 5b  finalize every [
2a1b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2a1c0 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  nt] in order to 
2a1d0 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63  avoid.** resourc
2a1e0 65 20 6c 65 61 6b 73 2e 20 20 49 74 20 69 73 20  e leaks.  It is 
2a1f0 61 20 67 72 69 65 76 6f 75 73 20 65 72 72 6f 72  a grievous error
2a200 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61   for the applica
2a210 74 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20 75  tion to try to u
2a220 73 65 0a 2a 2a 20 61 20 70 72 65 70 61 72 65 64  se.** a prepared
2a230 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72   statement after
2a240 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e   it has been fin
2a250 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75 73 65  alized.  Any use
2a260 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 0a 2a   of a prepared.*
2a270 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  * statement afte
2a280 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69  r it has been fi
2a290 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72 65 73 75  nalized can resu
2a2a0 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  lt in undefined 
2a2b0 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62  and.** undesirab
2a2c0 6c 65 20 62 65 68 61 76 69 6f 72 20 73 75 63 68  le behavior such
2a2d0 20 61 73 20 73 65 67 66 61 75 6c 74 73 20 61 6e   as segfaults an
2a2e0 64 20 68 65 61 70 20 63 6f 72 72 75 70 74 69 6f  d heap corruptio
2a2f0 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  n..*/.int sqlite
2a300 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74  3_finalize(sqlit
2a310 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2a320 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2a330 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72  : Reset A Prepar
2a340 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
2a350 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ect.**.** The sq
2a360 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20 66 75  lite3_reset() fu
2a370 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64  nction is called
2a380 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65   to reset a [pre
2a390 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2a3a0 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20  .** object back 
2a3b0 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73  to its initial s
2a3c0 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62  tate, ready to b
2a3d0 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a  e re-executed..*
2a3e0 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74 61 74 65  * ^Any SQL state
2a3f0 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74  ment variables t
2a400 68 61 74 20 68 61 64 20 76 61 6c 75 65 73 20 62  hat had values b
2a410 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69  ound to them usi
2a420 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  ng.** the [sqlit
2a430 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73  e3_bind_blob | s
2a440 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
2a450 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69  API] retain thei
2a460 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65  r values..** Use
2a470 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f   [sqlite3_clear_
2a480 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72  bindings()] to r
2a490 65 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67  eset the binding
2a4a0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73  s..**.** ^The [s
2a4b0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
2a4c0 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74   interface reset
2a4d0 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  s the [prepared 
2a4e0 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20  statement] S.** 
2a4f0 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69  back to the begi
2a500 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f  nning of its pro
2a510 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  gram..**.** ^If 
2a520 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
2a530 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2a540 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68  _step(S)] for th
2a550 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
2a560 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75  tatement] S retu
2a570 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57  rned [SQLITE_ROW
2a580 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ] or [SQLITE_DON
2a590 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71  E],.** or if [sq
2a5a0 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68  lite3_step(S)] h
2a5b0 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20  as never before 
2a5c0 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53  been called on S
2a5d0 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74  ,.** then [sqlit
2a5e0 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74  e3_reset(S)] ret
2a5f0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
2a600 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2a610 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
2a620 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
2a630 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a  p(S)] for the.**
2a640 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2a650 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65  ment] S indicate
2a660 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e  d an error, then
2a670 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
2a680 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61  et(S)] returns a
2a690 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65  n appropriate [e
2a6a0 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a  rror code]..**.*
2a6b0 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
2a6c0 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66  reset(S)] interf
2a6d0 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  ace does not cha
2a6e0 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a  nge the values.*
2a6f0 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65  * of any [sqlite
2a700 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64  3_bind_blob|bind
2a710 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72  ings] on the [pr
2a720 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2a730 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ] S..*/.int sqli
2a740 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65  te3_reset(sqlite
2a750 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
2a760 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2a770 20 43 72 65 61 74 65 20 4f 72 20 52 65 64 65 66   Create Or Redef
2a780 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  ine SQL Function
2a790 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
2a7a0 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f  function creatio
2a7b0 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b  n routines}.** K
2a7c0 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63  EYWORDS: {applic
2a7d0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
2a7e0 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b  L function}.** K
2a7f0 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63  EYWORDS: {applic
2a800 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
2a810 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a  L functions}.**.
2a820 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69  ** ^These functi
2a830 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c  ons (collectivel
2a840 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63  y known as "func
2a850 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f  tion creation ro
2a860 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20  utines").** are 
2a870 75 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20  used to add SQL 
2a880 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67  functions or agg
2a890 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65  regates or to re
2a8a0 64 65 66 69 6e 65 20 74 68 65 20 62 65 68 61 76  define the behav
2a8b0 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69  ior.** of existi
2a8c0 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ng SQL functions
2a8d0 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e 20   or aggregates. 
2a8e0 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72   The only differ
2a8f0 65 6e 63 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a  ences between.**
2a900 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
2a910 61 72 65 20 74 68 65 20 74 65 78 74 20 65 6e 63  are the text enc
2a920 6f 64 69 6e 67 20 65 78 70 65 63 74 65 64 20 66  oding expected f
2a930 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64  or.** the second
2a940 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20   parameter (the 
2a950 6e 61 6d 65 20 6f 66 20 74 68 65 20 66 75 6e 63  name of the func
2a960 74 69 6f 6e 20 62 65 69 6e 67 20 63 72 65 61 74  tion being creat
2a970 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70  ed).** and the p
2a980 72 65 73 65 6e 63 65 20 6f 72 20 61 62 73 65 6e  resence or absen
2a990 63 65 20 6f 66 20 61 20 64 65 73 74 72 75 63 74  ce of a destruct
2a9a0 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a  or callback for.
2a9b0 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
2a9c0 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e  on data pointer.
2a9d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
2a9e0 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
2a9f0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
2aa00 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63  nection] to whic
2aa10 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e  h the SQL.** fun
2aa20 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61  ction is to be a
2aa30 64 64 65 64 2e 20 20 5e 49 66 20 61 6e 20 61 70  dded.  ^If an ap
2aa40 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 73 20 6d  plication uses m
2aa50 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74  ore than one dat
2aa60 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
2aa70 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69 63 61  ion then applica
2aa80 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
2aa90 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20   functions must 
2aaa0 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65  be added.** to e
2aab0 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
2aac0 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 61 74 65  nection separate
2aad0 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ly..**.** ^The s
2aae0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
2aaf0 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
2ab00 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
2ab10 74 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f 72  to be created or
2ab20 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20  .** redefined.  
2ab30 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74  ^The length of t
2ab40 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74  he name is limit
2ab50 65 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 20  ed to 255 bytes 
2ab60 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65  in a UTF-8.** re
2ab70 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78  presentation, ex
2ab80 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20 7a  clusive of the z
2ab90 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero-terminator. 
2aba0 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20   ^Note that the 
2abb0 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c  name.** length l
2abc0 69 6d 69 74 20 69 73 20 69 6e 20 55 54 46 2d 38  imit is in UTF-8
2abd0 20 62 79 74 65 73 2c 20 6e 6f 74 20 63 68 61 72   bytes, not char
2abe0 61 63 74 65 72 73 20 6e 6f 72 20 55 54 46 2d 31  acters nor UTF-1
2abf0 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41  6 bytes.  .** ^A
2ac00 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72  ny attempt to cr
2ac10 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20  eate a function 
2ac20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61  with a longer na
2ac30 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c  me.** will resul
2ac40 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  t in [SQLITE_MIS
2ac50 55 53 45 5d 20 62 65 69 6e 67 20 72 65 74 75 72  USE] being retur
2ac60 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
2ac70 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
2ac80 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74 68 65  (nArg).** is the
2ac90 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
2aca0 65 6e 74 73 20 74 68 61 74 20 74 68 65 20 53 51  ents that the SQ
2acb0 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
2acc0 20 61 67 67 72 65 67 61 74 65 20 74 61 6b 65 73   aggregate takes
2acd0 2e 20 5e 49 66 20 74 68 69 73 20 70 61 72 61 6d  . ^If this param
2ace0 65 74 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eter is -1, then
2acf0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2ad00 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
2ad10 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e  e may take any n
2ad20 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
2ad30 74 73 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64  ts between 0 and
2ad40 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65   the limit.** se
2ad50 74 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69  t by [sqlite3_li
2ad60 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d  mit]([SQLITE_LIM
2ad70 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d  IT_FUNCTION_ARG]
2ad80 29 2e 20 20 49 66 20 74 68 65 20 74 68 69 72 64  ).  If the third
2ad90 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73  .** parameter is
2ada0 20 6c 65 73 73 20 74 68 61 6e 20 2d 31 20 6f 72   less than -1 or
2adb0 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 32   greater than 12
2adc0 37 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  7 then the behav
2add0 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69  ior is.** undefi
2ade0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
2adf0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
2ae00 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70 65 63  , eTextRep, spec
2ae10 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53  ifies what.** [S
2ae20 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78  QLITE_UTF8 | tex
2ae30 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73  t encoding] this
2ae40 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72   SQL function pr
2ae50 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73  efers for.** its
2ae60 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 45 76   parameters.  Ev
2ae70 65 72 79 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ery SQL function
2ae80 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2ae90 6d 75 73 74 20 62 65 20 61 62 6c 65 20 74 6f 20  must be able to 
2aea0 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 20 55 54 46  work.** with UTF
2aeb0 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72  -8, UTF-16le, or
2aec0 20 55 54 46 2d 31 36 62 65 2e 20 20 42 75 74 20   UTF-16be.  But 
2aed0 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  some implementat
2aee0 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d  ions may be.** m
2aef0 6f 72 65 20 65 66 66 69 63 69 65 6e 74 20 77 69  ore efficient wi
2af00 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20  th one encoding 
2af10 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20 5e  than another.  ^
2af20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  An application m
2af30 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c  ay.** invoke sql
2af40 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2af50 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  tion() or sqlite
2af60 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2af70 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a  n16() multiple.*
2af80 2a 20 74 69 6d 65 73 20 77 69 74 68 20 74 68 65  * times with the
2af90 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62   same function b
2afa0 75 74 20 77 69 74 68 20 64 69 66 66 65 72 65 6e  ut with differen
2afb0 74 20 76 61 6c 75 65 73 20 6f 66 20 65 54 65 78  t values of eTex
2afc0 74 52 65 70 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d  tRep..** ^When m
2afd0 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
2afe0 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
2aff0 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65  ame function are
2b000 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69   available, SQLi
2b010 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20  te.** will pick 
2b020 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76  the one that inv
2b030 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74 20  olves the least 
2b040 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63  amount of data c
2b050 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66  onversion..** If
2b060 20 74 68 65 72 65 20 69 73 20 6f 6e 6c 79 20 61   there is only a
2b070 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e   single implemen
2b080 74 61 74 69 6f 6e 20 77 68 69 63 68 20 64 6f 65  tation which doe
2b090 73 20 6e 6f 74 20 63 61 72 65 20 77 68 61 74 20  s not care what 
2b0a0 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67  text.** encoding
2b0b0 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 74   is used, then t
2b0c0 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
2b0d0 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 5b 53 51  nt should be [SQ
2b0e0 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a  LITE_ANY]..**.**
2b0f0 20 5e 28 54 68 65 20 66 69 66 74 68 20 70 61 72   ^(The fifth par
2b100 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 62  ameter is an arb
2b110 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20  itrary pointer. 
2b120 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   The implementat
2b130 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75  ion of the.** fu
2b140 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20  nction can gain 
2b150 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20 70  access to this p
2b160 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71  ointer using [sq
2b170 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
2b180 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  )].)^.**.** ^The
2b190 20 73 69 78 74 68 2c 20 73 65 76 65 6e 74 68 20   sixth, seventh 
2b1a0 61 6e 64 20 65 69 67 68 74 68 20 70 61 72 61 6d  and eighth param
2b1b0 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53  eters, xFunc, xS
2b1c0 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20  tep and xFinal, 
2b1d0 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20  are.** pointers 
2b1e0 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75  to C-language fu
2b1f0 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70  nctions that imp
2b200 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66  lement the SQL f
2b210 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
2b220 67 72 65 67 61 74 65 2e 20 5e 41 20 73 63 61 6c  gregate. ^A scal
2b230 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ar SQL function 
2b240 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c  requires an impl
2b250 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
2b260 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62  e xFunc.** callb
2b270 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70  ack only; NULL p
2b280 6f 69 6e 74 65 72 73 20 6d 75 73 74 20 62 65 20  ointers must be 
2b290 70 61 73 73 65 64 20 61 73 20 74 68 65 20 78 53  passed as the xS
2b2a0 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a  tep and xFinal.*
2b2b0 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 5e 41  * parameters. ^A
2b2c0 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  n aggregate SQL 
2b2d0 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
2b2e0 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  s an implementat
2b2f0 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20  ion of xStep.** 
2b300 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e  and xFinal and N
2b310 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73 74  ULL pointer must
2b320 20 62 65 20 70 61 73 73 65 64 20 66 6f 72 20 78   be passed for x
2b330 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65  Func. ^To delete
2b340 20 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20   an existing.** 
2b350 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20  SQL function or 
2b360 61 67 67 72 65 67 61 74 65 2c 20 70 61 73 73 20  aggregate, pass 
2b370 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f  NULL pointers fo
2b380 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63  r all three func
2b390 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  tion.** callback
2b3a0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68  s..**.** ^(If th
2b3b0 65 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65  e ninth paramete
2b3c0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65  r to sqlite3_cre
2b3d0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
2b3e0 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a  ) is not NULL,.*
2b3f0 2a 20 74 68 65 6e 20 69 74 20 69 73 20 64 65 73  * then it is des
2b400 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20  tructor for the 
2b410 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
2b420 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68   pointer. .** Th
2b430 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  e destructor is 
2b440 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65  invoked when the
2b450 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c   function is del
2b460 65 74 65 64 2c 20 65 69 74 68 65 72 20 62 79 20  eted, either by 
2b470 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61  being.** overloa
2b480 64 65 64 20 6f 72 20 77 68 65 6e 20 74 68 65 20  ded or when the 
2b490 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2b4a0 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a  ion closes.)^.**
2b4b0 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72   ^The destructor
2b4c0 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64   is also invoked
2b4d0 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a   if the call to.
2b4e0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ** sqlite3_creat
2b4f0 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20  e_function_v2() 
2b500 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20  fails..** ^When 
2b510 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 63  the destructor c
2b520 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 74  allback of the t
2b530 65 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  enth parameter i
2b540 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a  s invoked, it.**
2b550 20 69 73 20 70 61 73 73 65 64 20 61 20 73 69 6e   is passed a sin
2b560 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
2b570 63 68 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  ch is a copy of 
2b580 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
2b590 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72  data .** pointer
2b5a0 20 77 68 69 63 68 20 77 61 73 20 74 68 65 20 66   which was the f
2b5b0 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  ifth parameter t
2b5c0 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  o sqlite3_create
2b5d0 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a  _function_v2()..
2b5e0 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65 72  **.** ^It is per
2b5f0 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73 74  mitted to regist
2b600 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  er multiple impl
2b610 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
2b620 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74  he same.** funct
2b630 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73 61  ions with the sa
2b640 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68  me name but with
2b650 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69 6e   either differin
2b660 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20  g numbers of.** 
2b670 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66  arguments or dif
2b680 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 65 64  fering preferred
2b690 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e   text encodings.
2b6a0 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75    ^SQLite will u
2b6b0 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d  se.** the implem
2b6c0 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f  entation that mo
2b6d0 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68  st closely match
2b6e0 65 73 20 74 68 65 20 77 61 79 20 69 6e 20 77 68  es the way in wh
2b6f0 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66  ich the.** SQL f
2b700 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e  unction is used.
2b710 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d    ^A function im
2b720 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74  plementation wit
2b730 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65  h a non-negative
2b740 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74  .** nArg paramet
2b750 65 72 20 69 73 20 61 20 62 65 74 74 65 72 20 6d  er is a better m
2b760 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63  atch than a func
2b770 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
2b780 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65  ion with.** a ne
2b790 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20 5e 41  gative nArg.  ^A
2b7a0 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
2b7b0 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 65  the preferred te
2b7c0 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d  xt encoding.** m
2b7d0 61 74 63 68 65 73 20 74 68 65 20 64 61 74 61 62  atches the datab
2b7e0 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ase encoding is 
2b7f0 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63  a better.** matc
2b800 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
2b810 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
2b820 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e  ding is differen
2b830 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74  t.  .** ^A funct
2b840 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e  ion where the en
2b850 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63  coding differenc
2b860 65 20 69 73 20 62 65 74 77 65 65 6e 20 55 54 46  e is between UTF
2b870 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36 62 65  16le and UTF16be
2b880 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 20  .** is a closer 
2b890 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e  match than a fun
2b8a0 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
2b8b0 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65  encoding differe
2b8c0 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 65  nce is.** betwee
2b8d0 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46 31 36  n UTF8 and UTF16
2b8e0 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69  ..**.** ^Built-i
2b8f0 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20  n functions may 
2b900 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79  be overloaded by
2b910 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
2b920 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
2b930 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70  ns..**.** ^An ap
2b940 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2b950 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65  d function is pe
2b960 72 6d 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20  rmitted to call 
2b970 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20  other.** SQLite 
2b980 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77  interfaces.  How
2b990 65 76 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73  ever, such calls
2b9a0 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f   must not.** clo
2b9b0 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
2b9c0 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66  connection nor f
2b9d0 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74  inalize or reset
2b9e0 20 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a   the prepared.**
2b9f0 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68   statement in wh
2ba00 69 63 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ich the function
2ba10 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
2ba20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
2ba30 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73  te_function(.  s
2ba40 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
2ba50 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74  nst char *zFunct
2ba60 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
2ba70 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
2ba80 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
2ba90 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
2baa0 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
2bab0 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
2bac0 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
2bad0 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
2bae0 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
2baf0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
2bb00 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
2bb10 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
2bb20 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  t*).);.int sqlit
2bb30 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2bb40 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20  on16(.  sqlite3 
2bb50 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69  *db,.  const voi
2bb60 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  d *zFunctionName
2bb70 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
2bb80 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
2bb90 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f  void *pApp,.  vo
2bba0 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
2bbb0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
2bbc0 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
2bbd0 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
2bbe0 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
2bbf0 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
2bc00 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
2bc10 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
2bc20 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a  e3_context*).);.
2bc30 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
2bc40 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a  te_function_v2(.
2bc50 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20    sqlite3 *db,. 
2bc60 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75   const char *zFu
2bc70 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
2bc80 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
2bc90 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a  extRep,.  void *
2bca0 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78  pApp,.  void (*x
2bcb0 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
2bcc0 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
2bcd0 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
2bce0 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
2bcf0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
2bd00 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
2bd10 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
2bd20 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
2bd30 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a  text*),.  void(*
2bd40 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29  xDestroy)(void*)
2bd50 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
2bd60 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69  REF: Text Encodi
2bd70 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ngs.**.** These 
2bd80 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20  constant define 
2bd90 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74 68  integer codes th
2bda0 61 74 20 72 65 70 72 65 73 65 6e 74 20 74 68 65  at represent the
2bdb0 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74   various.** text
2bdc0 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f   encodings suppo
2bdd0 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a  rted by SQLite..
2bde0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2bdf0 45 5f 55 54 46 38 20 20 20 20 20 20 20 20 20 20  E_UTF8          
2be00 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
2be10 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20 20  E_UTF16LE       
2be20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
2be30 45 5f 55 54 46 31 36 42 45 20 20 20 20 20 20 20  E_UTF16BE       
2be40 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
2be50 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20 20  E_UTF16         
2be60 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74   4    /* Use nat
2be70 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a  ive byte order *
2be80 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
2be90 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20 20  _ANY            
2bea0 35 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  5    /* sqlite3_
2beb0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20  create_function 
2bec0 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
2bed0 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49  SQLITE_UTF16_ALI
2bee0 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71  GNED  8    /* sq
2bef0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
2bf00 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a  lation only */..
2bf10 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2bf20 44 65 70 72 65 63 61 74 65 64 20 46 75 6e 63 74  Deprecated Funct
2bf30 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 54  ions.** DEPRECAT
2bf40 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  ED.**.** These f
2bf50 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 65  unctions are [de
2bf60 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f  precated].  In o
2bf70 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e  rder to maintain
2bf80 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f  .** backwards co
2bf90 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 68  mpatibility with
2bfa0 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 65   older code, the
2bfb0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e  se functions con
2bfc0 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20  tinue .** to be 
2bfd0 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 65  supported.  Howe
2bfe0 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 61  ver, new applica
2bff0 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f  tions should avo
2c000 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66  id.** the use of
2c010 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
2c020 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75  .  To help encou
2c030 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f 20 61  rage people to a
2c040 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68  void.** using th
2c050 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77  ese functions, w
2c060 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20  e are not going 
2c070 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 68 61 74  to tell you what
2c080 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66   they do..*/.#if
2c090 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  ndef SQLITE_OMIT
2c0a0 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51 4c 49  _DEPRECATED.SQLI
2c0b0 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
2c0c0 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  t sqlite3_aggreg
2c0d0 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ate_count(sqlite
2c0e0 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c  3_context*);.SQL
2c0f0 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
2c100 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72  nt sqlite3_expir
2c110 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ed(sqlite3_stmt*
2c120 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
2c130 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
2c140 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e  _transfer_bindin
2c150 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  gs(sqlite3_stmt*
2c160 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  , sqlite3_stmt*)
2c170 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
2c180 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
2c190 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76  global_recover(v
2c1a0 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  oid);.SQLITE_DEP
2c1b0 52 45 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c  RECATED void sql
2c1c0 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61  ite3_thread_clea
2c1d0 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  nup(void);.SQLIT
2c1e0 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
2c1f0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
2c200 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f  alarm(void(*)(vo
2c210 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  id*,sqlite3_int6
2c220 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c 73 71 6c  4,int),void*,sql
2c230 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e  ite3_int64);.#en
2c240 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
2c250 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53  REF: Obtaining S
2c260 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61  QL Function Para
2c270 6d 65 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a 0a  meter Values.**.
2c280 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67  ** The C-languag
2c290 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2c2a0 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e   of SQL function
2c2b0 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
2c2c0 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65   uses.** this se
2c2d0 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72  t of interface r
2c2e0 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73  outines to acces
2c2f0 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  s the parameter 
2c300 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65  values on.** the
2c310 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
2c320 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  regate..**.** Th
2c330 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61  e xFunc (for sca
2c340 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f  lar functions) o
2c350 72 20 78 53 74 65 70 20 28 66 6f 72 20 61 67 67  r xStep (for agg
2c360 72 65 67 61 74 65 73 29 20 70 61 72 61 6d 65 74  regates) paramet
2c370 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  ers.** to [sqlit
2c380 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2c390 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  on()] and [sqlit
2c3a0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2c3b0 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e  on16()].** defin
2c3c0 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74  e callbacks that
2c3d0 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53   implement the S
2c3e0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
2c3f0 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20   aggregates..** 
2c400 54 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  The 3rd paramete
2c410 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62  r to these callb
2c420 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79  acks is an array
2c430 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a   of pointers to.
2c440 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  ** [protected sq
2c450 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2c460 65 63 74 73 2e 20 20 54 68 65 72 65 20 69 73 20  ects.  There is 
2c470 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  one [sqlite3_val
2c480 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a  ue] object for.*
2c490 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74 65 72  * each parameter
2c4a0 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63   to the SQL func
2c4b0 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75  tion.  These rou
2c4c0 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 74  tines are used t
2c4d0 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c  o.** extract val
2c4e0 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71  ues from the [sq
2c4f0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2c500 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ects..**.** Thes
2c510 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20  e routines work 
2c520 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65  only with [prote
2c530 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2c540 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  ue] objects..** 
2c550 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75  Any attempt to u
2c560 73 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  se these routine
2c570 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65  s on an [unprote
2c580 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2c590 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65  ue].** object re
2c5a0 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e  sults in undefin
2c5b0 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a  ed behavior..**.
2c5c0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
2c5d0 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b  es work just lik
2c5e0 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  e the correspond
2c5f0 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65  ing [column acce
2c600 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a  ss functions].**
2c610 20 65 78 63 65 70 74 20 74 68 61 74 20 20 74 68   except that  th
2c620 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b  ese routines tak
2c630 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74  e a single [prot
2c640 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2c650 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70  lue] object.** p
2c660 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f  ointer instead o
2c670 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  f a [sqlite3_stm
2c680 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20  t*] pointer and 
2c690 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d  an integer colum
2c6a0 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20  n number..**.** 
2c6b0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
2c6c0 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65  ue_text16() inte
2c6d0 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20 61  rface extracts a
2c6e0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a   UTF-16 string.*
2c6f0 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  * in the native 
2c700 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68  byte-order of th
2c710 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20  e host machine. 
2c720 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
2c730 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28  _value_text16be(
2c740 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61  ) and sqlite3_va
2c750 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69  lue_text16le() i
2c760 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74  nterfaces.** ext
2c770 72 61 63 74 20 55 54 46 2d 31 36 20 73 74 72 69  ract UTF-16 stri
2c780 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61  ngs as big-endia
2c790 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64  n and little-end
2c7a0 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79  ian respectively
2c7b0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71  ..**.** ^(The sq
2c7c0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65  lite3_value_nume
2c7d0 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72  ric_type() inter
2c7e0 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
2c7f0 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69   apply.** numeri
2c800 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68  c affinity to th
2c810 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d  e value.  This m
2c820 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74  eans that an att
2c830 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20  empt is.** made 
2c840 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76  to convert the v
2c850 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67  alue to an integ
2c860 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70  er or floating p
2c870 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63  oint.  If.** suc
2c880 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  h a conversion i
2c890 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f  s possible witho
2c8a0 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72  ut loss of infor
2c8b0 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72  mation (in other
2c8c0 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68  .** words, if th
2c8d0 65 20 76 61 6c 75 65 20 69 73 20 61 20 73 74 72  e value is a str
2c8e0 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c  ing that looks l
2c8f0 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a  ike a number).**
2c900 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72   then the conver
2c910 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65  sion is performe
2c920 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f  d.  Otherwise no
2c930 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75   conversion occu
2c940 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  rs..** The [SQLI
2c950 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74  TE_INTEGER | dat
2c960 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e  atype] after con
2c970 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72  version is retur
2c980 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65  ned.)^.**.** Ple
2c990 61 73 65 20 70 61 79 20 70 61 72 74 69 63 75 6c  ase pay particul
2c9a0 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20  ar attention to 
2c9b0 74 68 65 20 66 61 63 74 20 74 68 61 74 20 74 68  the fact that th
2c9c0 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e  e pointer return
2c9d0 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ed.** from [sqli
2c9e0 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29  te3_value_blob()
2c9f0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
2ca00 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a  e_text()], or.**
2ca10 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2ca20 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65  text16()] can be
2ca30 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20   invalidated by 
2ca40 61 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  a subsequent cal
2ca50 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
2ca60 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c  _value_bytes()],
2ca70 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2ca80 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c  bytes16()], [sql
2ca90 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
2caa0 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  )],.** or [sqlit
2cab0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
2cac0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  )]..**.** These 
2cad0 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65  routines must be
2cae0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
2caf0 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a   same thread as.
2cb00 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  ** the SQL funct
2cb10 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65  ion that supplie
2cb20 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  d the [sqlite3_v
2cb30 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72  alue*] parameter
2cb40 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64  s..*/.const void
2cb50 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
2cb60 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 6c  blob(sqlite3_val
2cb70 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
2cb80 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71  3_value_bytes(sq
2cb90 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
2cba0 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
2cbb0 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33  _bytes16(sqlite3
2cbc0 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65  _value*);.double
2cbd0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64   sqlite3_value_d
2cbe0 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 61  ouble(sqlite3_va
2cbf0 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
2cc00 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c  e3_value_int(sql
2cc10 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71  ite3_value*);.sq
2cc20 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
2cc30 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28  te3_value_int64(
2cc40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2cc50 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20  .const unsigned 
2cc60 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 61  char *sqlite3_va
2cc70 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65 33  lue_text(sqlite3
2cc80 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
2cc90 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
2cca0 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74  lue_text16(sqlit
2ccb0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73  e3_value*);.cons
2ccc0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2ccd0 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73  value_text16le(s
2cce0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2ccf0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2cd00 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
2cd10 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  be(sqlite3_value
2cd20 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
2cd30 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 74  value_type(sqlit
2cd40 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
2cd50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75  sqlite3_value_nu
2cd60 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74  meric_type(sqlit
2cd70 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a  e3_value*);../*.
2cd80 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74  ** CAPI3REF: Obt
2cd90 61 69 6e 20 41 67 67 72 65 67 61 74 65 20 46 75  ain Aggregate Fu
2cda0 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a  nction Context.*
2cdb0 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74  *.** Implementat
2cdc0 69 6f 6e 73 20 6f 66 20 61 67 67 72 65 67 61 74  ions of aggregat
2cdd0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  e SQL functions 
2cde0 75 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74  use this.** rout
2cdf0 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ine to allocate 
2ce00 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72 69  memory for stori
2ce10 6e 67 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a  ng their state..
2ce20 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
2ce30 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65   time the sqlite
2ce40 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
2ce50 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65  ext(C,N) routine
2ce60 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66   is called .** f
2ce70 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
2ce80 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
2ce90 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c  on, SQLite.** al
2cea0 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d  locates N of mem
2ceb0 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20  ory, zeroes out 
2cec0 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64  that memory, and
2ced0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2cee0 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77  er.** to the new
2cef0 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63   memory. ^On sec
2cf00 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65  ond and subseque
2cf10 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73  nt calls to.** s
2cf20 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
2cf30 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74  _context() for t
2cf40 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74  he same aggregat
2cf50 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61  e function insta
2cf60 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65  nce,.** the same
2cf70 20 62 75 66 66 65 72 20 69 73 20 72 65 74 75 72   buffer is retur
2cf80 6e 65 64 2e 20 20 53 71 6c 69 74 65 33 5f 61 67  ned.  Sqlite3_ag
2cf90 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
2cfa0 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a  ) is normally.**
2cfb0 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72   called once for
2cfc0 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e   each invocation
2cfd0 20 6f 66 20 74 68 65 20 78 53 74 65 70 20 63 61   of the xStep ca
2cfe0 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68 65 6e 20  llback and then 
2cff0 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65  one.** last time
2d000 20 77 68 65 6e 20 74 68 65 20 78 46 69 6e 61 6c   when the xFinal
2d010 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
2d020 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f  oked.  ^(When no
2d030 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61   rows match.** a
2d040 6e 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72  n aggregate quer
2d050 79 2c 20 74 68 65 20 78 53 74 65 70 28 29 20 63  y, the xStep() c
2d060 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 61  allback of the a
2d070 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
2d080 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  n.** implementat
2d090 69 6f 6e 20 69 73 20 6e 65 76 65 72 20 63 61 6c  ion is never cal
2d0a0 6c 65 64 20 61 6e 64 20 78 46 69 6e 61 6c 28 29  led and xFinal()
2d0b0 20 69 73 20 63 61 6c 6c 65 64 20 65 78 61 63 74   is called exact
2d0c0 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74  ly once..** In t
2d0d0 68 6f 73 65 20 63 61 73 65 73 2c 20 73 71 6c 69  hose cases, sqli
2d0e0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
2d0f0 6e 74 65 78 74 28 29 20 6d 69 67 68 74 20 62 65  ntext() might be
2d100 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a   called for the.
2d110 2a 2a 20 66 69 72 73 74 20 74 69 6d 65 20 66 72  ** first time fr
2d120 6f 6d 20 77 69 74 68 69 6e 20 78 46 69 6e 61 6c  om within xFinal
2d130 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().)^.**.** ^The
2d140 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
2d150 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20  te_context(C,N) 
2d160 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
2d170 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
2d180 66 20 4e 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74  f N is.** less t
2d190 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  han or equal to 
2d1a0 7a 65 72 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d  zero or if a mem
2d1b0 6f 72 79 20 61 6c 6c 6f 63 61 74 65 20 65 72 72  ory allocate err
2d1c0 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a  or occurs..**.**
2d1d0 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66   ^(The amount of
2d1e0 20 73 70 61 63 65 20 61 6c 6c 6f 63 61 74 65 64   space allocated
2d1f0 20 62 79 20 73 71 6c 69 74 65 33 5f 61 67 67 72   by sqlite3_aggr
2d200 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
2d210 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69  N) is.** determi
2d220 6e 65 64 20 62 79 20 74 68 65 20 4e 20 70 61 72  ned by the N par
2d230 61 6d 65 74 65 72 20 6f 6e 20 66 69 72 73 74 20  ameter on first 
2d240 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e  successful call.
2d250 20 20 43 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a    Changing the.*
2d260 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20  * value of N in 
2d270 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20  subsequent call 
2d280 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  to sqlite3_aggre
2d290 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77  gate_context() w
2d2a0 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d  ithin.** the sam
2d2b0 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
2d2c0 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77 69  tion instance wi
2d2d0 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20 74 68  ll not resize th
2d2e0 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
2d2f0 63 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20  cation.)^.**.** 
2d300 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69  ^SQLite automati
2d310 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20  cally frees the 
2d320 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64  memory allocated
2d330 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   by .** sqlite3_
2d340 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
2d350 74 28 29 20 77 68 65 6e 20 74 68 65 20 61 67 67  t() when the agg
2d360 72 65 67 61 74 65 20 71 75 65 72 79 20 63 6f 6e  regate query con
2d370 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  cludes..**.** Th
2d380 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
2d390 72 20 6d 75 73 74 20 62 65 20 61 20 63 6f 70 79  r must be a copy
2d3a0 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
2d3b0 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51  te3_context | SQ
2d3c0 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65  L function conte
2d3d0 78 74 5d 20 74 68 61 74 20 69 73 20 74 68 65 20  xt] that is the 
2d3e0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a  first parameter.
2d3f0 2a 2a 20 74 6f 20 74 68 65 20 78 53 74 65 70 20  ** to the xStep 
2d400 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61  or xFinal callba
2d410 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20  ck routine that 
2d420 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61  implements the a
2d430 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63  ggregate.** func
2d440 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  tion..**.** This
2d450 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65   routine must be
2d460 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
2d470 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
2d480 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67  which.** the agg
2d490 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
2d4a0 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
2d4b0 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
2d4c0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
2d4d0 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt(sqlite3_conte
2d4e0 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29  xt*, int nBytes)
2d4f0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2d500 46 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f 72  F: User Data For
2d510 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
2d520 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73   ^The sqlite3_us
2d530 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66  er_data() interf
2d540 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f  ace returns a co
2d550 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69  py of.** the poi
2d560 6e 74 65 72 20 74 68 61 74 20 77 61 73 20 74 68  nter that was th
2d570 65 20 70 55 73 65 72 44 61 74 61 20 70 61 72 61  e pUserData para
2d580 6d 65 74 65 72 20 28 74 68 65 20 35 74 68 20 70  meter (the 5th p
2d590 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20  arameter).** of 
2d5a0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
2d5b0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a  ate_function()].
2d5c0 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
2d5d0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
2d5e0 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68  6()] routines th
2d5f0 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a  at originally.**
2d600 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20   registered the 
2d610 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
2d620 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ned function..**
2d630 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
2d640 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
2d650 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
2d660 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
2d670 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2d680 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
2d690 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  n is running..*/
2d6a0 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75  .void *sqlite3_u
2d6b0 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33  ser_data(sqlite3
2d6c0 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a  _context*);../*.
2d6d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74  ** CAPI3REF: Dat
2d6e0 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
2d6f0 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a   For Functions.*
2d700 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2d710 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e  3_context_db_han
2d720 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  dle() interface 
2d730 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
2d740 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72  f.** the pointer
2d750 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73   to the [databas
2d760 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74  e connection] (t
2d770 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72  he 1st parameter
2d780 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  ).** of the [sql
2d790 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2d7a0 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  tion()].** and [
2d7b0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2d7c0 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75  unction16()] rou
2d7d0 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69  tines that origi
2d7e0 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65  nally.** registe
2d7f0 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  red the applicat
2d800 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63  ion defined func
2d810 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  tion..*/.sqlite3
2d820 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   *sqlite3_contex
2d830 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69  t_db_handle(sqli
2d840 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a  te3_context*);..
2d850 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2d860 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61  Function Auxilia
2d870 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68  ry Data.**.** Th
2d880 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20  e following two 
2d890 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65  functions may be
2d8a0 20 75 73 65 64 20 62 79 20 73 63 61 6c 61 72 20   used by scalar 
2d8b0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f  SQL functions to
2d8c0 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65  .** associate me
2d8d0 74 61 64 61 74 61 20 77 69 74 68 20 61 72 67 75  tadata with argu
2d8e0 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 20  ment values. If 
2d8f0 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20 69  the same value i
2d900 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d  s passed to.** m
2d910 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69  ultiple invocati
2d920 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
2d930 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 72  SQL function dur
2d940 69 6e 67 20 71 75 65 72 79 20 65 78 65 63 75 74  ing query execut
2d950 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f  ion, under.** so
2d960 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73  me circumstances
2d970 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 64 20   the associated 
2d980 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62 65 20  metadata may be 
2d990 70 72 65 73 65 72 76 65 64 2e 20 54 68 69 73 20  preserved. This 
2d9a0 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65 64 2c 20  may.** be used, 
2d9b0 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20  for example, to 
2d9c0 61 64 64 20 61 20 72 65 67 75 6c 61 72 2d 65 78  add a regular-ex
2d9d0 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e  pression matchin
2d9e0 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75 6e 63  g scalar.** func
2d9f0 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c  tion. The compil
2da00 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68  ed version of th
2da10 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73  e regular expres
2da20 73 69 6f 6e 20 69 73 20 73 74 6f 72 65 64 20 61  sion is stored a
2da30 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20 61 73  s.** metadata as
2da40 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
2da50 65 20 53 51 4c 20 76 61 6c 75 65 20 70 61 73 73  e SQL value pass
2da60 65 64 20 61 73 20 74 68 65 20 72 65 67 75 6c 61  ed as the regula
2da70 72 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20  r expression.** 
2da80 70 61 74 74 65 72 6e 2e 20 20 54 68 65 20 63 6f  pattern.  The co
2da90 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20 65  mpiled regular e
2daa0 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65  xpression can be
2dab0 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69   reused on multi
2dac0 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f  ple.** invocatio
2dad0 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66  ns of the same f
2dae0 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61 74 20  unction so that 
2daf0 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 70 61 74  the original pat
2db00 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a 20 64  tern string.** d
2db10 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
2db20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64 20 6f 6e  be recompiled on
2db30 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e   each invocation
2db40 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2db50 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
2db60 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
2db70 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
2db80 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a  o the metadata.*
2db90 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62 79 20  * associated by 
2dba0 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  the sqlite3_set_
2dbb0 61 75 78 64 61 74 61 28 29 20 66 75 6e 63 74 69  auxdata() functi
2dbc0 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68 20  on with the Nth 
2dbd0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75  argument.** valu
2dbe0 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  e to the applica
2dbf0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
2dc00 63 74 69 6f 6e 2e 20 5e 49 66 20 6e 6f 20 6d 65  ction. ^If no me
2dc10 74 61 64 61 74 61 20 68 61 73 20 62 65 65 6e 20  tadata has been 
2dc20 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20 73 65 74  ever.** been set
2dc30 20 66 6f 72 20 74 68 65 20 4e 74 68 20 61 72 67   for the Nth arg
2dc40 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 66 75 6e  ument of the fun
2dc50 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74 68 65  ction, or if the
2dc60 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a   corresponding.*
2dc70 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d  * function param
2dc80 65 74 65 72 20 68 61 73 20 63 68 61 6e 67 65 64  eter has changed
2dc90 20 73 69 6e 63 65 20 74 68 65 20 6d 65 74 61 2d   since the meta-
2dca0 64 61 74 61 20 77 61 73 20 73 65 74 2c 0a 2a 2a  data was set,.**
2dcb0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 67 65   then sqlite3_ge
2dcc0 74 5f 61 75 78 64 61 74 61 28 29 20 72 65 74 75  t_auxdata() retu
2dcd0 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
2dce0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
2dcf0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
2dd00 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ta() interface s
2dd10 61 76 65 73 20 74 68 65 20 6d 65 74 61 64 61 74  aves the metadat
2dd20 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20  a.** pointed to 
2dd30 62 79 20 69 74 73 20 33 72 64 20 70 61 72 61 6d  by its 3rd param
2dd40 65 74 65 72 20 61 73 20 74 68 65 20 6d 65 74 61  eter as the meta
2dd50 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74  data for the N-t
2dd60 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66  h.** argument of
2dd70 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2dd80 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
2dd90 6e 2e 20 20 53 75 62 73 65 71 75 65 6e 74 0a 2a  n.  Subsequent.*
2dda0 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  * calls to sqlit
2ddb0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
2ddc0 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20 74 68   might return th
2ddd0 69 73 20 64 61 74 61 2c 20 69 66 20 69 74 20 68  is data, if it h
2dde0 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e 20 64  as.** not been d
2ddf0 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 5e 49 66  estroyed..** ^If
2de00 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c   it is not NULL,
2de10 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76   SQLite will inv
2de20 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74  oke the destruct
2de30 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 67  or.** function g
2de40 69 76 65 6e 20 62 79 20 74 68 65 20 34 74 68 20  iven by the 4th 
2de50 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
2de60 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
2de70 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65 74  () on.** the met
2de80 61 64 61 74 61 20 77 68 65 6e 20 74 68 65 20 63  adata when the c
2de90 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e  orresponding fun
2dea0 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20  ction parameter 
2deb0 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 68  changes.** or wh
2dec0 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  en the SQL state
2ded0 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73 2c 20  ment completes, 
2dee0 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20  whichever comes 
2def0 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  first..**.** SQL
2df00 69 74 65 20 69 73 20 66 72 65 65 20 74 6f 20 63  ite is free to c
2df10 61 6c 6c 20 74 68 65 20 64 65 73 74 72 75 63 74  all the destruct
2df20 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d 65 74 61  or and drop meta
2df30 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70  data on any.** p
2df40 61 72 61 6d 65 74 65 72 20 6f 66 20 61 6e 79 20  arameter of any 
2df50 66 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e 79 20  function at any 
2df60 74 69 6d 65 2e 20 20 5e 54 68 65 20 6f 6e 6c 79  time.  ^The only
2df70 20 67 75 61 72 61 6e 74 65 65 20 69 73 20 74 68   guarantee is th
2df80 61 74 0a 2a 2a 20 74 68 65 20 64 65 73 74 72 75  at.** the destru
2df90 63 74 6f 72 20 77 69 6c 6c 20 62 65 20 63 61 6c  ctor will be cal
2dfa0 6c 65 64 20 62 65 66 6f 72 65 20 74 68 65 20 6d  led before the m
2dfb0 65 74 61 64 61 74 61 20 69 73 20 64 72 6f 70 70  etadata is dropp
2dfc0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70  ed..**.** ^(In p
2dfd0 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64 61 74  ractice, metadat
2dfe0 61 20 69 73 20 70 72 65 73 65 72 76 65 64 20 62  a is preserved b
2dff0 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20  etween function 
2e000 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70  calls for.** exp
2e010 72 65 73 73 69 6f 6e 73 20 74 68 61 74 20 61 72  ressions that ar
2e020 65 20 63 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f  e constant at co
2e030 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54 68 69 73  mpile time. This
2e040 20 69 6e 63 6c 75 64 65 73 20 6c 69 74 65 72 61   includes litera
2e050 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20  l.** values and 
2e060 5b 70 61 72 61 6d 65 74 65 72 73 5d 2e 29 5e 0a  [parameters].)^.
2e070 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
2e080 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c  ines must be cal
2e090 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
2e0a0 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
2e0b0 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e  h.** the SQL fun
2e0c0 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
2e0d0 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
2e0e0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73  e3_get_auxdata(s
2e0f0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2e100 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20 73 71   int N);.void sq
2e110 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
2e120 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
2e130 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a  t*, int N, void*
2e140 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a  , void (*)(void*
2e150 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ));.../*.** CAPI
2e160 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20  3REF: Constants 
2e170 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c  Defining Special
2e180 20 44 65 73 74 72 75 63 74 6f 72 20 42 65 68 61   Destructor Beha
2e190 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  vior.**.** These
2e1a0 20 61 72 65 20 73 70 65 63 69 61 6c 20 76 61 6c   are special val
2e1b0 75 65 73 20 66 6f 72 20 74 68 65 20 64 65 73 74  ues for the dest
2e1c0 72 75 63 74 6f 72 20 74 68 61 74 20 69 73 20 70  ructor that is p
2e1d0 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a  assed in as the.
2e1e0 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e  ** final argumen
2e1f0 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69  t to routines li
2e200 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  ke [sqlite3_resu
2e210 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e 49 66  lt_blob()].  ^If
2e220 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a   the destructor.
2e230 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 53  ** argument is S
2e240 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69 74  QLITE_STATIC, it
2e250 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
2e260 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72 20  content pointer 
2e270 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61  is constant.** a
2e280 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63 68  nd will never ch
2e290 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20 6e  ange.  It does n
2e2a0 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64 65  ot need to be de
2e2b0 73 74 72 6f 79 65 64 2e 20 20 5e 54 68 65 0a 2a  stroyed.  ^The.*
2e2c0 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  * SQLITE_TRANSIE
2e2d0 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20 74  NT value means t
2e2e0 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  hat the content 
2e2f0 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e  will likely chan
2e300 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61  ge in.** the nea
2e310 72 20 66 75 74 75 72 65 20 61 6e 64 20 74 68 61  r future and tha
2e320 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64 20  t SQLite should 
2e330 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72 69  make its own pri
2e340 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  vate copy of.** 
2e350 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f  the content befo
2e360 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a  re returning..**
2e370 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66 20  .** The typedef 
2e380 69 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20  is necessary to 
2e390 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62  work around prob
2e3a0 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e 0a  lems in certain.
2e3b0 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73  ** C++ compilers
2e3c0 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20 23 32  .  See ticket #2
2e3d0 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  191..*/.typedef 
2e3e0 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64  void (*sqlite3_d
2e3f0 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28  estructor_type)(
2e400 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20  void*);.#define 
2e410 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20  SQLITE_STATIC   
2e420 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73     ((sqlite3_des
2e430 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a  tructor_type)0).
2e440 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
2e450 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c  RANSIENT   ((sql
2e460 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f  ite3_destructor_
2e470 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20  type)-1)../*.** 
2e480 43 41 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e  CAPI3REF: Settin
2e490 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20  g The Result Of 
2e4a0 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a  An SQL Function.
2e4b0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
2e4c0 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 62 79  ines are used by
2e4d0 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46   the xFunc or xF
2e4e0 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74  inal callbacks t
2e4f0 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  hat.** implement
2e500 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61   SQL functions a
2e510 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 20 20  nd aggregates.  
2e520 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  See.** [sqlite3_
2e530 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2e540 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
2e550 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
2e560 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69  6()].** for addi
2e570 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
2e580 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  on..**.** These 
2e590 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76  functions work v
2e5a0 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68  ery much like th
2e5b0 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62 69 6e  e [parameter bin
2e5c0 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a  ding] family of.
2e5d0 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65  ** functions use
2e5e0 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73  d to bind values
2e5f0 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74   to host paramet
2e600 65 72 73 20 69 6e 20 70 72 65 70 61 72 65 64 20  ers in prepared 
2e610 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52  statements..** R
2e620 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53 51 4c  efer to the [SQL
2e630 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f 63 75   parameter] docu
2e640 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64  mentation for ad
2e650 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
2e660 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tion..**.** ^The
2e670 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2e680 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65  blob() interface
2e690 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74   sets the result
2e6a0 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c   from.** an appl
2e6b0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2e6c0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74  function to be t
2e6d0 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f  he BLOB whose co
2e6e0 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64  ntent is pointed
2e6f0 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65  .** to by the se
2e700 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61  cond parameter a
2e710 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20 62 79  nd which is N by
2e720 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e  tes long where N
2e730 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64   is the.** third
2e740 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
2e750 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
2e760 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29  esult_zeroblob()
2e770 20 69 6e 74 65 72 66 61 63 65 73 20 73 65 74 20   interfaces set 
2e780 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a  the result of.**
2e790 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2e7a0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
2e7b0 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 63  n to be a BLOB c
2e7c0 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65  ontaining all ze
2e7d0 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 20  ro.** bytes and 
2e7e0 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2c  N bytes in size,
2e7f0 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
2e800 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32 6e 64  value of the 2nd
2e810 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
2e820 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
2e830 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69  esult_double() i
2e840 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
2e850 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a  e result from.**
2e860 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
2e870 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2e880 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e   to be a floatin
2e890 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70  g point value sp
2e8a0 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74  ecified.** by it
2e8b0 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  s 2nd argument..
2e8c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2e8d0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
2e8e0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  ) and sqlite3_re
2e8f0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66  sult_error16() f
2e900 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73  unctions.** caus
2e910 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65  e the implemente
2e920 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  d SQL function t
2e930 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70  o throw an excep
2e940 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  tion..** ^SQLite
2e950 20 75 73 65 73 20 74 68 65 20 73 74 72 69 6e 67   uses the string
2e960 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74   pointed to by t
2e970 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65  he.** 2nd parame
2e980 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 72  ter of sqlite3_r
2e990 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72  esult_error() or
2e9a0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2e9b0 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20  error16().** as 
2e9c0 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20 65  the text of an e
2e9d0 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 5e  rror message.  ^
2e9e0 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74  SQLite interpret
2e9f0 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d  s the error.** m
2ea00 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 66 72  essage string fr
2ea10 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  om sqlite3_resul
2ea20 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55 54 46  t_error() as UTF
2ea30 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 69  -8. ^SQLite.** i
2ea40 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 73 74  nterprets the st
2ea50 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65  ring from sqlite
2ea60 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
2ea70 28 29 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  () as UTF-16 in 
2ea80 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f  native.** byte o
2ea90 72 64 65 72 2e 20 20 5e 49 66 20 74 68 65 20 74  rder.  ^If the t
2eaa0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
2eab0 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
2eac0 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73  _error().** or s
2ead0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2eae0 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67 61 74  ror16() is negat
2eaf0 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20  ive then SQLite 
2eb00 74 61 6b 65 73 20 61 73 20 74 68 65 20 65 72 72  takes as the err
2eb10 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c  or.** message al
2eb20 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f 75 67  l text up throug
2eb30 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  h the first zero
2eb40 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e   character..** ^
2eb50 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72  If the third par
2eb60 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
2eb70 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
2eb80 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72   or.** sqlite3_r
2eb90 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
2eba0 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20  is non-negative 
2ebb0 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65  then SQLite take
2ebc0 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62  s that many.** b
2ebd0 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63  ytes (not charac
2ebe0 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32  ters) from the 2
2ebf0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20  nd parameter as 
2ec00 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
2ec10 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  e..** ^The sqlit
2ec20 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
2ec30 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  ) and sqlite3_re
2ec40 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a  sult_error16().*
2ec50 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20  * routines make 
2ec60 61 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  a private copy o
2ec70 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  f the error mess
2ec80 61 67 65 20 74 65 78 74 20 62 65 66 6f 72 65 0a  age text before.
2ec90 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e 2e 20  ** they return. 
2eca0 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c   Hence, the call
2ecb0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e  ing function can
2ecc0 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a   deallocate or.*
2ecd0 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65 78  * modify the tex
2ece0 74 20 61 66 74 65 72 20 74 68 65 79 20 72 65 74  t after they ret
2ecf0 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72 6d  urn without harm
2ed00 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
2ed10 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63  3_result_error_c
2ed20 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 63  ode() function c
2ed30 68 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f 72  hanges the error
2ed40 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65   code.** returne
2ed50 64 20 62 79 20 53 51 4c 69 74 65 20 61 73 20 61  d by SQLite as a
2ed60 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 72   result of an er
2ed70 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69 6f  ror in a functio
2ed80 6e 2e 20 20 5e 42 79 20 64 65 66 61 75 6c 74 2c  n.  ^By default,
2ed90 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f  .** the error co
2eda0 64 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52  de is SQLITE_ERR
2edb0 4f 52 2e 20 20 5e 41 20 73 75 62 73 65 71 75 65  OR.  ^A subseque
2edc0 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  nt call to sqlit
2edd0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
2ede0 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
2edf0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
2ee00 20 72 65 73 65 74 73 20 74 68 65 20 65 72 72 6f   resets the erro
2ee10 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45  r code to SQLITE
2ee20 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54  _ERROR..**.** ^T
2ee30 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2ee40 74 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72  t_toobig() inter
2ee50 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69  face causes SQLi
2ee60 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65  te to throw an e
2ee70 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69  rror.** indicati
2ee80 6e 67 20 74 68 61 74 20 61 20 73 74 72 69 6e 67  ng that a string
2ee90 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f 20   or BLOB is too 
2eea0 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e  long to represen
2eeb0 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  t..**.** ^The sq
2eec0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 6f 6d  lite3_result_nom
2eed0 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65 20 63  em() interface c
2eee0 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20  auses SQLite to 
2eef0 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a  throw an error.*
2ef00 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61  * indicating tha
2ef10 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  t a memory alloc
2ef20 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a  ation failed..**
2ef30 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2ef40 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e  _result_int() in
2ef50 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
2ef60 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
2ef70 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
2ef80 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
2ef90 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 33  tion to be the 3
2efa0 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  2-bit signed int
2efb0 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69  eger.** value gi
2efc0 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61  ven in the 2nd a
2efd0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  rgument..** ^The
2efe0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2eff0 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66 61 63  int64() interfac
2f000 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72  e sets the retur
2f010 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68  n value.** of th
2f020 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
2f030 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
2f040 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69 74 20  o be the 64-bit 
2f050 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a  signed integer.*
2f060 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e  * value given in
2f070 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e   the 2nd argumen
2f080 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  t..**.** ^The sq
2f090 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c  lite3_result_nul
2f0a0 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  l() interface se
2f0b0 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ts the return va
2f0c0 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70  lue.** of the ap
2f0d0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2f0e0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
2f0f0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   NULL..**.** ^Th
2f100 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2f110 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33  _text(), sqlite3
2f120 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29  _result_text16()
2f130 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  ,.** sqlite3_res
2f140 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 2c 20  ult_text16le(), 
2f150 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  and sqlite3_resu
2f160 6c 74 5f 74 65 78 74 31 36 62 65 28 29 20 69 6e  lt_text16be() in
2f170 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 20  terfaces.** set 
2f180 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
2f190 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
2f1a0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
2f1b0 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20  tion to be.** a 
2f1c0 74 65 78 74 20 73 74 72 69 6e 67 20 77 68 69 63  text string whic
2f1d0 68 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64  h is represented
2f1e0 20 61 73 20 55 54 46 2d 38 2c 20 55 54 46 2d 31   as UTF-8, UTF-1
2f1f0 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  6 native byte or
2f200 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c  der,.** UTF-16 l
2f210 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72  ittle endian, or
2f220 20 55 54 46 2d 31 36 20 62 69 67 20 65 6e 64 69   UTF-16 big endi
2f230 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79  an, respectively
2f240 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 74 61 6b  ..** ^SQLite tak
2f250 65 73 20 74 68 65 20 74 65 78 74 20 72 65 73 75  es the text resu
2f260 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 70 70 6c  lt from the appl
2f270 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20  ication from.** 
2f280 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
2f290 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  r of the sqlite3
2f2a0 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
2f2b0 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 5e 49 66  terfaces..** ^If
2f2c0 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
2f2d0 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
2f2e0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
2f2f0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20  nterfaces.** is 
2f300 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 53  negative, then S
2f310 51 4c 69 74 65 20 74 61 6b 65 73 20 72 65 73 75  QLite takes resu
2f320 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 74 68 65  lt text from the
2f330 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a   2nd parameter.*
2f340 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69  * through the fi
2f350 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74  rst zero charact
2f360 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33  er..** ^If the 3
2f370 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
2f380 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
2f390 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
2f3a0 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65  ces.** is non-ne
2f3b0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73 20  gative, then as 
2f3c0 6d 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 20  many bytes (not 
2f3d0 63 68 61 72 61 63 74 65 72 73 29 20 6f 66 20 74  characters) of t
2f3e0 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74  he text.** point
2f3f0 65 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e 64  ed to by the 2nd
2f400 20 70 61 72 61 6d 65 74 65 72 20 61 72 65 20 74   parameter are t
2f410 61 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70 6c  aken as the appl
2f420 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a  ication-defined.
2f430 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 75  ** function resu
2f440 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34  lt..** ^If the 4
2f450 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
2f460 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
2f470 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
2f480 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  ces.** or sqlite
2f490 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73  3_result_blob is
2f4a0 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
2f4b0 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ter, then SQLite
2f4c0 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66   calls that.** f
2f4d0 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64  unction as the d
2f4e0 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65  estructor on the
2f4f0 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65   text or BLOB re
2f500 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73  sult when it has
2f510 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69  .** finished usi
2f520 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a  ng that result..
2f530 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70  ** ^If the 4th p
2f540 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
2f550 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2f560 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20  ext* interfaces 
2f570 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  or to.** sqlite3
2f580 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20  _result_blob is 
2f590 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73  the special cons
2f5a0 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54  tant SQLITE_STAT
2f5b0 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a  IC, then SQLite.
2f5c0 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  ** assumes that 
2f5d0 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42  the text or BLOB
2f5e0 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f   result is in co
2f5f0 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64  nstant space and
2f600 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70   does not.** cop
2f610 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  y the content of
2f620 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6e   the parameter n
2f630 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75  or call a destru
2f640 63 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74  ctor on the cont
2f650 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68  ent.** when it h
2f660 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e  as finished usin
2f670 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a  g that result..*
2f680 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61  * ^If the 4th pa
2f690 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
2f6a0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
2f6b0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
2f6c0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
2f6d0 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20  ult_blob is the 
2f6e0 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74  special constant
2f6f0 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e   SQLITE_TRANSIEN
2f700 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65  T.** then SQLite
2f710 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
2f720 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f   the result into
2f730 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20   space obtained 
2f740 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  from.** from [sq
2f750 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
2f760 62 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e  before it return
2f770 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
2f780 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
2f790 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ue() interface s
2f7a0 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f  ets the result o
2f7b0 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  f.** the applica
2f7c0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
2f7d0 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f  ction to be a co
2f7e0 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f  py the.** [unpro
2f7f0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2f800 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 65  alue] object spe
2f810 63 69 66 69 65 64 20 62 79 20 74 68 65 20 32 6e  cified by the 2n
2f820 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54  d parameter.  ^T
2f830 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  he.** sqlite3_re
2f840 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74  sult_value() int
2f850 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63  erface makes a c
2f860 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  opy of the [sqli
2f870 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f  te3_value].** so
2f880 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74   that the [sqlit
2f890 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66  e3_value] specif
2f8a0 69 65 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d  ied in the param
2f8b0 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20  eter may change 
2f8c0 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63  or.** be dealloc
2f8d0 61 74 65 64 20 61 66 74 65 72 20 73 71 6c 69 74  ated after sqlit
2f8e0 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
2f8f0 29 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75  ) returns withou
2f900 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70  t harm..** ^A [p
2f910 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2f920 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d  _value] object m
2f930 61 79 20 61 6c 77 61 79 73 20 62 65 20 75 73 65  ay always be use
2f940 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75  d where an.** [u
2f950 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2f960 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2f970 20 69 73 20 72 65 71 75 69 72 65 64 2c 20 73 6f   is required, so
2f980 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20   either.** kind 
2f990 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  of [sqlite3_valu
2f9a0 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 65  e] object can be
2f9b0 20 75 73 65 64 20 77 69 74 68 20 74 68 69 73 20   used with this 
2f9c0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
2f9d0 20 49 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   If these routin
2f9e0 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72  es are called fr
2f9f0 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64 69  om within the di
2fa00 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 0a 2a  fferent thread.*
2fa10 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63  * than the one c
2fa20 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70  ontaining the ap
2fa30 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2fa40 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  d function that 
2fa50 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65 20  received.** the 
2fa60 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
2fa70 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72  ] pointer, the r
2fa80 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
2fa90 69 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  ined..*/.void sq
2faa0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
2fab0 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  b(sqlite3_contex
2fac0 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
2fad0 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
2fae0 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
2faf0 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c  te3_result_doubl
2fb00 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
2fb10 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69  t*, double);.voi
2fb20 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2fb30 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63  _error(sqlite3_c
2fb40 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63  ontext*, const c
2fb50 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  har*, int);.void
2fb60 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2fb70 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f  error16(sqlite3_
2fb80 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
2fb90 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  void*, int);.voi
2fba0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2fbb0 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71  _error_toobig(sq
2fbc0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
2fbd0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
2fbe0 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d  sult_error_nomem
2fbf0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2fc00 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
2fc10 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f  _result_error_co
2fc20 64 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  de(sqlite3_conte
2fc30 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  xt*, int);.void 
2fc40 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
2fc50 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  nt(sqlite3_conte
2fc60 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  xt*, int);.void 
2fc70 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
2fc80 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nt64(sqlite3_con
2fc90 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69  text*, sqlite3_i
2fca0 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69  nt64);.void sqli
2fcb0 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28  te3_result_null(
2fcc0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2fcd0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2fce0 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69  result_text(sqli
2fcf0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
2fd00 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20  nst char*, int, 
2fd10 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
2fd20 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
2fd30 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69  sult_text16(sqli
2fd40 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
2fd50 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
2fd60 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
2fd70 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
2fd80 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71  sult_text16le(sq
2fd90 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2fda0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
2fdb0 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
2fdc0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
2fdd0 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73  esult_text16be(s
2fde0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2fdf0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
2fe00 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  t,void(*)(void*)
2fe10 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2fe20 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c  result_value(sql
2fe30 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73  ite3_context*, s
2fe40 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2fe50 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2fe60 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c  ult_zeroblob(sql
2fe70 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
2fe80 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt n);../*.** CA
2fe90 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e  PI3REF: Define N
2fea0 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71  ew Collating Seq
2feb0 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  uences.**.** ^Th
2fec0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 64  ese functions ad
2fed0 64 2c 20 72 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f  d, remove, or mo
2fee0 64 69 66 79 20 61 20 5b 63 6f 6c 6c 61 74 69 6f  dify a [collatio
2fef0 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a  n] associated.**
2ff00 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
2ff10 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2ff20 73 70 65 63 69 66 69 65 64 20 61 73 20 74 68 65  specified as the
2ff30 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
2ff40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  .**.** ^The name
2ff50 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f   of the collatio
2ff60 6e 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72  n is a UTF-8 str
2ff70 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74  ing.** for sqlit
2ff80 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2ff90 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ion() and sqlite
2ffa0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2ffb0 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61  on_v2().** and a
2ffc0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69   UTF-16 string i
2ffd0 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  n native byte or
2ffe0 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  der for sqlite3_
2fff0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
30000 31 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74  16()..** ^Collat
30010 69 6f 6e 20 6e 61 6d 65 73 20 74 68 61 74 20 63  ion names that c
30020 6f 6d 70 61 72 65 20 65 71 75 61 6c 20 61 63 63  ompare equal acc
30030 6f 72 64 69 6e 67 20 74 6f 20 5b 73 71 6c 69 74  ording to [sqlit
30040 65 33 5f 73 74 72 6e 69 63 6d 70 28 29 5d 20 61  e3_strnicmp()] a
30050 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64  re.** considered
30060 20 74 6f 20 62 65 20 74 68 65 20 73 61 6d 65 20   to be the same 
30070 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  name..**.** ^(Th
30080 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
30090 20 28 65 54 65 78 74 52 65 70 29 20 6d 75 73 74   (eTextRep) must
300a0 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63   be one of the c
300b0 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c  onstants:.** <ul
300c0 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
300d0 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e  E_UTF8],.** <li>
300e0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
300f0 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
30100 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20  TE_UTF16BE],.** 
30110 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46  <li> [SQLITE_UTF
30120 31 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  16], or.** <li> 
30130 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c  [SQLITE_UTF16_AL
30140 49 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e  IGNED]..** </ul>
30150 29 5e 0a 2a 2a 20 5e 54 68 65 20 65 54 65 78 74  )^.** ^The eText
30160 52 65 70 20 61 72 67 75 6d 65 6e 74 20 64 65 74  Rep argument det
30170 65 72 6d 69 6e 65 73 20 74 68 65 20 65 6e 63 6f  ermines the enco
30180 64 69 6e 67 20 6f 66 20 73 74 72 69 6e 67 73 20  ding of strings 
30190 70 61 73 73 65 64 0a 2a 2a 20 74 6f 20 74 68 65  passed.** to the
301a0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
301b0 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c 20 78 43  ion callback, xC
301c0 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65  allback..** ^The
301d0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20   [SQLITE_UTF16] 
301e0 61 6e 64 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  and [SQLITE_UTF1
301f0 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65  6_ALIGNED] value
30200 73 20 66 6f 72 20 65 54 65 78 74 52 65 70 0a 2a  s for eTextRep.*
30210 2a 20 66 6f 72 63 65 20 73 74 72 69 6e 67 73 20  * force strings 
30220 74 6f 20 62 65 20 55 54 46 31 36 20 77 69 74 68  to be UTF16 with
30230 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
30240 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  er..** ^The [SQL
30250 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45  ITE_UTF16_ALIGNE
30260 44 5d 20 76 61 6c 75 65 20 66 6f 72 20 65 54 65  D] value for eTe
30270 78 74 52 65 70 20 66 6f 72 63 65 73 20 73 74 72  xtRep forces str
30280 69 6e 67 73 20 74 6f 20 62 65 67 69 6e 0a 2a 2a  ings to begin.**
30290 20 6f 6e 20 61 6e 20 65 76 65 6e 20 62 79 74 65   on an even byte
302a0 20 61 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20   address..**.** 
302b0 5e 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 75  ^The fourth argu
302c0 6d 65 6e 74 2c 20 70 41 72 67 2c 20 69 73 20 61  ment, pArg, is a
302d0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  n application da
302e0 74 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20  ta pointer that 
302f0 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 68 72  is passed.** thr
30300 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73  ough as the firs
30310 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
30320 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
30330 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  tion callback..*
30340 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20  *.** ^The fifth 
30350 61 72 67 75 6d 65 6e 74 2c 20 78 43 61 6c 6c 62  argument, xCallb
30360 61 63 6b 2c 20 69 73 20 61 20 70 6f 69 6e 74 65  ack, is a pointe
30370 72 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69  r to the collati
30380 6e 67 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20  ng function..** 
30390 5e 4d 75 6c 74 69 70 6c 65 20 63 6f 6c 6c 61 74  ^Multiple collat
303a0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 63 61  ing functions ca
303b0 6e 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20  n be registered 
303c0 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e  using the same n
303d0 61 6d 65 20 62 75 74 0a 2a 2a 20 77 69 74 68 20  ame but.** with 
303e0 64 69 66 66 65 72 65 6e 74 20 65 54 65 78 74 52  different eTextR
303f0 65 70 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e  ep parameters an
30400 64 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73  d SQLite will us
30410 65 20 77 68 69 63 68 65 76 65 72 0a 2a 2a 20 66  e whichever.** f
30420 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73  unction requires
30430 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e   the least amoun
30440 74 20 6f 66 20 64 61 74 61 20 74 72 61 6e 73 66  t of data transf
30450 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66  ormation..** ^If
30460 20 74 68 65 20 78 43 61 6c 6c 62 61 63 6b 20 61   the xCallback a
30470 72 67 75 6d 65 6e 74 20 69 73 20 4e 55 4c 4c 20  rgument is NULL 
30480 74 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69  then the collati
30490 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a  ng function is.*
304a0 2a 20 64 65 6c 65 74 65 64 2e 20 20 5e 57 68 65  * deleted.  ^Whe
304b0 6e 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67 20  n all collating 
304c0 66 75 6e 63 74 69 6f 6e 73 20 68 61 76 69 6e 67  functions having
304d0 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 61   the same name a
304e0 72 65 20 64 65 6c 65 74 65 64 2c 0a 2a 2a 20 74  re deleted,.** t
304f0 68 61 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73  hat collation is
30500 20 6e 6f 20 6c 6f 6e 67 65 72 20 75 73 61 62 6c   no longer usabl
30510 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f  e..**.** ^The co
30520 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
30530 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
30540 6f 6b 65 64 20 77 69 74 68 20 61 20 63 6f 70 79  oked with a copy
30550 20 6f 66 20 74 68 65 20 70 41 72 67 20 0a 2a 2a   of the pArg .**
30560 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
30570 61 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 77 69  a pointer and wi
30580 74 68 20 74 77 6f 20 73 74 72 69 6e 67 73 20 69  th two strings i
30590 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73  n the encoding s
305a0 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74  pecified.** by t
305b0 68 65 20 65 54 65 78 74 52 65 70 20 61 72 67 75  he eTextRep argu
305c0 6d 65 6e 74 2e 20 20 54 68 65 20 63 6f 6c 6c 61  ment.  The colla
305d0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75  ting function mu
305e0 73 74 20 72 65 74 75 72 6e 20 61 6e 0a 2a 2a 20  st return an.** 
305f0 69 6e 74 65 67 65 72 20 74 68 61 74 20 69 73 20  integer that is 
30600 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 2c 20  negative, zero, 
30610 6f 72 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20 69  or positive.** i
30620 66 20 74 68 65 20 66 69 72 73 74 20 73 74 72 69  f the first stri
30630 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c  ng is less than,
30640 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72   equal to, or gr
30650 65 61 74 65 72 20 74 68 61 6e 20 74 68 65 20 73  eater than the s
30660 65 63 6f 6e 64 2c 0a 2a 2a 20 72 65 73 70 65 63  econd,.** respec
30670 74 69 76 65 6c 79 2e 20 20 41 20 63 6f 6c 6c 61  tively.  A colla
30680 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75  ting function mu
30690 73 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  st always return
306a0 20 74 68 65 20 73 61 6d 65 20 61 6e 73 77 65 72   the same answer
306b0 0a 2a 2a 20 67 69 76 65 6e 20 74 68 65 20 73 61  .** given the sa
306c0 6d 65 20 69 6e 70 75 74 73 2e 20 20 49 66 20 74  me inputs.  If t
306d0 77 6f 20 6f 72 20 6d 6f 72 65 20 63 6f 6c 6c 61  wo or more colla
306e0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61  ting functions a
306f0 72 65 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a  re registered.**
30700 20 74 6f 20 74 68 65 20 73 61 6d 65 20 63 6f 6c   to the same col
30710 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 28 75 73 69  lation name (usi
30720 6e 67 20 64 69 66 66 65 72 65 6e 74 20 65 54 65  ng different eTe
30730 78 74 52 65 70 20 76 61 6c 75 65 73 29 20 74 68  xtRep values) th
30740 65 6e 20 61 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67  en all.** must g
30750 69 76 65 20 61 6e 20 65 71 75 69 76 61 6c 65 6e  ive an equivalen
30760 74 20 61 6e 73 77 65 72 20 77 68 65 6e 20 69 6e  t answer when in
30770 76 6f 6b 65 64 20 77 69 74 68 20 65 71 75 69 76  voked with equiv
30780 61 6c 65 6e 74 20 73 74 72 69 6e 67 73 2e 0a 2a  alent strings..*
30790 2a 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  * The collating 
307a0 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6f 62  function must ob
307b0 65 79 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ey the following
307c0 20 70 72 6f 70 65 72 74 69 65 73 20 66 6f 72 20   properties for 
307d0 61 6c 6c 0a 2a 2a 20 73 74 72 69 6e 67 73 20 41  all.** strings A
307e0 2c 20 42 2c 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a  , B, and C:.**.*
307f0 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49  * <ol>.** <li> I
30800 66 20 41 3d 3d 42 20 74 68 65 6e 20 42 3d 3d 41  f A==B then B==A
30810 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d  ..** <li> If A==
30820 42 20 61 6e 64 20 42 3d 3d 43 20 74 68 65 6e 20  B and B==C then 
30830 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66  A==C..** <li> If
30840 20 41 26 6c 74 3b 42 20 54 48 45 4e 20 42 26 67   A&lt;B THEN B&g
30850 74 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20  t;A..** <li> If 
30860 41 26 6c 74 3b 42 20 61 6e 64 20 42 26 6c 74 3b  A&lt;B and B&lt;
30870 43 20 74 68 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a  C then A&lt;C..*
30880 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66  * </ol>.**.** If
30890 20 61 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e   a collating fun
308a0 63 74 69 6f 6e 20 66 61 69 6c 73 20 61 6e 79 20  ction fails any 
308b0 6f 66 20 74 68 65 20 61 62 6f 76 65 20 63 6f 6e  of the above con
308c0 73 74 72 61 69 6e 74 73 20 61 6e 64 20 74 68 61  straints and tha
308d0 74 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6e 67 20 66  t.** collating f
308e0 75 6e 63 74 69 6f 6e 20 69 73 20 20 72 65 67 69  unction is  regi
308f0 73 74 65 72 65 64 20 61 6e 64 20 75 73 65 64 2c  stered and used,
30900 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
30910 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  or of SQLite.** 
30920 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
30930 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
30940 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
30950 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b  n_v2() works lik
30960 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
30970 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20  _collation().** 
30980 77 69 74 68 20 74 68 65 20 61 64 64 69 74 69 6f  with the additio
30990 6e 20 74 68 61 74 20 74 68 65 20 78 44 65 73 74  n that the xDest
309a0 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  roy callback is 
309b0 69 6e 76 6f 6b 65 64 20 6f 6e 20 70 41 72 67 20  invoked on pArg 
309c0 77 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c  when.** the coll
309d0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69  ating function i
309e0 73 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43  s deleted..** ^C
309f0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
30a00 6e 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 77  ns are deleted w
30a10 68 65 6e 20 74 68 65 79 20 61 72 65 20 6f 76 65  hen they are ove
30a20 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72  rridden by later
30a30 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  .** calls to the
30a40 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74   collation creat
30a50 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  ion functions or
30a60 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 64 61   when the.** [da
30a70 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
30a80 6e 5d 20 69 73 20 63 6c 6f 73 65 64 20 75 73 69  n] is closed usi
30a90 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  ng [sqlite3_clos
30aa0 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  e()]..**.** ^The
30ab0 20 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61   xDestroy callba
30ac0 63 6b 20 69 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e  ck is <u>not</u>
30ad0 20 63 61 6c 6c 65 64 20 69 66 20 74 68 65 20 0a   called if the .
30ae0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ** sqlite3_creat
30af0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
30b00 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 2e   function fails.
30b10 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74    Applications t
30b20 68 61 74 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71  hat invoke.** sq
30b30 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
30b40 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 69 74 68  lation_v2() with
30b50 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73   a non-NULL xDes
30b60 74 72 6f 79 20 61 72 67 75 6d 65 6e 74 20 73 68  troy argument sh
30b70 6f 75 6c 64 20 0a 2a 2a 20 63 68 65 63 6b 20 74  ould .** check t
30b80 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 61  he return code a
30b90 6e 64 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  nd dispose of th
30ba0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  e application da
30bb0 74 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68  ta pointer.** th
30bc0 65 6d 73 65 6c 76 65 73 20 72 61 74 68 65 72 20  emselves rather 
30bd0 74 68 61 6e 20 65 78 70 65 63 74 69 6e 67 20 53  than expecting S
30be0 51 4c 69 74 65 20 74 6f 20 64 65 61 6c 20 77 69  QLite to deal wi
30bf0 74 68 20 69 74 20 66 6f 72 20 74 68 65 6d 2e 0a  th it for them..
30c00 2a 2a 20 54 68 69 73 20 69 73 20 64 69 66 66 65  ** This is diffe
30c10 72 65 6e 74 20 66 72 6f 6d 20 65 76 65 72 79 20  rent from every 
30c20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
30c30 65 72 66 61 63 65 2e 20 20 54 68 65 20 69 6e 63  erface.  The inc
30c40 6f 6e 73 69 73 74 65 6e 63 79 20 0a 2a 2a 20 69  onsistency .** i
30c50 73 20 75 6e 66 6f 72 74 75 6e 61 74 65 20 62 75  s unfortunate bu
30c60 74 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e  t cannot be chan
30c70 67 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61  ged without brea
30c80 6b 69 6e 67 20 62 61 63 6b 77 61 72 64 73 20 0a  king backwards .
30c90 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ** compatibility
30ca0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
30cb0 3a 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  :  [sqlite3_coll
30cc0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20  ation_needed()] 
30cd0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  and [sqlite3_col
30ce0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
30cf0 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
30d00 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
30d10 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  ion(.  sqlite3*,
30d20 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a   .  const char *
30d30 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54  zName, .  int eT
30d40 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20  extRep, .  void 
30d50 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43  *pArg,.  int(*xC
30d60 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e  ompare)(void*,in
30d70 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e  t,const void*,in
30d80 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29  t,const void*).)
30d90 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
30da0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
30db0 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  2(.  sqlite3*, .
30dc0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
30dd0 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78  ame, .  int eTex
30de0 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70  tRep, .  void *p
30df0 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d  Arg,.  int(*xCom
30e00 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  pare)(void*,int,
30e10 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c  const void*,int,
30e20 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20  const void*),.  
30e30 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28  void(*xDestroy)(
30e40 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  void*).);.int sq
30e50 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
30e60 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69  lation16(.  sqli
30e70 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76  te3*, .  const v
30e80 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e  oid *zName,.  in
30e90 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76  t eTextRep, .  v
30ea0 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74  oid *pArg,.  int
30eb0 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64  (*xCompare)(void
30ec0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
30ed0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
30ee0 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *).);../*.** CAP
30ef0 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e  I3REF: Collation
30f00 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b   Needed Callback
30f10 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69  s.**.** ^To avoi
30f20 64 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69  d having to regi
30f30 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69  ster all collati
30f40 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65 66  on sequences bef
30f50 6f 72 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a  ore a database.*
30f60 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61  * can be used, a
30f70 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b   single callback
30f80 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65   function may be
30f90 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68   registered with
30fa0 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73   the.** [databas
30fb0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f  e connection] to
30fc0 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
30fd0 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65  ever an undefine
30fe0 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73  d collation.** s
30ff0 65 71 75 65 6e 63 65 20 69 73 20 72 65 71 75 69  equence is requi
31000 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  red..**.** ^If t
31010 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  he function is r
31020 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20  egistered using 
31030 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  the sqlite3_coll
31040 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41  ation_needed() A
31050 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69  PI,.** then it i
31060 73 20 70 61 73 73 65 64 20 74 68 65 20 6e 61 6d  s passed the nam
31070 65 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 20  es of undefined 
31080 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
31090 63 65 73 20 61 73 20 73 74 72 69 6e 67 73 0a 2a  ces as strings.*
310a0 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46  * encoded in UTF
310b0 2d 38 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  -8. ^If sqlite3_
310c0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
310d0 31 36 28 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a  16() is used,.**
310e0 20 74 68 65 20 6e 61 6d 65 73 20 61 72 65 20 70   the names are p
310f0 61 73 73 65 64 20 61 73 20 55 54 46 2d 31 36 20  assed as UTF-16 
31100 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76  in machine nativ
31110 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a  e byte order..**
31120 20 5e 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68   ^A call to eith
31130 65 72 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c  er function repl
31140 61 63 65 73 20 74 68 65 20 65 78 69 73 74 69 6e  aces the existin
31150 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64  g collation-need
31160 65 64 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  ed callback..**.
31170 2a 2a 20 5e 28 57 68 65 6e 20 74 68 65 20 63 61  ** ^(When the ca
31180 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
31190 64 2c 20 74 68 65 20 66 69 72 73 74 20 61 72 67  d, the first arg
311a0 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73 20  ument passed is 
311b0 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65  a copy.** of the
311c0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
311d0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c   to sqlite3_coll
311e0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f  ation_needed() o
311f0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
31200 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
31210 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61  ).  The second a
31220 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 64  rgument is the d
31230 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
31240 63 74 69 6f 6e 2e 20 20 54 68 65 20 74 68 69 72  ction.  The thir
31250 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e  d argument is on
31260 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46  e of [SQLITE_UTF
31270 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  8], [SQLITE_UTF1
31280 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  6BE],.** or [SQL
31290 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e  ITE_UTF16LE], in
312a0 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73  dicating the mos
312b0 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d  t desirable form
312c0 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f   of the collatio
312d0 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66 75  n.** sequence fu
312e0 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e  nction required.
312f0 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72    The fourth par
31300 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61  ameter is the na
31310 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71  me of the.** req
31320 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  uired collation 
31330 73 65 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a  sequence.)^.**.*
31340 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66  * The callback f
31350 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72  unction should r
31360 65 67 69 73 74 65 72 20 74 68 65 20 64 65 73 69  egister the desi
31370 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73  red collation us
31380 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
31390 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
313a0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72  ()], [sqlite3_cr
313b0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
313c0 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
313d0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
313e0 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69  tion_v2()]..*/.i
313f0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  nt sqlite3_colla
31400 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73  tion_needed(.  s
31410 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64  qlite3*, .  void
31420 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f  *, .  void(*)(vo
31430 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74  id*,sqlite3*,int
31440 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20   eTextRep,const 
31450 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  char*).);.int sq
31460 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
31470 6e 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69  needed16(.  sqli
31480 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a  te3*, .  void*,.
31490 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c    void(*)(void*,
314a0 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65  sqlite3*,int eTe
314b0 78 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64  xtRep,const void
314c0 2a 29 0a 29 3b 0a 0a 23 69 66 64 65 66 20 53 51  *).);..#ifdef SQ
314d0 4c 49 54 45 5f 48 41 53 5f 43 4f 44 45 43 0a 2f  LITE_HAS_CODEC./
314e0 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65  *.** Specify the
314f0 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72   key for an encr
31500 79 70 74 65 64 20 64 61 74 61 62 61 73 65 2e 20  ypted database. 
31510 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68   This routine sh
31520 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65  ould be.** calle
31530 64 20 72 69 67 68 74 20 61 66 74 65 72 20 73 71  d right after sq
31540 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a  lite3_open()..**
31550 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20  .** The code to 
31560 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41  implement this A
31570 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61  PI is not availa
31580 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69  ble in the publi
31590 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20  c release.** of 
315a0 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73  SQLite..*/.int s
315b0 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71  qlite3_key(.  sq
315c0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
315d0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
315e0 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  Database to be r
315f0 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73  ekeyed */.  cons
31600 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e  t void *pKey, in
31610 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68  t nKey     /* Th
31620 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  e key */.);../*.
31630 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65  ** Change the ke
31640 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74  y on an open dat
31650 61 62 61 73 65 2e 20 20 49 66 20 74 68 65 20 63  abase.  If the c
31660 75 72 72 65 6e 74 20 64 61 74 61 62 61 73 65 20  urrent database 
31670 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70  is not.** encryp
31680 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e  ted, this routin
31690 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69  e will encrypt i
316a0 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f  t.  If pNew==0 o
316b0 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a  r nNew==0, the.*
316c0 2a 20 64 61 74 61 62 61 73 65 20 69 73 20 64 65  * database is de
316d0 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  crypted..**.** T
316e0 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65  he code to imple
316f0 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73  ment this API is
31700 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69   not available i
31710 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c  n the public rel
31720 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ease.** of SQLit
31730 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
31740 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74  3_rekey(.  sqlit
31750 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
31760 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
31770 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65  abase to be reke
31780 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  yed */.  const v
31790 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e  oid *pKey, int n
317a0 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e  Key     /* The n
317b0 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a  ew key */.);../*
317c0 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20  .** Specify the 
317d0 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66  activation key f
317e0 6f 72 20 61 20 53 45 45 20 64 61 74 61 62 61 73  or a SEE databas
317f0 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61  e.  Unless .** a
31800 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f  ctivated, none o
31810 66 20 74 68 65 20 53 45 45 20 72 6f 75 74 69 6e  f the SEE routin
31820 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f  es will work..*/
31830 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 63  .void sqlite3_ac
31840 74 69 76 61 74 65 5f 73 65 65 28 0a 20 20 63 6f  tivate_see(.  co
31850 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50  nst char *zPassP
31860 68 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20  hrase        /* 
31870 41 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73  Activation phras
31880 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a  e */.);.#endif..
31890 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 45 4e  #ifdef SQLITE_EN
318a0 41 42 4c 45 5f 43 45 52 4f 44 0a 2f 2a 0a 2a 2a  ABLE_CEROD./*.**
318b0 20 53 70 65 63 69 66 79 20 74 68 65 20 61 63 74   Specify the act
318c0 69 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20  ivation key for 
318d0 61 20 43 45 52 4f 44 20 64 61 74 61 62 61 73 65  a CEROD database
318e0 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63  .  Unless .** ac
318f0 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66  tivated, none of
31900 20 74 68 65 20 43 45 52 4f 44 20 72 6f 75 74 69   the CEROD routi
31910 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a  nes will work..*
31920 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61  /.void sqlite3_a
31930 63 74 69 76 61 74 65 5f 63 65 72 6f 64 28 0a 20  ctivate_cerod(. 
31940 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61   const char *zPa
31950 73 73 50 68 72 61 73 65 20 20 20 20 20 20 20 20  ssPhrase        
31960 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68  /* Activation ph
31970 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69  rase */.);.#endi
31980 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
31990 46 3a 20 53 75 73 70 65 6e 64 20 45 78 65 63 75  F: Suspend Execu
319a0 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74  tion For A Short
319b0 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20   Time.**.** The 
319c0 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20  sqlite3_sleep() 
319d0 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20  function causes 
319e0 74 68 65 20 63 75 72 72 65 6e 74 20 74 68 72 65  the current thre
319f0 61 64 20 74 6f 20 73 75 73 70 65 6e 64 20 65 78  ad to suspend ex
31a00 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61  ecution.** for a
31a10 74 20 6c 65 61 73 74 20 61 20 6e 75 6d 62 65 72  t least a number
31a20 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   of milliseconds
31a30 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 69 74   specified in it
31a40 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  s parameter..**.
31a50 2a 2a 20 49 66 20 74 68 65 20 6f 70 65 72 61 74  ** If the operat
31a60 69 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 73 20  ing system does 
31a70 6e 6f 74 20 73 75 70 70 6f 72 74 20 73 6c 65 65  not support slee
31a80 70 20 72 65 71 75 65 73 74 73 20 77 69 74 68 0a  p requests with.
31a90 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74  ** millisecond t
31aa0 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20  ime resolution, 
31ab0 74 68 65 6e 20 74 68 65 20 74 69 6d 65 20 77 69  then the time wi
31ac0 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 75 70  ll be rounded up
31ad0 20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65   to.** the neare
31ae0 73 74 20 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e  st second. The n
31af0 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65  umber of millise
31b00 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61  conds of sleep a
31b10 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65  ctually.** reque
31b20 73 74 65 64 20 66 72 6f 6d 20 74 68 65 20 6f 70  sted from the op
31b30 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69  erating system i
31b40 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
31b50 2a 20 5e 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d  * ^SQLite implem
31b60 65 6e 74 73 20 74 68 69 73 20 69 6e 74 65 72 66  ents this interf
31b70 61 63 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74  ace by calling t
31b80 68 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d  he xSleep().** m
31b90 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66  ethod of the def
31ba0 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
31bb0 73 5d 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 74  s] object.  If t
31bc0 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68  he xSleep() meth
31bd0 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 64 65 66  od.** of the def
31be0 61 75 6c 74 20 56 46 53 20 69 73 20 6e 6f 74 20  ault VFS is not 
31bf0 69 6d 70 6c 65 6d 65 6e 74 65 64 20 63 6f 72 72  implemented corr
31c00 65 63 74 6c 79 2c 20 6f 72 20 6e 6f 74 20 69 6d  ectly, or not im
31c10 70 6c 65 6d 65 6e 74 65 64 20 61 74 0a 2a 2a 20  plemented at.** 
31c20 61 6c 6c 2c 20 74 68 65 6e 20 74 68 65 20 62 65  all, then the be
31c30 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65  havior of sqlite
31c40 33 5f 73 6c 65 65 70 28 29 20 6d 61 79 20 64 65  3_sleep() may de
31c50 76 69 61 74 65 20 66 72 6f 6d 20 74 68 65 20 64  viate from the d
31c60 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 20 69 6e  escription.** in
31c70 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61   the previous pa
31c80 72 61 67 72 61 70 68 73 2e 0a 2a 2f 0a 69 6e 74  ragraphs..*/.int
31c90 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 69   sqlite3_sleep(i
31ca0 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
31cb0 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68  3REF: Name Of Th
31cc0 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67  e Folder Holding
31cd0 20 54 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 73   Temporary Files
31ce0 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73  .**.** ^(If this
31cf0 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65   global variable
31d00 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   is made to poin
31d10 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68  t to a string wh
31d20 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61  ich is.** the na
31d30 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28  me of a folder (
31d40 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72 79  a.k.a. directory
31d50 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70  ), then all temp
31d60 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63  orary files.** c
31d70 72 65 61 74 65 64 20 62 79 20 53 51 4c 69 74 65  reated by SQLite
31d80 20 77 68 65 6e 20 75 73 69 6e 67 20 61 20 62 75   when using a bu
31d90 69 6c 74 2d 69 6e 20 5b 73 71 6c 69 74 65 33 5f  ilt-in [sqlite3_
31da0 76 66 73 20 7c 20 56 46 53 5d 0a 2a 2a 20 77 69  vfs | VFS].** wi
31db0 6c 6c 20 62 65 20 70 6c 61 63 65 64 20 69 6e 20  ll be placed in 
31dc0 74 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e 29  that directory.)
31dd0 5e 20 20 5e 49 66 20 74 68 69 73 20 76 61 72 69  ^  ^If this vari
31de0 61 62 6c 65 0a 2a 2a 20 69 73 20 61 20 4e 55 4c  able.** is a NUL
31df0 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
31e00 53 51 4c 69 74 65 20 70 65 72 66 6f 72 6d 73 20  SQLite performs 
31e10 61 20 73 65 61 72 63 68 20 66 6f 72 20 61 6e 20  a search for an 
31e20 61 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 74  appropriate.** t
31e30 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 20 64 69  emporary file di
31e40 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49  rectory..**.** I
31e50 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
31e60 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20   read or modify 
31e70 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 6e  this variable in
31e80 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a   more than one.*
31e90 2a 20 74 68 72 65 61 64 20 61 74 20 61 20 74 69  * thread at a ti
31ea0 6d 65 2e 20 20 49 74 20 69 73 20 6e 6f 74 20 73  me.  It is not s
31eb0 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d  afe to read or m
31ec0 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61  odify this varia
31ed0 62 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74  ble.** if a [dat
31ee0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
31ef0 5d 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20  ] is being used 
31f00 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
31f10 20 69 6e 20 61 20 73 65 70 61 72 61 74 65 0a 2a   in a separate.*
31f20 2a 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20  * thread..** It 
31f30 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74  is intended that
31f40 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 62   this variable b
31f50 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73  e set once.** as
31f60 20 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73   part of process
31f70 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
31f80 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53  and before any S
31f90 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a  QLite interface.
31fa0 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65  ** routines have
31fb0 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64   been called and
31fc0 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61   that this varia
31fd0 62 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63 68 61  ble remain uncha
31fe0 6e 67 65 64 0a 2a 2a 20 74 68 65 72 65 61 66 74  nged.** thereaft
31ff0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  er..**.** ^The [
32000 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
32010 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d 61 79  tory pragma] may
32020 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72   modify this var
32030 69 61 62 6c 65 20 61 6e 64 20 63 61 75 73 65 0a  iable and cause.
32040 2a 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 20 74  ** it to point t
32050 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
32060 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
32070 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 68  malloc].  ^Furth
32080 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b  ermore,.** the [
32090 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
320a0 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 6c 77  tory pragma] alw
320b0 61 79 73 20 61 73 73 75 6d 65 73 20 74 68 61 74  ays assumes that
320c0 20 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74   any string.** t
320d0 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c  hat this variabl
320e0 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 68  e points to is h
320f0 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62  eld in memory ob
32100 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20  tained from .** 
32110 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d  [sqlite3_malloc]
32120 20 61 6e 64 20 74 68 65 20 70 72 61 67 6d 61 20   and the pragma 
32130 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 66  may attempt to f
32140 72 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a  ree that memory.
32150 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ** using [sqlite
32160 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63  3_free]..** Henc
32170 65 2c 20 69 66 20 74 68 69 73 20 76 61 72 69 61  e, if this varia
32180 62 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20  ble is modified 
32190 64 69 72 65 63 74 6c 79 2c 20 65 69 74 68 65 72  directly, either
321a0 20 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a   it should be.**
321b0 20 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61   made NULL or ma
321c0 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d  de to point to m
321d0 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
321e0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
321f0 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20  loc].** or else 
32200 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b  the use of the [
32210 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
32220 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 68 6f  tory pragma] sho
32230 75 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a  uld be avoided..
32240 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e  */.SQLITE_EXTERN
32250 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 74   char *sqlite3_t
32260 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a  emp_directory;..
32270 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
32280 54 65 73 74 20 46 6f 72 20 41 75 74 6f 2d 43 6f  Test For Auto-Co
32290 6d 6d 69 74 20 4d 6f 64 65 0a 2a 2a 20 4b 45 59  mmit Mode.** KEY
322a0 57 4f 52 44 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d  WORDS: {autocomm
322b0 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 5e  it mode}.**.** ^
322c0 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
322d0 61 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e 74  autocommit() int
322e0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 6e  erface returns n
322f0 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65  on-zero or.** ze
32300 72 6f 20 69 66 20 74 68 65 20 67 69 76 65 6e 20  ro if the given 
32310 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
32320 69 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f 74  ion is or is not
32330 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d   in autocommit m
32340 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69  ode,.** respecti
32350 76 65 6c 79 2e 20 20 5e 41 75 74 6f 63 6f 6d 6d  vely.  ^Autocomm
32360 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79  it mode is on by
32370 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 5e 41 75   default..** ^Au
32380 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73  tocommit mode is
32390 20 64 69 73 61 62 6c 65 64 20 62 79 20 61 20 5b   disabled by a [
323a0 42 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74  BEGIN] statement
323b0 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74  ..** ^Autocommit
323c0 20 6d 6f 64 65 20 69 73 20 72 65 2d 65 6e 61 62   mode is re-enab
323d0 6c 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49 54  led by a [COMMIT
323e0 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e  ] or [ROLLBACK].
323f0 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61 69  .**.** If certai
32400 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f 72  n kinds of error
32410 73 20 6f 63 63 75 72 20 6f 6e 20 61 20 73 74 61  s occur on a sta
32420 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20  tement within a 
32430 6d 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74 0a  multi-statement.
32440 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 28  ** transaction (
32450 65 72 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e 67  errors including
32460 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20   [SQLITE_FULL], 
32470 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c 0a  [SQLITE_IOERR],.
32480 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ** [SQLITE_NOMEM
32490 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ], [SQLITE_BUSY]
324a0 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49 4e  , and [SQLITE_IN
324b0 54 45 52 52 55 50 54 5d 29 20 74 68 65 6e 20 74  TERRUPT]) then t
324c0 68 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f  he.** transactio
324d0 6e 20 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c 65  n might be rolle
324e0 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63  d back automatic
324f0 61 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79 20  ally.  The only 
32500 77 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f  way to.** find o
32510 75 74 20 77 68 65 74 68 65 72 20 53 51 4c 69 74  ut whether SQLit
32520 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
32530 72 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68 65 20  rolled back the 
32540 74 72 61 6e 73 61 63 74 69 6f 6e 20 61 66 74 65  transaction afte
32550 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69 73  r.** an error is
32560 20 74 6f 20 75 73 65 20 74 68 69 73 20 66 75 6e   to use this fun
32570 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ction..**.** If 
32580 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 63  another thread c
32590 68 61 6e 67 65 73 20 74 68 65 20 61 75 74 6f 63  hanges the autoc
325a0 6f 6d 6d 69 74 20 73 74 61 74 75 73 20 6f 66 20  ommit status of 
325b0 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
325c0 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65  connection while
325d0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
325e0 20 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74   running, then t
325f0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
32600 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  ** is undefined.
32610 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
32620 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73  get_autocommit(s
32630 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
32640 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20   CAPI3REF: Find 
32650 54 68 65 20 44 61 74 61 62 61 73 65 20 48 61 6e  The Database Han
32660 64 6c 65 20 4f 66 20 41 20 50 72 65 70 61 72 65  dle Of A Prepare
32670 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a  d Statement.**.*
32680 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
32690 62 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72 66 61  b_handle interfa
326a0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b  ce returns the [
326b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
326c0 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 74  ion] handle.** t
326d0 6f 20 77 68 69 63 68 20 61 20 5b 70 72 65 70 61  o which a [prepa
326e0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 62  red statement] b
326f0 65 6c 6f 6e 67 73 2e 20 20 5e 54 68 65 20 5b 64  elongs.  ^The [d
32700 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
32710 6f 6e 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  on].** returned 
32720 62 79 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  by sqlite3_db_ha
32730 6e 64 6c 65 20 69 73 20 74 68 65 20 73 61 6d 65  ndle is the same
32740 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
32750 63 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20 77  ction].** that w
32760 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
32770 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20  ument.** to the 
32780 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
32790 5f 76 32 28 29 5d 20 63 61 6c 6c 20 28 6f 72 20  _v2()] call (or 
327a0 69 74 73 20 76 61 72 69 61 6e 74 73 29 20 74 68  its variants) th
327b0 61 74 20 77 61 73 20 75 73 65 64 20 74 6f 0a 2a  at was used to.*
327c0 2a 20 63 72 65 61 74 65 20 74 68 65 20 73 74 61  * create the sta
327d0 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 66 69  tement in the fi
327e0 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2f 0a 73 71  rst place..*/.sq
327f0 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 64  lite3 *sqlite3_d
32800 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33  b_handle(sqlite3
32810 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
32820 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20 74  CAPI3REF: Find t
32830 68 65 20 6e 65 78 74 20 70 72 65 70 61 72 65 64  he next prepared
32840 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a   statement.**.**
32850 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65   ^This interface
32860 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
32870 65 72 20 74 6f 20 74 68 65 20 6e 65 78 74 20 5b  er to the next [
32880 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
32890 6e 74 5d 20 61 66 74 65 72 0a 2a 2a 20 70 53 74  nt] after.** pSt
328a0 6d 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  mt associated wi
328b0 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
328c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 44 62   connection] pDb
328d0 2e 20 20 5e 49 66 20 70 53 74 6d 74 20 69 73 20  .  ^If pStmt is 
328e0 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e 20 74 68 69  NULL.** then thi
328f0 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  s interface retu
32900 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
32910 20 74 68 65 20 66 69 72 73 74 20 70 72 65 70 61   the first prepa
32920 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  red statement.**
32930 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
32940 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
32950 6e 6e 65 63 74 69 6f 6e 20 70 44 62 2e 20 20 5e  nnection pDb.  ^
32960 49 66 20 6e 6f 20 70 72 65 70 61 72 65 64 20 73  If no prepared s
32970 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 73 61 74 69  tatement.** sati
32980 73 66 69 65 73 20 74 68 65 20 63 6f 6e 64 69 74  sfies the condit
32990 69 6f 6e 73 20 6f 66 20 74 68 69 73 20 72 6f 75  ions of this rou
329a0 74 69 6e 65 2c 20 69 74 20 72 65 74 75 72 6e 73  tine, it returns
329b0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   NULL..**.** The
329c0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
329d0 63 74 69 6f 6e 5d 20 70 6f 69 6e 74 65 72 20 44  ction] pointer D
329e0 20 69 6e 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a   in a call to.**
329f0 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   [sqlite3_next_s
32a00 74 6d 74 28 44 2c 53 29 5d 20 6d 75 73 74 20 72  tmt(D,S)] must r
32a10 65 66 65 72 20 74 6f 20 61 6e 20 6f 70 65 6e 20  efer to an open 
32a20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
32a30 65 63 74 69 6f 6e 20 61 6e 64 20 69 6e 20 70 61  ection and in pa
32a40 72 74 69 63 75 6c 61 72 20 6d 75 73 74 20 6e 6f  rticular must no
32a50 74 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t be a NULL poin
32a60 74 65 72 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  ter..*/.sqlite3_
32a70 73 74 6d 74 20 2a 73 71 6c 69 74 65 33 5f 6e 65  stmt *sqlite3_ne
32a80 78 74 5f 73 74 6d 74 28 73 71 6c 69 74 65 33 20  xt_stmt(sqlite3 
32a90 2a 70 44 62 2c 20 73 71 6c 69 74 65 33 5f 73 74  *pDb, sqlite3_st
32aa0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
32ab0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
32ac0 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62 61 63 6b  mit And Rollback
32ad0 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61   Notification Ca
32ae0 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54  llbacks.**.** ^T
32af0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  he sqlite3_commi
32b00 74 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61  t_hook() interfa
32b10 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ce registers a c
32b20 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74  allback.** funct
32b30 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  ion to be invoke
32b40 64 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 61  d whenever a tra
32b50 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b 43 4f 4d  nsaction is [COM
32b60 4d 49 54 20 7c 20 63 6f 6d 6d 69 74 74 65 64 5d  MIT | committed]
32b70 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61  ..** ^Any callba
32b80 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76  ck set by a prev
32b90 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ious call to sql
32ba0 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b  ite3_commit_hook
32bb0 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  ().** for the sa
32bc0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
32bd0 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69  ection is overri
32be0 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  dden..** ^The sq
32bf0 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68  lite3_rollback_h
32c00 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20  ook() interface 
32c10 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
32c20 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  back.** function
32c30 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
32c40 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61  henever a transa
32c50 63 74 69 6f 6e 20 69 73 20 5b 52 4f 4c 4c 42 41  ction is [ROLLBA
32c60 43 4b 20 7c 20 72 6f 6c 6c 65 64 20 62 61 63 6b  CK | rolled back
32c70 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62  ]..** ^Any callb
32c80 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65  ack set by a pre
32c90 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71  vious call to sq
32ca0 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68  lite3_rollback_h
32cb0 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65  ook().** for the
32cc0 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
32cd0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65  onnection is ove
32ce0 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65  rridden..** ^The
32cf0 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 69   pArg argument i
32d00 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68  s passed through
32d10 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
32d20 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c  ..** ^If the cal
32d30 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69  lback on a commi
32d40 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e 20  t hook function 
32d50 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
32d60 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f  ,.** then the co
32d70 6d 6d 69 74 20 69 73 20 63 6f 6e 76 65 72 74 65  mmit is converte
32d80 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63  d into a rollbac
32d90 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  k..**.** ^The sq
32da0 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
32db0 6b 28 44 2c 43 2c 50 29 20 61 6e 64 20 73 71 6c  k(D,C,P) and sql
32dc0 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f  ite3_rollback_ho
32dd0 6f 6b 28 44 2c 43 2c 50 29 20 66 75 6e 63 74 69  ok(D,C,P) functi
32de0 6f 6e 73 0a 2a 2a 20 72 65 74 75 72 6e 20 74 68  ons.** return th
32df0 65 20 50 20 61 72 67 75 6d 65 6e 74 20 66 72 6f  e P argument fro
32e00 6d 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63  m the previous c
32e10 61 6c 6c 20 6f 66 20 74 68 65 20 73 61 6d 65 20  all of the same 
32e20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6f 6e 20 74  function.** on t
32e30 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73  he same [databas
32e40 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c  e connection] D,
32e50 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20   or NULL for.** 
32e60 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 66  the first call f
32e70 6f 72 20 65 61 63 68 20 66 75 6e 63 74 69 6f 6e  or each function
32e80 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   on D..**.** The
32e90 20 63 61 6c 6c 62 61 63 6b 20 69 6d 70 6c 65 6d   callback implem
32ea0 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  entation must no
32eb0 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68  t do anything th
32ec0 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a  at will modify.*
32ed0 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
32ee0 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
32ef0 6e 76 6f 6b 65 64 20 74 68 65 20 63 61 6c 6c 62  nvoked the callb
32f00 61 63 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e  ack.  Any action
32f10 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74  s.** to modify t
32f20 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
32f30 65 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 64  ection must be d
32f40 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 66  eferred until af
32f50 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c  ter the.** compl
32f60 65 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71  etion of the [sq
32f70 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61  lite3_step()] ca
32f80 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65  ll that triggere
32f90 64 20 74 68 65 20 63 6f 6d 6d 69 74 0a 2a 2a 20  d the commit.** 
32fa0 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b  or rollback hook
32fb0 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c   in the first pl
32fc0 61 63 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ace..** Note tha
32fd0 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  t [sqlite3_prepa
32fe0 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
32ff0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f  lite3_step()] bo
33000 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a  th modify their.
33010 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
33020 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20  ections for the 
33030 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69  meaning of "modi
33040 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61  fy" in this para
33050 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65  graph..**.** ^Re
33060 67 69 73 74 65 72 69 6e 67 20 61 20 4e 55 4c 4c  gistering a NULL
33070 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c   function disabl
33080 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e  es the callback.
33090 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65  .**.** ^When the
330a0 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 63 61 6c   commit hook cal
330b0 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65  lback routine re
330c0 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20  turns zero, the 
330d0 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 70 65 72  [COMMIT].** oper
330e0 61 74 69 6f 6e 20 69 73 20 61 6c 6c 6f 77 65 64  ation is allowed
330f0 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 6e 6f 72   to continue nor
33100 6d 61 6c 6c 79 2e 20 20 5e 49 66 20 74 68 65 20  mally.  ^If the 
33110 63 6f 6d 6d 69 74 20 68 6f 6f 6b 0a 2a 2a 20 72  commit hook.** r
33120 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
33130 20 74 68 65 6e 20 74 68 65 20 5b 43 4f 4d 4d 49   then the [COMMI
33140 54 5d 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20  T] is converted 
33150 69 6e 74 6f 20 61 20 5b 52 4f 4c 4c 42 41 43 4b  into a [ROLLBACK
33160 5d 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c 62  ]..** ^The rollb
33170 61 63 6b 20 68 6f 6f 6b 20 69 73 20 69 6e 76 6f  ack hook is invo
33180 6b 65 64 20 6f 6e 20 61 20 72 6f 6c 6c 62 61 63  ked on a rollbac
33190 6b 20 74 68 61 74 20 72 65 73 75 6c 74 73 20 66  k that results f
331a0 72 6f 6d 20 61 20 63 6f 6d 6d 69 74 0a 2a 2a 20  rom a commit.** 
331b0 68 6f 6f 6b 20 72 65 74 75 72 6e 69 6e 67 20 6e  hook returning n
331c0 6f 6e 2d 7a 65 72 6f 2c 20 6a 75 73 74 20 61 73  on-zero, just as
331d0 20 69 74 20 77 6f 75 6c 64 20 62 65 20 77 69 74   it would be wit
331e0 68 20 61 6e 79 20 6f 74 68 65 72 20 72 6f 6c 6c  h any other roll
331f0 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72  back..**.** ^For
33200 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66   the purposes of
33210 20 74 68 69 73 20 41 50 49 2c 20 61 20 74 72 61   this API, a tra
33220 6e 73 61 63 74 69 6f 6e 20 69 73 20 73 61 69 64  nsaction is said
33230 20 74 6f 20 68 61 76 65 20 62 65 65 6e 0a 2a 2a   to have been.**
33240 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 69 66 20   rolled back if 
33250 61 6e 20 65 78 70 6c 69 63 69 74 20 22 52 4f 4c  an explicit "ROL
33260 4c 42 41 43 4b 22 20 73 74 61 74 65 6d 65 6e 74  LBACK" statement
33270 20 69 73 20 65 78 65 63 75 74 65 64 2c 20 6f 72   is executed, or
33280 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 6f 72 20  .** an error or 
33290 63 6f 6e 73 74 72 61 69 6e 74 20 63 61 75 73 65  constraint cause
332a0 73 20 61 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f  s an implicit ro
332b0 6c 6c 62 61 63 6b 20 74 6f 20 6f 63 63 75 72 2e  llback to occur.
332c0 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c 62 61 63  .** ^The rollbac
332d0 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f  k callback is no
332e0 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 74  t invoked if a t
332f0 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a  ransaction is.**
33300 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
33310 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65 63 61 75  olled back becau
33320 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
33330 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c  connection is cl
33340 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  osed..**.** See 
33350 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  also the [sqlite
33360 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 5d  3_update_hook()]
33370 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 76   interface..*/.v
33380 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  oid *sqlite3_com
33390 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33  mit_hook(sqlite3
333a0 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29  *, int(*)(void*)
333b0 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a  , void*);.void *
333c0 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b  sqlite3_rollback
333d0 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20  _hook(sqlite3*, 
333e0 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 29 2c  void(*)(void *),
333f0 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
33400 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 20 43  CAPI3REF: Data C
33410 68 61 6e 67 65 20 4e 6f 74 69 66 69 63 61 74 69  hange Notificati
33420 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a  on Callbacks.**.
33430 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
33440 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 20 69 6e  update_hook() in
33450 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
33460 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
33470 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68  ction.** with th
33480 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
33490 65 63 74 69 6f 6e 5d 20 69 64 65 6e 74 69 66 69  ection] identifi
334a0 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
334b0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 62  argument.** to b
334c0 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  e invoked whenev
334d0 65 72 20 61 20 72 6f 77 20 69 73 20 75 70 64 61  er a row is upda
334e0 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72  ted, inserted or
334f0 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 41 6e   deleted..** ^An
33500 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62  y callback set b
33510 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c  y a previous cal
33520 6c 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69  l to this functi
33530 6f 6e 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  on.** for the sa
33540 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
33550 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69  ection is overri
33560 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  dden..**.** ^The
33570 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
33580 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
33590 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 74 6f   the function to
335a0 20 69 6e 76 6f 6b 65 20 77 68 65 6e 20 61 0a 2a   invoke when a.*
335b0 2a 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 64  * row is updated
335c0 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65  , inserted or de
335d0 6c 65 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 66  leted..** ^The f
335e0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
335f0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
33600 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74   a copy of the t
33610 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  hird argument.**
33620 20 74 6f 20 73 71 6c 69 74 65 33 5f 75 70 64 61   to sqlite3_upda
33630 74 65 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 5e 54  te_hook()..** ^T
33640 68 65 20 73 65 63 6f 6e 64 20 63 61 6c 6c 62 61  he second callba
33650 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f  ck argument is o
33660 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e  ne of [SQLITE_IN
33670 53 45 52 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44  SERT], [SQLITE_D
33680 45 4c 45 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53  ELETE],.** or [S
33690 51 4c 49 54 45 5f 55 50 44 41 54 45 5d 2c 20 64  QLITE_UPDATE], d
336a0 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
336b0 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 63  operation that c
336c0 61 75 73 65 64 20 74 68 65 20 63 61 6c 6c 62 61  aused the callba
336d0 63 6b 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f  ck.** to be invo
336e0 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 74 68 69  ked..** ^The thi
336f0 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 61 72  rd and fourth ar
33700 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 63  guments to the c
33710 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20  allback contain 
33720 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 0a  pointers to the.
33730 2a 2a 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  ** database and 
33740 74 61 62 6c 65 20 6e 61 6d 65 20 63 6f 6e 74 61  table name conta
33750 69 6e 69 6e 67 20 74 68 65 20 61 66 66 65 63 74  ining the affect
33760 65 64 20 72 6f 77 2e 0a 2a 2a 20 5e 54 68 65 20  ed row..** ^The 
33770 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 70  final callback p
33780 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
33790 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 72  [rowid] of the r
337a0 6f 77 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 63  ow..** ^In the c
337b0 61 73 65 20 6f 66 20 61 6e 20 75 70 64 61 74 65  ase of an update
337c0 2c 20 74 68 69 73 20 69 73 20 74 68 65 20 5b 72  , this is the [r
337d0 6f 77 69 64 5d 20 61 66 74 65 72 20 74 68 65 20  owid] after the 
337e0 75 70 64 61 74 65 20 74 61 6b 65 73 20 70 6c 61  update takes pla
337f0 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ce..**.** ^(The 
33800 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 73 20 6e  update hook is n
33810 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  ot invoked when 
33820 69 6e 74 65 72 6e 61 6c 20 73 79 73 74 65 6d 20  internal system 
33830 74 61 62 6c 65 73 20 61 72 65 0a 2a 2a 20 6d 6f  tables are.** mo
33840 64 69 66 69 65 64 20 28 69 2e 65 2e 20 73 71 6c  dified (i.e. sql
33850 69 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 20 73  ite_master and s
33860 71 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 29 2e  qlite_sequence).
33870 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65  )^.**.** ^In the
33880 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65   current impleme
33890 6e 74 61 74 69 6f 6e 2c 20 74 68 65 20 75 70 64  ntation, the upd
338a0 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 73 20 6e  ate hook.** is n
338b0 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  ot invoked when 
338c0 64 75 70 6c 69 63 61 74 69 6f 6e 20 72 6f 77 73  duplication rows
338d0 20 61 72 65 20 64 65 6c 65 74 65 64 20 62 65 63   are deleted bec
338e0 61 75 73 65 20 6f 66 20 61 6e 0a 2a 2a 20 5b 4f  ause of an.** [O
338f0 4e 20 43 4f 4e 46 4c 49 43 54 20 7c 20 4f 4e 20  N CONFLICT | ON 
33900 43 4f 4e 46 4c 49 43 54 20 52 45 50 4c 41 43 45  CONFLICT REPLACE
33910 5d 20 63 6c 61 75 73 65 2e 20 20 5e 4e 6f 72 20  ] clause.  ^Nor 
33920 69 73 20 74 68 65 20 75 70 64 61 74 65 20 68 6f  is the update ho
33930 6f 6b 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 77 68  ok.** invoked wh
33940 65 6e 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65  en rows are dele
33950 74 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 74  ted using the [t
33960 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61  runcate optimiza
33970 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 65 78  tion]..** The ex
33980 63 65 70 74 69 6f 6e 73 20 64 65 66 69 6e 65 64  ceptions defined
33990 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61   in this paragra
339a0 70 68 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20  ph might change 
339b0 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72  in a future.** r
339c0 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
339d0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 70 64 61  ..**.** The upda
339e0 74 65 20 68 6f 6f 6b 20 69 6d 70 6c 65 6d 65 6e  te hook implemen
339f0 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  tation must not 
33a00 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
33a10 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
33a20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
33a30 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
33a40 6f 6b 65 64 20 74 68 65 20 75 70 64 61 74 65 20  oked the update 
33a50 68 6f 6f 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f  hook.  Any actio
33a60 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20  ns.** to modify 
33a70 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
33a80 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20  nection must be 
33a90 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61  deferred until a
33aa0 66 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70  fter the.** comp
33ab0 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73  letion of the [s
33ac0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63  qlite3_step()] c
33ad0 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
33ae0 65 64 20 74 68 65 20 75 70 64 61 74 65 20 68 6f  ed the update ho
33af0 6f 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  ok..** Note that
33b00 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
33b10 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
33b20 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74  ite3_step()] bot
33b30 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a  h modify their.*
33b40 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
33b50 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d  ctions for the m
33b60 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66  eaning of "modif
33b70 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67  y" in this parag
33b80 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  raph..**.** ^The
33b90 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f   sqlite3_update_
33ba0 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 66 75 6e 63  hook(D,C,P) func
33bb0 74 69 6f 6e 0a 2a 2a 20 72 65 74 75 72 6e 73 20  tion.** returns 
33bc0 74 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 66  the P argument f
33bd0 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f 75 73  rom the previous
33be0 20 63 61 6c 6c 0a 2a 2a 20 6f 6e 20 74 68 65 20   call.** on the 
33bf0 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63  same [database c
33c00 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72  onnection] D, or
33c10 20 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68 65   NULL for.** the
33c20 20 66 69 72 73 74 20 63 61 6c 6c 20 6f 6e 20 44   first call on D
33c30 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
33c40 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
33c50 6d 6d 69 74 5f 68 6f 6f 6b 28 29 5d 2c 20 5b 73  mmit_hook()], [s
33c60 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f  qlite3_rollback_
33c70 68 6f 6f 6b 28 29 5d 2c 0a 2a 2a 20 61 6e 64 20  hook()],.** and 
33c80 5b 73 71 6c 69 74 65 33 5f 70 72 65 75 70 64 61  [sqlite3_preupda
33c90 74 65 5f 68 6f 6f 6b 28 29 5d 20 69 6e 74 65 72  te_hook()] inter
33ca0 66 61 63 65 73 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  faces..*/.void *
33cb0 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
33cc0 6f 6f 6b 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  ook(.  sqlite3*,
33cd0 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   .  void(*)(void
33ce0 20 2a 2c 69 6e 74 20 2c 63 68 61 72 20 63 6f 6e   *,int ,char con
33cf0 73 74 20 2a 2c 63 68 61 72 20 63 6f 6e 73 74 20  st *,char const 
33d00 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  *,sqlite3_int64)
33d10 2c 0a 20 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a  ,.  void*.);../*
33d20 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e  .** CAPI3REF: En
33d30 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20  able Or Disable 
33d40 53 68 61 72 65 64 20 50 61 67 65 72 20 43 61 63  Shared Pager Cac
33d50 68 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  he.** KEYWORDS: 
33d60 7b 73 68 61 72 65 64 20 63 61 63 68 65 7d 0a 2a  {shared cache}.*
33d70 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74  *.** ^(This rout
33d80 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  ine enables or d
33d90 69 73 61 62 6c 65 73 20 74 68 65 20 73 68 61 72  isables the shar
33da0 69 6e 67 20 6f 66 20 74 68 65 20 64 61 74 61 62  ing of the datab
33db0 61 73 65 20 63 61 63 68 65 0a 2a 2a 20 61 6e 64  ase cache.** and
33dc0 20 73 63 68 65 6d 61 20 64 61 74 61 20 73 74 72   schema data str
33dd0 75 63 74 75 72 65 73 20 62 65 74 77 65 65 6e 20  uctures between 
33de0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
33df0 74 69 6f 6e 20 7c 20 63 6f 6e 6e 65 63 74 69 6f  tion | connectio
33e00 6e 73 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61  ns].** to the sa
33e10 6d 65 20 64 61 74 61 62 61 73 65 2e 20 53 68 61  me database. Sha
33e20 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20  ring is enabled 
33e30 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  if the argument 
33e40 69 73 20 74 72 75 65 0a 2a 2a 20 61 6e 64 20 64  is true.** and d
33e50 69 73 61 62 6c 65 64 20 69 66 20 74 68 65 20 61  isabled if the a
33e60 72 67 75 6d 65 6e 74 20 69 73 20 66 61 6c 73 65  rgument is false
33e70 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 61 63 68 65  .)^.**.** ^Cache
33e80 20 73 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62   sharing is enab
33e90 6c 65 64 20 61 6e 64 20 64 69 73 61 62 6c 65 64  led and disabled
33ea0 20 66 6f 72 20 61 6e 20 65 6e 74 69 72 65 20 70   for an entire p
33eb0 72 6f 63 65 73 73 2e 0a 2a 2a 20 54 68 69 73 20  rocess..** This 
33ec0 69 73 20 61 20 63 68 61 6e 67 65 20 61 73 20 6f  is a change as o
33ed0 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  f SQLite version
33ee0 20 33 2e 35 2e 30 2e 20 49 6e 20 70 72 69 6f 72   3.5.0. In prior
33ef0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
33f00 69 74 65 2c 0a 2a 2a 20 73 68 61 72 69 6e 67 20  ite,.** sharing 
33f10 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 64  was enabled or d
33f20 69 73 61 62 6c 65 64 20 66 6f 72 20 65 61 63 68  isabled for each
33f30 20 74 68 72 65 61 64 20 73 65 70 61 72 61 74 65   thread separate
33f40 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ly..**.** ^(The 
33f50 63 61 63 68 65 20 73 68 61 72 69 6e 67 20 6d 6f  cache sharing mo
33f60 64 65 20 73 65 74 20 62 79 20 74 68 69 73 20 69  de set by this i
33f70 6e 74 65 72 66 61 63 65 20 65 66 66 65 63 74 73  nterface effects
33f80 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 0a   all subsequent.
33f90 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  ** calls to [sql
33fa0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
33fb0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
33fc0 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
33fd0 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20 45 78  open16()]..** Ex
33fe0 69 73 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  isting database 
33ff0 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 63 6f 6e 74  connections cont
34000 69 6e 75 65 20 75 73 65 20 74 68 65 20 73 68 61  inue use the sha
34010 72 69 6e 67 20 6d 6f 64 65 0a 2a 2a 20 74 68 61  ring mode.** tha
34020 74 20 77 61 73 20 69 6e 20 65 66 66 65 63 74 20  t was in effect 
34030 61 74 20 74 68 65 20 74 69 6d 65 20 74 68 65 79  at the time they
34040 20 77 65 72 65 20 6f 70 65 6e 65 64 2e 29 5e 0a   were opened.)^.
34050 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75  **.** ^(This rou
34060 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51  tine returns [SQ
34070 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72  LITE_OK] if shar
34080 65 64 20 63 61 63 68 65 20 77 61 73 20 65 6e 61  ed cache was ena
34090 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64  bled or disabled
340a0 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79  .** successfully
340b0 2e 20 20 41 6e 20 5b 65 72 72 6f 72 20 63 6f 64  .  An [error cod
340c0 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 6f  e] is returned o
340d0 74 68 65 72 77 69 73 65 2e 29 5e 0a 2a 2a 0a 2a  therwise.)^.**.*
340e0 2a 20 5e 53 68 61 72 65 64 20 63 61 63 68 65 20  * ^Shared cache 
340f0 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  is disabled by d
34100 65 66 61 75 6c 74 2e 20 42 75 74 20 74 68 69 73  efault. But this
34110 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e   might change in
34120 0a 2a 2a 20 66 75 74 75 72 65 20 72 65 6c 65 61  .** future relea
34130 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20  ses of SQLite.  
34140 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
34150 74 20 63 61 72 65 20 61 62 6f 75 74 20 73 68 61  t care about sha
34160 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 73 65 74  red.** cache set
34170 74 69 6e 67 20 73 68 6f 75 6c 64 20 73 65 74 20  ting should set 
34180 69 74 20 65 78 70 6c 69 63 69 74 6c 79 2e 0a 2a  it explicitly..*
34190 2a 0a 2a 2a 20 53 65 65 20 41 6c 73 6f 3a 20 20  *.** See Also:  
341a0 5b 53 51 4c 69 74 65 20 53 68 61 72 65 64 2d 43  [SQLite Shared-C
341b0 61 63 68 65 20 4d 6f 64 65 5d 0a 2a 2f 0a 69 6e  ache Mode].*/.in
341c0 74 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65  t sqlite3_enable
341d0 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 69 6e  _shared_cache(in
341e0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
341f0 52 45 46 3a 20 41 74 74 65 6d 70 74 20 54 6f 20  REF: Attempt To 
34200 46 72 65 65 20 48 65 61 70 20 4d 65 6d 6f 72 79  Free Heap Memory
34210 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
34220 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
34230 72 79 28 29 20 69 6e 74 65 72 66 61 63 65 20 61  ry() interface a
34240 74 74 65 6d 70 74 73 20 74 6f 20 66 72 65 65 20  ttempts to free 
34250 4e 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 68 65  N bytes.** of he
34260 61 70 20 6d 65 6d 6f 72 79 20 62 79 20 64 65 61  ap memory by dea
34270 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d 65 73  llocating non-es
34280 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 20 61  sential memory a
34290 6c 6c 6f 63 61 74 69 6f 6e 73 0a 2a 2a 20 68 65  llocations.** he
342a0 6c 64 20 62 79 20 74 68 65 20 64 61 74 61 62 61  ld by the databa
342b0 73 65 20 6c 69 62 72 61 72 79 2e 20 20 20 4d 65  se library.   Me
342c0 6d 6f 72 79 20 75 73 65 64 20 74 6f 20 63 61 63  mory used to cac
342d0 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 70  he database.** p
342e0 61 67 65 73 20 74 6f 20 69 6d 70 72 6f 76 65 20  ages to improve 
342f0 70 65 72 66 6f 72 6d 61 6e 63 65 20 69 73 20 61  performance is a
34300 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 6e 6f 6e  n example of non
34310 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72  -essential memor
34320 79 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72  y..** ^sqlite3_r
34330 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20  elease_memory() 
34340 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
34350 65 72 20 6f 66 20 62 79 74 65 73 20 61 63 74 75  er of bytes actu
34360 61 6c 6c 79 20 66 72 65 65 64 2c 0a 2a 2a 20 77  ally freed,.** w
34370 68 69 63 68 20 6d 69 67 68 74 20 62 65 20 6d 6f  hich might be mo
34380 72 65 20 6f 72 20 6c 65 73 73 20 74 68 61 6e 20  re or less than 
34390 74 68 65 20 61 6d 6f 75 6e 74 20 72 65 71 75 65  the amount reque
343a0 73 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  sted..** ^The sq
343b0 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65  lite3_release_me
343c0 6d 6f 72 79 28 29 20 72 6f 75 74 69 6e 65 20 69  mory() routine i
343d0 73 20 61 20 6e 6f 2d 6f 70 20 72 65 74 75 72 6e  s a no-op return
343e0 69 6e 67 20 7a 65 72 6f 0a 2a 2a 20 69 66 20 53  ing zero.** if S
343f0 51 4c 69 74 65 20 69 73 20 6e 6f 74 20 63 6f 6d  QLite is not com
34400 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49  piled with [SQLI
34410 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59  TE_ENABLE_MEMORY
34420 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2e 0a 2a 2f  _MANAGEMENT]..*/
34430 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6c  .int sqlite3_rel
34440 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e 74 29  ease_memory(int)
34450 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
34460 46 3a 20 49 6d 70 6f 73 65 20 41 20 4c 69 6d 69  F: Impose A Limi
34470 74 20 4f 6e 20 48 65 61 70 20 53 69 7a 65 0a 2a  t On Heap Size.*
34480 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
34490 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
344a0 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 20  t64() interface 
344b0 73 65 74 73 20 61 6e 64 2f 6f 72 20 71 75 65 72  sets and/or quer
344c0 69 65 73 20 74 68 65 0a 2a 2a 20 73 6f 66 74 20  ies the.** soft 
344d0 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20 61 6d 6f  limit on the amo
344e0 75 6e 74 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f  unt of heap memo
344f0 72 79 20 74 68 61 74 20 6d 61 79 20 62 65 20 61  ry that may be a
34500 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69  llocated by SQLi
34510 74 65 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 73  te..** ^SQLite s
34520 74 72 69 76 65 73 20 74 6f 20 6b 65 65 70 20 68  trives to keep h
34530 65 61 70 20 6d 65 6d 6f 72 79 20 75 74 69 6c 69  eap memory utili
34540 7a 61 74 69 6f 6e 20 62 65 6c 6f 77 20 74 68 65  zation below the
34550 20 73 6f 66 74 20 68 65 61 70 0a 2a 2a 20 6c 69   soft heap.** li
34560 6d 69 74 20 62 79 20 72 65 64 75 63 69 6e 67 20  mit by reducing 
34570 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61  the number of pa
34580 67 65 73 20 68 65 6c 64 20 69 6e 20 74 68 65 20  ges held in the 
34590 70 61 67 65 20 63 61 63 68 65 0a 2a 2a 20 61 73  page cache.** as
345a0 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 75 73 61   heap memory usa
345b0 67 65 73 20 61 70 70 72 6f 61 63 68 65 73 20 74  ges approaches t
345c0 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68  he limit..** ^Th
345d0 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
345e0 74 20 69 73 20 22 73 6f 66 74 22 20 62 65 63 61  t is "soft" beca
345f0 75 73 65 20 65 76 65 6e 20 74 68 6f 75 67 68 20  use even though 
34600 53 51 4c 69 74 65 20 73 74 72 69 76 65 73 20 74  SQLite strives t
34610 6f 20 73 74 61 79 0a 2a 2a 20 62 65 6c 6f 77 20  o stay.** below 
34620 74 68 65 20 6c 69 6d 69 74 2c 20 69 74 20 77 69  the limit, it wi
34630 6c 6c 20 65 78 63 65 65 64 20 74 68 65 20 6c 69  ll exceed the li
34640 6d 69 74 20 72 61 74 68 65 72 20 74 68 61 6e 20  mit rather than 
34650 67 65 6e 65 72 61 74 65 0a 2a 2a 20 61 6e 20 5b  generate.** an [
34660 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 65 72  SQLITE_NOMEM] er
34670 72 6f 72 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  ror.  In other w
34680 6f 72 64 73 2c 20 74 68 65 20 73 6f 66 74 20 68  ords, the soft h
34690 65 61 70 20 6c 69 6d 69 74 20 0a 2a 2a 20 69 73  eap limit .** is
346a0 20 61 64 76 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a   advisory only..
346b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  **.** ^The retur
346c0 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  n value from sql
346d0 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
346e0 69 6d 69 74 36 34 28 29 20 69 73 20 74 68 65 20  imit64() is the 
346f0 73 69 7a 65 20 6f 66 0a 2a 2a 20 74 68 65 20 73  size of.** the s
34700 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 70  oft heap limit p
34710 72 69 6f 72 20 74 6f 20 74 68 65 20 63 61 6c 6c  rior to the call
34720 2e 20 20 5e 49 66 20 74 68 65 20 61 72 67 75 6d  .  ^If the argum
34730 65 6e 74 20 4e 20 69 73 20 6e 65 67 61 74 69 76  ent N is negativ
34740 65 0a 2a 2a 20 74 68 65 6e 20 6e 6f 20 63 68 61  e.** then no cha
34750 6e 67 65 20 69 73 20 6d 61 64 65 20 74 6f 20 74  nge is made to t
34760 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
34770 69 74 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20  it.  Hence, the 
34780 63 75 72 72 65 6e 74 0a 2a 2a 20 73 69 7a 65 20  current.** size 
34790 6f 66 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  of the soft heap
347a0 20 6c 69 6d 69 74 20 63 61 6e 20 62 65 20 64 65   limit can be de
347b0 74 65 72 6d 69 6e 65 64 20 62 79 20 69 6e 76 6f  termined by invo
347c0 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  king.** sqlite3_
347d0 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36  soft_heap_limit6
347e0 34 28 29 20 77 69 74 68 20 61 20 6e 65 67 61 74  4() with a negat
347f0 69 76 65 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  ive argument..**
34800 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 72 67 75  .** ^If the argu
34810 6d 65 6e 74 20 4e 20 69 73 20 7a 65 72 6f 20 74  ment N is zero t
34820 68 65 6e 20 74 68 65 20 73 6f 66 74 20 68 65 61  hen the soft hea
34830 70 20 6c 69 6d 69 74 20 69 73 20 64 69 73 61 62  p limit is disab
34840 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  led..**.** ^(The
34850 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
34860 20 69 73 20 6e 6f 74 20 65 6e 66 6f 72 63 65 64   is not enforced
34870 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
34880 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  implementation.*
34890 2a 20 69 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  * if one or more
348a0 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f   of following co
348b0 6e 64 69 74 69 6f 6e 73 20 61 72 65 20 74 72 75  nditions are tru
348c0 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  e:.**.** <ul>.**
348d0 20 3c 6c 69 3e 20 54 68 65 20 73 6f 66 74 20 68   <li> The soft h
348e0 65 61 70 20 6c 69 6d 69 74 20 69 73 20 73 65 74  eap limit is set
348f0 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 20 3c 6c 69   to zero..** <li
34900 3e 20 4d 65 6d 6f 72 79 20 61 63 63 6f 75 6e 74  > Memory account
34910 69 6e 67 20 69 73 20 64 69 73 61 62 6c 65 64 20  ing is disabled 
34920 75 73 69 6e 67 20 61 20 63 6f 6d 62 69 6e 61 74  using a combinat
34930 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20  ion of the.**   
34940 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66     [sqlite3_conf
34950 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ig]([SQLITE_CONF
34960 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 2c 2e 2e  IG_MEMSTATUS],..
34970 2e 29 20 73 74 61 72 74 2d 74 69 6d 65 20 6f 70  .) start-time op
34980 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20 20 20  tion and.**     
34990 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 44 45 46   the [SQLITE_DEF
349a0 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 20  AULT_MEMSTATUS] 
349b0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
349c0 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 41 6e 20  ion..** <li> An 
349d0 61 6c 74 65 72 6e 61 74 69 76 65 20 70 61 67 65  alternative page
349e0 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
349f0 61 74 69 6f 6e 20 69 73 20 73 70 65 63 69 66 69  ation is specifi
34a00 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20  ed using.**     
34a10 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
34a20 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ]([SQLITE_CONFIG
34a30 5f 50 43 41 43 48 45 5d 2c 2e 2e 2e 29 2e 0a 2a  _PCACHE],...)..*
34a40 2a 20 3c 6c 69 3e 20 54 68 65 20 70 61 67 65 20  * <li> The page 
34a50 63 61 63 68 65 20 61 6c 6c 6f 63 61 74 65 73 20  cache allocates 
34a60 66 72 6f 6d 20 69 74 73 20 6f 77 6e 20 6d 65 6d  from its own mem
34a70 6f 72 79 20 70 6f 6f 6c 20 73 75 70 70 6c 69 65  ory pool supplie
34a80 64 0a 2a 2a 20 20 20 20 20 20 62 79 20 5b 73 71  d.**      by [sq
34a90 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53  lite3_config]([S
34aa0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
34ab0 45 43 41 43 48 45 5d 2c 2e 2e 2e 29 20 72 61 74  ECACHE],...) rat
34ac0 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20  her than.**     
34ad0 20 66 72 6f 6d 20 74 68 65 20 68 65 61 70 2e 0a   from the heap..
34ae0 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  ** </ul>)^.**.**
34af0 20 42 65 67 69 6e 6e 69 6e 67 20 77 69 74 68 20   Beginning with 
34b00 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
34b10 2e 37 2e 33 2c 20 74 68 65 20 73 6f 66 74 20 68  .7.3, the soft h
34b20 65 61 70 20 6c 69 6d 69 74 20 69 73 20 65 6e 66  eap limit is enf
34b30 6f 72 63 65 64 0a 2a 2a 20 72 65 67 61 72 64 6c  orced.** regardl
34b40 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
34b50 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54  r not the [SQLIT
34b60 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f  E_ENABLE_MEMORY_
34b70 4d 41 4e 41 47 45 4d 45 4e 54 5d 0a 2a 2a 20 63  MANAGEMENT].** c
34b80 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
34b90 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20  on is invoked.  
34ba0 57 69 74 68 20 5b 53 51 4c 49 54 45 5f 45 4e 41  With [SQLITE_ENA
34bb0 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47  BLE_MEMORY_MANAG
34bc0 45 4d 45 4e 54 5d 2c 0a 2a 2a 20 74 68 65 20 73  EMENT],.** the s
34bd0 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69  oft heap limit i
34be0 73 20 65 6e 66 6f 72 63 65 64 20 6f 6e 20 65 76  s enforced on ev
34bf0 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ery memory alloc
34c00 61 74 69 6f 6e 2e 20 20 57 69 74 68 6f 75 74 0a  ation.  Without.
34c10 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  ** [SQLITE_ENABL
34c20 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d  E_MEMORY_MANAGEM
34c30 45 4e 54 5d 2c 20 74 68 65 20 73 6f 66 74 20 68  ENT], the soft h
34c40 65 61 70 20 6c 69 6d 69 74 20 69 73 20 6f 6e 6c  eap limit is onl
34c50 79 20 65 6e 66 6f 72 63 65 64 0a 2a 2a 20 77 68  y enforced.** wh
34c60 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20 61 6c 6c  en memory is all
34c70 6f 63 61 74 65 64 20 62 79 20 74 68 65 20 70 61  ocated by the pa
34c80 67 65 20 63 61 63 68 65 2e 20 20 54 65 73 74 69  ge cache.  Testi
34c90 6e 67 20 73 75 67 67 65 73 74 73 20 74 68 61 74  ng suggests that
34ca0 20 62 65 63 61 75 73 65 0a 2a 2a 20 74 68 65 20   because.** the 
34cb0 70 61 67 65 20 63 61 63 68 65 20 69 73 20 74 68  page cache is th
34cc0 65 20 70 72 65 64 6f 6d 69 6e 61 74 65 20 6d 65  e predominate me
34cd0 6d 6f 72 79 20 75 73 65 72 20 69 6e 20 53 51 4c  mory user in SQL
34ce0 69 74 65 2c 20 6d 6f 73 74 0a 2a 2a 20 61 70 70  ite, most.** app
34cf0 6c 69 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 61  lications will a
34d00 63 68 69 65 76 65 20 61 64 65 71 75 61 74 65 20  chieve adequate 
34d10 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
34d20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 77 69 74 68  enforcement with
34d30 6f 75 74 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f  out.** the use o
34d40 66 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  f [SQLITE_ENABLE
34d50 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45  _MEMORY_MANAGEME
34d60 4e 54 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  NT]..**.** The c
34d70 69 72 63 75 6d 73 74 61 6e 63 65 73 20 75 6e 64  ircumstances und
34d80 65 72 20 77 68 69 63 68 20 53 51 4c 69 74 65 20  er which SQLite 
34d90 77 69 6c 6c 20 65 6e 66 6f 72 63 65 20 74 68 65  will enforce the
34da0 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
34db0 20 6d 61 79 0a 2a 2a 20 63 68 61 6e 67 65 73 20   may.** changes 
34dc0 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
34dd0 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  es of SQLite..*/
34de0 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
34df0 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
34e00 5f 6c 69 6d 69 74 36 34 28 73 71 6c 69 74 65 33  _limit64(sqlite3
34e10 5f 69 6e 74 36 34 20 4e 29 3b 0a 0a 2f 2a 0a 2a  _int64 N);../*.*
34e20 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 70 72  * CAPI3REF: Depr
34e30 65 63 61 74 65 64 20 53 6f 66 74 20 48 65 61 70  ecated Soft Heap
34e40 20 4c 69 6d 69 74 20 49 6e 74 65 72 66 61 63 65   Limit Interface
34e50 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a  .** DEPRECATED.*
34e60 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 64  *.** This is a d
34e70 65 70 72 65 63 61 74 65 64 20 76 65 72 73 69 6f  eprecated versio
34e80 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  n of the [sqlite
34e90 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
34ea0 74 36 34 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  t64()].** interf
34eb0 61 63 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69  ace.  This routi
34ec0 6e 65 20 69 73 20 70 72 6f 76 69 64 65 64 20 66  ne is provided f
34ed0 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f  or historical co
34ee0 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20 6f  mpatibility.** o
34ef0 6e 6c 79 2e 20 20 41 6c 6c 20 6e 65 77 20 61 70  nly.  All new ap
34f00 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
34f10 64 20 75 73 65 20 74 68 65 0a 2a 2a 20 5b 73 71  d use the.** [sq
34f20 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
34f30 6c 69 6d 69 74 36 34 28 29 5d 20 69 6e 74 65 72  limit64()] inter
34f40 66 61 63 65 20 72 61 74 68 65 72 20 74 68 61 6e  face rather than
34f50 20 74 68 69 73 20 6f 6e 65 2e 0a 2a 2f 0a 53 51   this one..*/.SQ
34f60 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
34f70 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 6f 66  void sqlite3_sof
34f80 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 69 6e 74  t_heap_limit(int
34f90 20 4e 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50   N);.../*.** CAP
34fa0 49 33 52 45 46 3a 20 45 78 74 72 61 63 74 20 4d  I3REF: Extract M
34fb0 65 74 61 64 61 74 61 20 41 62 6f 75 74 20 41 20  etadata About A 
34fc0 43 6f 6c 75 6d 6e 20 4f 66 20 41 20 54 61 62 6c  Column Of A Tabl
34fd0 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  e.**.** ^This ro
34fe0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 6d 65  utine returns me
34ff0 74 61 64 61 74 61 20 61 62 6f 75 74 20 61 20 73  tadata about a s
35000 70 65 63 69 66 69 63 20 63 6f 6c 75 6d 6e 20 6f  pecific column o
35010 66 20 61 20 73 70 65 63 69 66 69 63 0a 2a 2a 20  f a specific.** 
35020 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 61  database table a
35030 63 63 65 73 73 69 62 6c 65 20 75 73 69 6e 67 20  ccessible using 
35040 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
35050 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
35060 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74 68  .** passed as th
35070 65 20 66 69 72 73 74 20 66 75 6e 63 74 69 6f 6e  e first function
35080 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
35090 20 5e 54 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20   ^The column is 
350a0 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68  identified by th
350b0 65 20 73 65 63 6f 6e 64 2c 20 74 68 69 72 64 20  e second, third 
350c0 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d  and fourth param
350d0 65 74 65 72 73 20 74 6f 0a 2a 2a 20 74 68 69 73  eters to.** this
350e0 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 54 68 65 20   function. ^The 
350f0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
35100 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20 6e   is either the n
35110 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
35120 61 73 65 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d 61  ase.** (i.e. "ma
35130 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20 6f 72 20  in", "temp", or 
35140 61 6e 20 61 74 74 61 63 68 65 64 20 64 61 74 61  an attached data
35150 62 61 73 65 29 20 63 6f 6e 74 61 69 6e 69 6e 67  base) containing
35160 20 74 68 65 20 73 70 65 63 69 66 69 65 64 0a 2a   the specified.*
35170 2a 20 74 61 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e  * table or NULL.
35180 20 5e 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c   ^If it is NULL,
35190 20 74 68 65 6e 20 61 6c 6c 20 61 74 74 61 63 68   then all attach
351a0 65 64 20 64 61 74 61 62 61 73 65 73 20 61 72 65  ed databases are
351b0 20 73 65 61 72 63 68 65 64 0a 2a 2a 20 66 6f 72   searched.** for
351c0 20 74 68 65 20 74 61 62 6c 65 20 75 73 69 6e 67   the table using
351d0 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69   the same algori
351e0 74 68 6d 20 75 73 65 64 20 62 79 20 74 68 65 20  thm used by the 
351f0 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20  database engine 
35200 74 6f 0a 2a 2a 20 72 65 73 6f 6c 76 65 20 75 6e  to.** resolve un
35210 71 75 61 6c 69 66 69 65 64 20 74 61 62 6c 65 20  qualified table 
35220 72 65 66 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a  references..**.*
35230 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 6e 64  * ^The third and
35240 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
35250 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74  rs to this funct
35260 69 6f 6e 20 61 72 65 20 74 68 65 20 74 61 62 6c  ion are the tabl
35270 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  e and column.** 
35280 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 65 73 69  name of the desi
35290 72 65 64 20 63 6f 6c 75 6d 6e 2c 20 72 65 73 70  red column, resp
352a0 65 63 74 69 76 65 6c 79 2e 20 4e 65 69 74 68 65  ectively. Neithe
352b0 72 20 6f 66 20 74 68 65 73 65 20 70 61 72 61 6d  r of these param
352c0 65 74 65 72 73 0a 2a 2a 20 6d 61 79 20 62 65 20  eters.** may be 
352d0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4d 65 74  NULL..**.** ^Met
352e0 61 64 61 74 61 20 69 73 20 72 65 74 75 72 6e 65  adata is returne
352f0 64 20 62 79 20 77 72 69 74 69 6e 67 20 74 6f 20  d by writing to 
35300 74 68 65 20 6d 65 6d 6f 72 79 20 6c 6f 63 61 74  the memory locat
35310 69 6f 6e 73 20 70 61 73 73 65 64 20 61 73 20 74  ions passed as t
35320 68 65 20 35 74 68 0a 2a 2a 20 61 6e 64 20 73 75  he 5th.** and su
35330 62 73 65 71 75 65 6e 74 20 70 61 72 61 6d 65 74  bsequent paramet
35340 65 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63  ers to this func
35350 74 69 6f 6e 2e 20 5e 41 6e 79 20 6f 66 20 74 68  tion. ^Any of th
35360 65 73 65 20 61 72 67 75 6d 65 6e 74 73 20 6d 61  ese arguments ma
35370 79 20 62 65 0a 2a 2a 20 4e 55 4c 4c 2c 20 69 6e  y be.** NULL, in
35380 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
35390 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 65 6c  corresponding el
353a0 65 6d 65 6e 74 20 6f 66 20 6d 65 74 61 64 61 74  ement of metadat
353b0 61 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a  a is omitted..**
353c0 0a 2a 2a 20 5e 28 3c 62 6c 6f 63 6b 71 75 6f 74  .** ^(<blockquot
353d0 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72  e>.** <table bor
353e0 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e  der="1">.** <tr>
353f0 3c 74 68 3e 20 50 61 72 61 6d 65 74 65 72 20 3c  <th> Parameter <
35400 74 68 3e 20 4f 75 74 70 75 74 3c 62 72 3e 54 79  th> Output<br>Ty
35410 70 65 20 3c 74 68 3e 20 20 44 65 73 63 72 69 70  pe <th>  Descrip
35420 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c  tion.**.** <tr><
35430 74 64 3e 20 35 74 68 20 3c 74 64 3e 20 63 6f 6e  td> 5th <td> con
35440 73 74 20 63 68 61 72 2a 20 3c 74 64 3e 20 44 61  st char* <td> Da
35450 74 61 20 74 79 70 65 0a 2a 2a 20 3c 74 72 3e 3c  ta type.** <tr><
35460 74 64 3e 20 36 74 68 20 3c 74 64 3e 20 63 6f 6e  td> 6th <td> con
35470 73 74 20 63 68 61 72 2a 20 3c 74 64 3e 20 4e 61  st char* <td> Na
35480 6d 65 20 6f 66 20 64 65 66 61 75 6c 74 20 63 6f  me of default co
35490 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
354a0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 37 74 68  .** <tr><td> 7th
354b0 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20   <td> int       
354c0 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63    <td> True if c
354d0 6f 6c 75 6d 6e 20 68 61 73 20 61 20 4e 4f 54 20  olumn has a NOT 
354e0 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 0a  NULL constraint.
354f0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 38 74 68 20  ** <tr><td> 8th 
35500 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20  <td> int        
35510 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f   <td> True if co
35520 6c 75 6d 6e 20 69 73 20 70 61 72 74 20 6f 66 20  lumn is part of 
35530 74 68 65 20 50 52 49 4d 41 52 59 20 4b 45 59 0a  the PRIMARY KEY.
35540 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 39 74 68 20  ** <tr><td> 9th 
35550 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20  <td> int        
35560 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f   <td> True if co
35570 6c 75 6d 6e 20 69 73 20 5b 41 55 54 4f 49 4e 43  lumn is [AUTOINC
35580 52 45 4d 45 4e 54 5d 0a 2a 2a 20 3c 2f 74 61 62  REMENT].** </tab
35590 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75  le>.** </blockqu
355a0 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ote>)^.**.** ^Th
355b0 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 64  e memory pointed
355c0 20 74 6f 20 62 79 20 74 68 65 20 63 68 61 72 61   to by the chara
355d0 63 74 65 72 20 70 6f 69 6e 74 65 72 73 20 72 65  cter pointers re
355e0 74 75 72 6e 65 64 20 66 6f 72 20 74 68 65 0a 2a  turned for the.*
355f0 2a 20 64 65 63 6c 61 72 61 74 69 6f 6e 20 74 79  * declaration ty
35600 70 65 20 61 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e  pe and collation
35610 20 73 65 71 75 65 6e 63 65 20 69 73 20 76 61 6c   sequence is val
35620 69 64 20 6f 6e 6c 79 20 75 6e 74 69 6c 20 74 68  id only until th
35630 65 20 6e 65 78 74 0a 2a 2a 20 63 61 6c 6c 20 74  e next.** call t
35640 6f 20 61 6e 79 20 53 51 4c 69 74 65 20 41 50 49  o any SQLite API
35650 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
35660 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 69   ^If the specifi
35670 65 64 20 74 61 62 6c 65 20 69 73 20 61 63 74 75  ed table is actu
35680 61 6c 6c 79 20 61 20 76 69 65 77 2c 20 61 6e 20  ally a view, an 
35690 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
356a0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
356b0 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 69 65  ^If the specifie
356c0 64 20 63 6f 6c 75 6d 6e 20 69 73 20 22 72 6f 77  d column is "row
356d0 69 64 22 2c 20 22 6f 69 64 22 20 6f 72 20 22 5f  id", "oid" or "_
356e0 72 6f 77 69 64 5f 22 20 61 6e 64 20 61 6e 0a 2a  rowid_" and an.*
356f0 2a 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41  * [INTEGER PRIMA
35700 52 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 20 68  RY KEY] column h
35710 61 73 20 62 65 65 6e 20 65 78 70 6c 69 63 69 74  as been explicit
35720 6c 79 20 64 65 63 6c 61 72 65 64 2c 20 74 68 65  ly declared, the
35730 6e 20 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20  n the output.** 
35740 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 73  parameters are s
35750 65 74 20 66 6f 72 20 74 68 65 20 65 78 70 6c 69  et for the expli
35760 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63  citly declared c
35770 6f 6c 75 6d 6e 2e 20 5e 28 49 66 20 74 68 65 72  olumn. ^(If ther
35780 65 20 69 73 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69  e is no.** expli
35790 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 5b  citly declared [
357a0 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20  INTEGER PRIMARY 
357b0 4b 45 59 5d 20 63 6f 6c 75 6d 6e 2c 20 74 68 65  KEY] column, the
357c0 6e 20 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20  n the output.** 
357d0 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 73  parameters are s
357e0 65 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  et as follows:.*
357f0 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20  *.** <pre>.**   
35800 20 20 64 61 74 61 20 74 79 70 65 3a 20 22 49 4e    data type: "IN
35810 54 45 47 45 52 22 0a 2a 2a 20 20 20 20 20 63 6f  TEGER".**     co
35820 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
35830 3a 20 22 42 49 4e 41 52 59 22 0a 2a 2a 20 20 20  : "BINARY".**   
35840 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a    not null: 0.**
35850 20 20 20 20 20 70 72 69 6d 61 72 79 20 6b 65 79       primary key
35860 3a 20 31 0a 2a 2a 20 20 20 20 20 61 75 74 6f 20  : 1.**     auto 
35870 69 6e 63 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20  increment: 0.** 
35880 3c 2f 70 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  </pre>)^.**.** ^
35890 28 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d  (This function m
358a0 61 79 20 6c 6f 61 64 20 6f 6e 65 20 6f 72 20 6d  ay load one or m
358b0 6f 72 65 20 73 63 68 65 6d 61 73 20 66 72 6f 6d  ore schemas from
358c0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 2e   database files.
358d0 20 49 66 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20   If an.** error 
358e0 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68  occurs during th
358f0 69 73 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69  is process, or i
35900 66 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20  f the requested 
35910 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a  table or column.
35920 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20 66 6f 75  ** cannot be fou
35930 6e 64 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  nd, an [error co
35940 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  de] is returned 
35950 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  and an error mes
35960 73 61 67 65 20 6c 65 66 74 0a 2a 2a 20 69 6e 20  sage left.** in 
35970 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
35980 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 6f 20 62 65  nnection] (to be
35990 20 72 65 74 72 69 65 76 65 64 20 75 73 69 6e 67   retrieved using
359a0 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28   sqlite3_errmsg(
359b0 29 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  )).)^.**.** ^Thi
359c0 73 20 41 50 49 20 69 73 20 6f 6e 6c 79 20 61 76  s API is only av
359d0 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c  ailable if the l
359e0 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69  ibrary was compi
359f0 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
35a00 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43  [SQLITE_ENABLE_C
35a10 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20  OLUMN_METADATA] 
35a20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73  C-preprocessor s
35a30 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a  ymbol defined..*
35a40 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 61  /.int sqlite3_ta
35a50 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64  ble_column_metad
35a60 61 74 61 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ata(.  sqlite3 *
35a70 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
35a80 20 20 20 2f 2a 20 43 6f 6e 6e 65 63 74 69 6f 6e     /* Connection
35a90 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
35aa0 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65  st char *zDbName
35ab0 2c 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61  ,        /* Data
35ac0 62 61 73 65 20 6e 61 6d 65 20 6f 72 20 4e 55 4c  base name or NUL
35ad0 4c 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  L */.  const cha
35ae0 72 20 2a 7a 54 61 62 6c 65 4e 61 6d 65 2c 20 20  r *zTableName,  
35af0 20 20 20 2f 2a 20 54 61 62 6c 65 20 6e 61 6d 65     /* Table name
35b00 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
35b10 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 20   *zColumnName,  
35b20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65    /* Column name
35b30 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 74   */.  char const
35b40 20 2a 2a 70 7a 44 61 74 61 54 79 70 65 2c 20 20   **pzDataType,  
35b50 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 44 65 63    /* OUTPUT: Dec
35b60 6c 61 72 65 64 20 64 61 74 61 20 74 79 70 65 20  lared data type 
35b70 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20  */.  char const 
35b80 2a 2a 70 7a 43 6f 6c 6c 53 65 71 2c 20 20 20 20  **pzCollSeq,    
35b90 20 2f 2a 20 4f 55 54 50 55 54 3a 20 43 6f 6c 6c   /* OUTPUT: Coll
35ba0 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 6e  ation sequence n
35bb0 61 6d 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 4e  ame */.  int *pN
35bc0 6f 74 4e 75 6c 6c 2c 20 20 20 20 20 20 20 20 20  otNull,         
35bd0 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20       /* OUTPUT: 
35be0 54 72 75 65 20 69 66 20 4e 4f 54 20 4e 55 4c 4c  True if NOT NULL
35bf0 20 63 6f 6e 73 74 72 61 69 6e 74 20 65 78 69 73   constraint exis
35c00 74 73 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 50 72  ts */.  int *pPr
35c10 69 6d 61 72 79 4b 65 79 2c 20 20 20 20 20 20 20  imaryKey,       
35c20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54      /* OUTPUT: T
35c30 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 70 61  rue if column pa
35c40 72 74 20 6f 66 20 50 4b 20 2a 2f 0a 20 20 69 6e  rt of PK */.  in
35c50 74 20 2a 70 41 75 74 6f 69 6e 63 20 20 20 20 20  t *pAutoinc     
35c60 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
35c70 50 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c  PUT: True if col
35c80 75 6d 6e 20 69 73 20 61 75 74 6f 2d 69 6e 63 72  umn is auto-incr
35c90 65 6d 65 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  ement */.);../*.
35ca0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f 61  ** CAPI3REF: Loa
35cb0 64 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e 0a 2a  d An Extension.*
35cc0 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72  *.** ^This inter
35cd0 66 61 63 65 20 6c 6f 61 64 73 20 61 6e 20 53 51  face loads an SQ
35ce0 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c  Lite extension l
35cf0 69 62 72 61 72 79 20 66 72 6f 6d 20 74 68 65 20  ibrary from the 
35d00 6e 61 6d 65 64 20 66 69 6c 65 2e 0a 2a 2a 0a 2a  named file..**.*
35d10 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c  * ^The sqlite3_l
35d20 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20  oad_extension() 
35d30 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
35d40 74 73 20 74 6f 20 6c 6f 61 64 20 61 6e 0a 2a 2a  ts to load an.**
35d50 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f   SQLite extensio
35d60 6e 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61 69  n library contai
35d70 6e 65 64 20 69 6e 20 74 68 65 20 66 69 6c 65 20  ned in the file 
35d80 7a 46 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  zFile..**.** ^Th
35d90 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 69 73  e entry point is
35da0 20 7a 50 72 6f 63 2e 0a 2a 2a 20 5e 7a 50 72 6f   zProc..** ^zPro
35db0 63 20 6d 61 79 20 62 65 20 30 2c 20 69 6e 20 77  c may be 0, in w
35dc0 68 69 63 68 20 63 61 73 65 20 74 68 65 20 6e 61  hich case the na
35dd0 6d 65 20 6f 66 20 74 68 65 20 65 6e 74 72 79 20  me of the entry 
35de0 70 6f 69 6e 74 0a 2a 2a 20 64 65 66 61 75 6c 74  point.** default
35df0 73 20 74 6f 20 22 73 71 6c 69 74 65 33 5f 65 78  s to "sqlite3_ex
35e00 74 65 6e 73 69 6f 6e 5f 69 6e 69 74 22 2e 0a 2a  tension_init"..*
35e10 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c  * ^The sqlite3_l
35e20 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20  oad_extension() 
35e30 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
35e40 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  s.** [SQLITE_OK]
35e50 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20   on success and 
35e60 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
35e70 66 20 73 6f 6d 65 74 68 69 6e 67 20 67 6f 65 73  f something goes
35e80 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 49 66 20 61   wrong..** ^If a
35e90 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 61  n error occurs a
35ea0 6e 64 20 70 7a 45 72 72 4d 73 67 20 69 73 20 6e  nd pzErrMsg is n
35eb0 6f 74 20 30 2c 20 74 68 65 6e 20 74 68 65 0a 2a  ot 0, then the.*
35ec0 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f  * [sqlite3_load_
35ed0 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74  extension()] int
35ee0 65 72 66 61 63 65 20 73 68 61 6c 6c 20 61 74 74  erface shall att
35ef0 65 6d 70 74 20 74 6f 0a 2a 2a 20 66 69 6c 6c 20  empt to.** fill 
35f00 2a 70 7a 45 72 72 4d 73 67 20 77 69 74 68 20 65  *pzErrMsg with e
35f10 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78  rror message tex
35f20 74 20 73 74 6f 72 65 64 20 69 6e 20 6d 65 6d 6f  t stored in memo
35f30 72 79 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66  ry.** obtained f
35f40 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
35f50 6c 6f 63 28 29 5d 2e 20 54 68 65 20 63 61 6c 6c  loc()]. The call
35f60 69 6e 67 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ing function.** 
35f70 73 68 6f 75 6c 64 20 66 72 65 65 20 74 68 69 73  should free this
35f80 20 6d 65 6d 6f 72 79 20 62 79 20 63 61 6c 6c 69   memory by calli
35f90 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ng [sqlite3_free
35fa0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 45 78 74 65  ()]..**.** ^Exte
35fb0 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d 75  nsion loading mu
35fc0 73 74 20 62 65 20 65 6e 61 62 6c 65 64 20 75 73  st be enabled us
35fd0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
35fe0 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65  enable_load_exte
35ff0 6e 73 69 6f 6e 28 29 5d 20 70 72 69 6f 72 20 74  nsion()] prior t
36000 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 41  o calling this A
36010 50 49 2c 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65  PI,.** otherwise
36020 20 61 6e 20 65 72 72 6f 72 20 77 69 6c 6c 20 62   an error will b
36030 65 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  e returned..**.*
36040 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
36050 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
36060 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
36070 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c  */.int sqlite3_l
36080 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 0a 20  oad_extension(. 
36090 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
360a0 20 20 20 20 20 20 20 2f 2a 20 4c 6f 61 64 20 74         /* Load t
360b0 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e 74  he extension int
360c0 6f 20 74 68 69 73 20 64 61 74 61 62 61 73 65 20  o this database 
360d0 63 6f 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20 20  connection */.  
360e0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
360f0 65 2c 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66  e,    /* Name of
36100 20 74 68 65 20 73 68 61 72 65 64 20 6c 69 62 72   the shared libr
36110 61 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 65  ary containing e
36120 78 74 65 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f  xtension */.  co
36130 6e 73 74 20 63 68 61 72 20 2a 7a 50 72 6f 63 2c  nst char *zProc,
36140 20 20 20 20 2f 2a 20 45 6e 74 72 79 20 70 6f 69      /* Entry poi
36150 6e 74 2e 20 20 44 65 72 69 76 65 64 20 66 72 6f  nt.  Derived fro
36160 6d 20 7a 46 69 6c 65 20 69 66 20 30 20 2a 2f 0a  m zFile if 0 */.
36170 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 4d 73    char **pzErrMs
36180 67 20 20 20 20 20 20 20 2f 2a 20 50 75 74 20 65  g       /* Put e
36190 72 72 6f 72 20 6d 65 73 73 61 67 65 20 68 65 72  rror message her
361a0 65 20 69 66 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b  e if not 0 */.);
361b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
361c0 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61  : Enable Or Disa
361d0 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f  ble Extension Lo
361e0 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 5e 53 6f 20  ading.**.** ^So 
361f0 61 73 20 6e 6f 74 20 74 6f 20 6f 70 65 6e 20 73  as not to open s
36200 65 63 75 72 69 74 79 20 68 6f 6c 65 73 20 69 6e  ecurity holes in
36210 20 6f 6c 64 65 72 20 61 70 70 6c 69 63 61 74 69   older applicati
36220 6f 6e 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20  ons that are.** 
36230 75 6e 70 72 65 70 61 72 65 64 20 74 6f 20 64 65  unprepared to de
36240 61 6c 20 77 69 74 68 20 65 78 74 65 6e 73 69 6f  al with extensio
36250 6e 20 6c 6f 61 64 69 6e 67 2c 20 61 6e 64 20 61  n loading, and a
36260 73 20 61 20 6d 65 61 6e 73 20 6f 66 20 64 69 73  s a means of dis
36270 61 62 6c 69 6e 67 0a 2a 2a 20 65 78 74 65 6e 73  abling.** extens
36280 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 77 68 69 6c  ion loading whil
36290 65 20 65 76 61 6c 75 61 74 69 6e 67 20 75 73 65  e evaluating use
362a0 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 2c 20 74  r-entered SQL, t
362b0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 41 50 49  he following API
362c0 0a 2a 2a 20 69 73 20 70 72 6f 76 69 64 65 64 20  .** is provided 
362d0 74 6f 20 74 75 72 6e 20 74 68 65 20 5b 73 71 6c  to turn the [sql
362e0 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  ite3_load_extens
362f0 69 6f 6e 28 29 5d 20 6d 65 63 68 61 6e 69 73 6d  ion()] mechanism
36300 20 6f 6e 20 61 6e 64 20 6f 66 66 2e 0a 2a 2a 0a   on and off..**.
36310 2a 2a 20 5e 45 78 74 65 6e 73 69 6f 6e 20 6c 6f  ** ^Extension lo
36320 61 64 69 6e 67 20 69 73 20 6f 66 66 20 62 79 20  ading is off by 
36330 64 65 66 61 75 6c 74 2e 20 53 65 65 20 74 69 63  default. See tic
36340 6b 65 74 20 23 31 38 36 33 2e 0a 2a 2a 20 5e 43  ket #1863..** ^C
36350 61 6c 6c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  all the sqlite3_
36360 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65  enable_load_exte
36370 6e 73 69 6f 6e 28 29 20 72 6f 75 74 69 6e 65 20  nsion() routine 
36380 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 31 0a 2a 2a  with onoff==1.**
36390 20 74 6f 20 74 75 72 6e 20 65 78 74 65 6e 73 69   to turn extensi
363a0 6f 6e 20 6c 6f 61 64 69 6e 67 20 6f 6e 20 61 6e  on loading on an
363b0 64 20 63 61 6c 6c 20 69 74 20 77 69 74 68 20 6f  d call it with o
363c0 6e 6f 66 66 3d 3d 30 20 74 6f 20 74 75 72 6e 0a  noff==0 to turn.
363d0 2a 2a 20 69 74 20 62 61 63 6b 20 6f 66 66 20 61  ** it back off a
363e0 67 61 69 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  gain..*/.int sql
363f0 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64  ite3_enable_load
36400 5f 65 78 74 65 6e 73 69 6f 6e 28 73 71 6c 69 74  _extension(sqlit
36410 65 33 20 2a 64 62 2c 20 69 6e 74 20 6f 6e 6f 66  e3 *db, int onof
36420 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  f);../*.** CAPI3
36430 52 45 46 3a 20 41 75 74 6f 6d 61 74 69 63 61 6c  REF: Automatical
36440 6c 79 20 4c 6f 61 64 20 53 74 61 74 69 63 61 6c  ly Load Statical
36450 6c 79 20 4c 69 6e 6b 65 64 20 45 78 74 65 6e 73  ly Linked Extens
36460 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ions.**.** ^This
36470 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
36480 73 20 74 68 65 20 78 45 6e 74 72 79 50 6f 69 6e  s the xEntryPoin
36490 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  t() function to 
364a0 62 65 20 69 6e 76 6f 6b 65 64 20 66 6f 72 0a 2a  be invoked for.*
364b0 2a 20 65 61 63 68 20 6e 65 77 20 5b 64 61 74 61  * each new [data
364c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
364d0 20 74 68 61 74 20 69 73 20 63 72 65 61 74 65 64   that is created
364e0 2e 20 20 54 68 65 20 69 64 65 61 20 68 65 72 65  .  The idea here
364f0 20 69 73 20 74 68 61 74 0a 2a 2a 20 78 45 6e 74   is that.** xEnt
36500 72 79 50 6f 69 6e 74 28 29 20 69 73 20 74 68 65  ryPoint() is the
36510 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 66 6f 72   entry point for
36520 20 61 20 73 74 61 74 69 63 61 6c 6c 79 20 6c 69   a statically li
36530 6e 6b 65 64 20 53 51 4c 69 74 65 20 65 78 74 65  nked SQLite exte
36540 6e 73 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73  nsion.** that is
36550 20 74 6f 20 62 65 20 61 75 74 6f 6d 61 74 69 63   to be automatic
36560 61 6c 6c 79 20 6c 6f 61 64 65 64 20 69 6e 74 6f  ally loaded into
36570 20 61 6c 6c 20 6e 65 77 20 64 61 74 61 62 61 73   all new databas
36580 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 0a 2a  e connections..*
36590 2a 0a 2a 2a 20 5e 28 45 76 65 6e 20 74 68 6f 75  *.** ^(Even thou
365a0 67 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  gh the function 
365b0 70 72 6f 74 6f 74 79 70 65 20 73 68 6f 77 73 20  prototype shows 
365c0 74 68 61 74 20 78 45 6e 74 72 79 50 6f 69 6e 74  that xEntryPoint
365d0 28 29 20 74 61 6b 65 73 0a 2a 2a 20 6e 6f 20 61  () takes.** no a
365e0 72 67 75 6d 65 6e 74 73 20 61 6e 64 20 72 65 74  rguments and ret
365f0 75 72 6e 73 20 76 6f 69 64 2c 20 53 51 4c 69 74  urns void, SQLit
36600 65 20 69 6e 76 6f 6b 65 73 20 78 45 6e 74 72 79  e invokes xEntry
36610 50 6f 69 6e 74 28 29 20 77 69 74 68 20 74 68 72  Point() with thr
36620 65 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20  ee.** arguments 
36630 61 6e 64 20 65 78 70 65 63 74 73 20 61 6e 64 20  and expects and 
36640 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20 61  integer result a
36650 73 20 69 66 20 74 68 65 20 73 69 67 6e 61 74 75  s if the signatu
36660 72 65 20 6f 66 20 74 68 65 0a 2a 2a 20 65 6e 74  re of the.** ent
36670 72 79 20 70 6f 69 6e 74 20 77 68 65 72 65 20 61  ry point where a
36680 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
36690 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
366a0 65 3e 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 69 6e  e>.** &nbsp;  in
366b0 74 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 0a 2a  t xEntryPoint(.*
366c0 2a 20 26 6e 62 73 70 3b 20 20 20 20 73 71 6c 69  * &nbsp;    sqli
366d0 74 65 33 20 2a 64 62 2c 0a 2a 2a 20 26 6e 62 73  te3 *db,.** &nbs
366e0 70 3b 20 20 20 20 63 6f 6e 73 74 20 63 68 61 72  p;    const char
366f0 20 2a 2a 70 7a 45 72 72 4d 73 67 2c 0a 2a 2a 20   **pzErrMsg,.** 
36700 26 6e 62 73 70 3b 20 20 20 20 63 6f 6e 73 74 20  &nbsp;    const 
36710 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 61  struct sqlite3_a
36720 70 69 5f 72 6f 75 74 69 6e 65 73 20 2a 70 54 68  pi_routines *pTh
36730 75 6e 6b 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 29  unk.** &nbsp;  )
36740 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
36750 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
36760 20 49 66 20 74 68 65 20 78 45 6e 74 72 79 50 6f   If the xEntryPo
36770 69 6e 74 20 72 6f 75 74 69 6e 65 20 65 6e 63 6f  int routine enco
36780 75 6e 74 65 72 73 20 61 6e 20 65 72 72 6f 72 2c  unters an error,
36790 20 69 74 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20   it should make 
367a0 2a 70 7a 45 72 72 4d 73 67 0a 2a 2a 20 70 6f 69  *pzErrMsg.** poi
367b0 6e 74 20 74 6f 20 61 6e 20 61 70 70 72 6f 70 72  nt to an appropr
367c0 69 61 74 65 20 65 72 72 6f 72 20 6d 65 73 73 61  iate error messa
367d0 67 65 20 28 6f 62 74 61 69 6e 65 64 20 66 72 6f  ge (obtained fro
367e0 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  m [sqlite3_mprin
367f0 74 66 28 29 5d 29 0a 2a 2a 20 61 6e 64 20 72 65  tf()]).** and re
36800 74 75 72 6e 20 61 6e 20 61 70 70 72 6f 70 72 69  turn an appropri
36810 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ate [error code]
36820 2e 20 20 5e 53 51 4c 69 74 65 20 65 6e 73 75 72  .  ^SQLite ensur
36830 65 73 20 74 68 61 74 20 2a 70 7a 45 72 72 4d 73  es that *pzErrMs
36840 67 0a 2a 2a 20 69 73 20 4e 55 4c 4c 20 62 65 66  g.** is NULL bef
36850 6f 72 65 20 63 61 6c 6c 69 6e 67 20 74 68 65 20  ore calling the 
36860 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 2e 20 20  xEntryPoint().  
36870 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76  ^SQLite will inv
36880 6f 6b 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  oke.** [sqlite3_
36890 66 72 65 65 28 29 5d 20 6f 6e 20 2a 70 7a 45 72  free()] on *pzEr
368a0 72 4d 73 67 20 61 66 74 65 72 20 78 45 6e 74 72  rMsg after xEntr
368b0 79 50 6f 69 6e 74 28 29 20 72 65 74 75 72 6e 73  yPoint() returns
368c0 2e 20 20 5e 49 66 20 61 6e 79 0a 2a 2a 20 78 45  .  ^If any.** xE
368d0 6e 74 72 79 50 6f 69 6e 74 28 29 20 72 65 74 75  ntryPoint() retu
368e0 72 6e 73 20 61 6e 20 65 72 72 6f 72 2c 20 74 68  rns an error, th
368f0 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  e [sqlite3_open(
36900 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
36910 6e 31 36 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73  n16()],.** or [s
36920 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
36930 5d 20 63 61 6c 6c 20 74 68 61 74 20 70 72 6f 76  ] call that prov
36940 6f 6b 65 64 20 74 68 65 20 78 45 6e 74 72 79 50  oked the xEntryP
36950 6f 69 6e 74 28 29 20 77 69 6c 6c 20 66 61 69 6c  oint() will fail
36960 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  ..**.** ^Calling
36970 20 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78   sqlite3_auto_ex
36980 74 65 6e 73 69 6f 6e 28 58 29 20 77 69 74 68 20  tension(X) with 
36990 61 6e 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 58  an entry point X
369a0 20 74 68 61 74 20 69 73 20 61 6c 72 65 61 64 79   that is already
369b0 0a 2a 2a 20 6f 6e 20 74 68 65 20 6c 69 73 74 20  .** on the list 
369c0 6f 66 20 61 75 74 6f 6d 61 74 69 63 20 65 78 74  of automatic ext
369d0 65 6e 73 69 6f 6e 73 20 69 73 20 61 20 68 61 72  ensions is a har
369e0 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 20 5e 4e 6f  mless no-op. ^No
369f0 20 65 6e 74 72 79 20 70 6f 69 6e 74 0a 2a 2a 20   entry point.** 
36a00 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 6d  will be called m
36a10 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 66 6f  ore than once fo
36a20 72 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  r each database 
36a30 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
36a40 69 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a  is opened..**.**
36a50 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
36a60 74 65 33 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65  te3_reset_auto_e
36a70 78 74 65 6e 73 69 6f 6e 28 29 5d 2e 0a 2a 2f 0a  xtension()]..*/.
36a80 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 75 74 6f  int sqlite3_auto
36a90 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64 20  _extension(void 
36aa0 28 2a 78 45 6e 74 72 79 50 6f 69 6e 74 29 28 76  (*xEntryPoint)(v
36ab0 6f 69 64 29 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid));../*.** CA
36ac0 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 75  PI3REF: Reset Au
36ad0 74 6f 6d 61 74 69 63 20 45 78 74 65 6e 73 69 6f  tomatic Extensio
36ae0 6e 20 4c 6f 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20  n Loading.**.** 
36af0 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20  ^This interface 
36b00 64 69 73 61 62 6c 65 73 20 61 6c 6c 20 61 75 74  disables all aut
36b10 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e  omatic extension
36b20 73 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20  s previously.** 
36b30 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67  registered using
36b40 20 5b 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65   [sqlite3_auto_e
36b50 78 74 65 6e 73 69 6f 6e 28 29 5d 2e 0a 2a 2f 0a  xtension()]..*/.
36b60 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
36b70 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f  et_auto_extensio
36b80 6e 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20  n(void);../*.** 
36b90 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f  The interface to
36ba0 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62   the virtual-tab
36bb0 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 69 73 20  le mechanism is 
36bc0 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64  currently consid
36bd0 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78  ered.** to be ex
36be0 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65  perimental.  The
36bf0 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74   interface might
36c00 20 63 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d   change in incom
36c10 70 61 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a  patible ways..**
36c20 20 49 66 20 74 68 69 73 20 69 73 20 61 20 70 72   If this is a pr
36c30 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64  oblem for you, d
36c40 6f 20 6e 6f 74 20 75 73 65 20 74 68 65 20 69 6e  o not use the in
36c50 74 65 72 66 61 63 65 20 61 74 20 74 68 69 73 20  terface at this 
36c60 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  time..**.** When
36c70 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62   the virtual-tab
36c80 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 73 74 61  le mechanism sta
36c90 62 69 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c  bilizes, we will
36ca0 20 64 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20   declare the.** 
36cb0 69 6e 74 65 72 66 61 63 65 20 66 69 78 65 64 2c  interface fixed,
36cc0 20 73 75 70 70 6f 72 74 20 69 74 20 69 6e 64 65   support it inde
36cd0 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72 65  finitely, and re
36ce0 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e  move this commen
36cf0 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74 72  t..*/../*.** Str
36d00 75 63 74 75 72 65 73 20 75 73 65 64 20 62 79 20  uctures used by 
36d10 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  the virtual tabl
36d20 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2f 0a 74  e interface.*/.t
36d30 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
36d40 6c 69 74 65 33 5f 76 74 61 62 20 73 71 6c 69 74  lite3_vtab sqlit
36d50 65 33 5f 76 74 61 62 3b 0a 74 79 70 65 64 65 66  e3_vtab;.typedef
36d60 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
36d70 69 6e 64 65 78 5f 69 6e 66 6f 20 73 71 6c 69 74  index_info sqlit
36d80 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 3b 0a 74  e3_index_info;.t
36d90 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
36da0 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
36db0 72 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  r sqlite3_vtab_c
36dc0 75 72 73 6f 72 3b 0a 74 79 70 65 64 65 66 20 73  ursor;.typedef s
36dd0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f  truct sqlite3_mo
36de0 64 75 6c 65 20 73 71 6c 69 74 65 33 5f 6d 6f 64  dule sqlite3_mod
36df0 75 6c 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ule;../*.** CAPI
36e00 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61  3REF: Virtual Ta
36e10 62 6c 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45  ble Object.** KE
36e20 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f  YWORDS: sqlite3_
36e30 6d 6f 64 75 6c 65 20 7b 76 69 72 74 75 61 6c 20  module {virtual 
36e40 74 61 62 6c 65 20 6d 6f 64 75 6c 65 7d 0a 2a 2a  table module}.**
36e50 0a 2a 2a 20 54 68 69 73 20 73 74 72 75 63 74 75  .** This structu
36e60 72 65 2c 20 73 6f 6d 65 74 69 6d 65 73 20 63 61  re, sometimes ca
36e70 6c 6c 65 64 20 61 20 22 76 69 72 74 75 61 6c 20  lled a "virtual 
36e80 74 61 62 6c 65 20 6d 6f 64 75 6c 65 22 2c 20 0a  table module", .
36e90 2a 2a 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ** defines the i
36ea0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
36eb0 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c   a [virtual tabl
36ec0 65 73 5d 2e 20 20 0a 2a 2a 20 54 68 69 73 20 73  es].  .** This s
36ed0 74 72 75 63 74 75 72 65 20 63 6f 6e 73 69 73 74  tructure consist
36ee0 73 20 6d 6f 73 74 6c 79 20 6f 66 20 6d 65 74 68  s mostly of meth
36ef0 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75  ods for the modu
36f00 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 76 69 72  le..**.** ^A vir
36f10 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c  tual table modul
36f20 65 20 69 73 20 63 72 65 61 74 65 64 20 62 79 20  e is created by 
36f30 66 69 6c 6c 69 6e 67 20 69 6e 20 61 20 70 65 72  filling in a per
36f40 73 69 73 74 65 6e 74 0a 2a 2a 20 69 6e 73 74 61  sistent.** insta
36f50 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74 72 75  nce of this stru
36f60 63 74 75 72 65 20 61 6e 64 20 70 61 73 73 69 6e  cture and passin
36f70 67 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  g a pointer to t
36f80 68 61 74 20 69 6e 73 74 61 6e 63 65 0a 2a 2a 20  hat instance.** 
36f90 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  to [sqlite3_crea
36fa0 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 6f 72 20  te_module()] or 
36fb0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
36fc0 6d 6f 64 75 6c 65 5f 76 32 28 29 5d 2e 0a 2a 2a  module_v2()]..**
36fd0 20 5e 54 68 65 20 72 65 67 69 73 74 72 61 74 69   ^The registrati
36fe0 6f 6e 20 72 65 6d 61 69 6e 73 20 76 61 6c 69 64  on remains valid
36ff0 20 75 6e 74 69 6c 20 69 74 20 69 73 20 72 65 70   until it is rep
37000 6c 61 63 65 64 20 62 79 20 61 20 64 69 66 66 65  laced by a diffe
37010 72 65 6e 74 0a 2a 2a 20 6d 6f 64 75 6c 65 20 6f  rent.** module o
37020 72 20 75 6e 74 69 6c 20 74 68 65 20 5b 64 61 74  r until the [dat
37030 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
37040 5d 20 63 6c 6f 73 65 73 2e 20 20 54 68 65 20 63  ] closes.  The c
37050 6f 6e 74 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 69  ontent.** of thi
37060 73 20 73 74 72 75 63 74 75 72 65 20 6d 75 73 74  s structure must
37070 20 6e 6f 74 20 63 68 61 6e 67 65 20 77 68 69 6c   not change whil
37080 65 20 69 74 20 69 73 20 72 65 67 69 73 74 65 72  e it is register
37090 65 64 20 77 69 74 68 0a 2a 2a 20 61 6e 79 20 64  ed with.** any d
370a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
370b0 6f 6e 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71  on..*/.struct sq
370c0 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20  lite3_module {. 
370d0 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20   int iVersion;. 
370e0 20 69 6e 74 20 28 2a 78 43 72 65 61 74 65 29 28   int (*xCreate)(
370f0 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a  sqlite3*, void *
37100 70 41 75 78 2c 0a 20 20 20 20 20 20 20 20 20 20  pAux,.          
37110 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20 63       int argc, c
37120 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e 73 74  onst char *const
37130 2a 61 72 67 76 2c 0a 20 20 20 20 20 20 20 20 20  *argv,.         
37140 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 76 74        sqlite3_vt
37150 61 62 20 2a 2a 70 70 56 54 61 62 2c 20 63 68 61  ab **ppVTab, cha
37160 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  r**);.  int (*xC
37170 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74 65 33 2a  onnect)(sqlite3*
37180 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20  , void *pAux,.  
37190 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74               int
371a0 20 61 72 67 63 2c 20 63 6f 6e 73 74 20 63 68 61   argc, const cha
371b0 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20  r *const*argv,. 
371c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 73 71                sq
371d0 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a 70 70 56  lite3_vtab **ppV
371e0 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20  Tab, char**);.  
371f0 69 6e 74 20 28 2a 78 42 65 73 74 49 6e 64 65 78  int (*xBestIndex
37200 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
37210 70 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 69  pVTab, sqlite3_i
37220 6e 64 65 78 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69  ndex_info*);.  i
37230 6e 74 20 28 2a 78 44 69 73 63 6f 6e 6e 65 63 74  nt (*xDisconnect
37240 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
37250 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a  pVTab);.  int (*
37260 78 44 65 73 74 72 6f 79 29 28 73 71 6c 69 74 65  xDestroy)(sqlite
37270 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a  3_vtab *pVTab);.
37280 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73    int (*xOpen)(s
37290 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
372a0 61 62 2c 20 73 71 6c 69 74 65 33 5f 76 74 61 62  ab, sqlite3_vtab
372b0 5f 63 75 72 73 6f 72 20 2a 2a 70 70 43 75 72 73  _cursor **ppCurs
372c0 6f 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c  or);.  int (*xCl
372d0 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ose)(sqlite3_vta
372e0 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e  b_cursor*);.  in
372f0 74 20 28 2a 78 46 69 6c 74 65 72 29 28 73 71 6c  t (*xFilter)(sql
37300 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
37310 2a 2c 20 69 6e 74 20 69 64 78 4e 75 6d 2c 20 63  *, int idxNum, c
37320 6f 6e 73 74 20 63 68 61 72 20 2a 69 64 78 53 74  onst char *idxSt
37330 72 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  r,.             
37340 20 20 20 69 6e 74 20 61 72 67 63 2c 20 73 71 6c     int argc, sql
37350 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 61 72 67  ite3_value **arg
37360 76 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4e 65 78  v);.  int (*xNex
37370 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  t)(sqlite3_vtab_
37380 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20  cursor*);.  int 
37390 28 2a 78 45 6f 66 29 28 73 71 6c 69 74 65 33 5f  (*xEof)(sqlite3_
373a0 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20  vtab_cursor*);. 
373b0 20 69 6e 74 20 28 2a 78 43 6f 6c 75 6d 6e 29 28   int (*xColumn)(
373c0 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
373d0 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 63 6f  sor*, sqlite3_co
373e0 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 20 20  ntext*, int);.  
373f0 69 6e 74 20 28 2a 78 52 6f 77 69 64 29 28 73 71  int (*xRowid)(sq
37400 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
37410 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  r*, sqlite3_int6
37420 34 20 2a 70 52 6f 77 69 64 29 3b 0a 20 20 69 6e  4 *pRowid);.  in
37430 74 20 28 2a 78 55 70 64 61 74 65 29 28 73 71 6c  t (*xUpdate)(sql
37440 69 74 65 33 5f 76 74 61 62 20 2a 2c 20 69 6e 74  ite3_vtab *, int
37450 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  , sqlite3_value 
37460 2a 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  **, sqlite3_int6
37470 34 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42  4 *);.  int (*xB
37480 65 67 69 6e 29 28 73 71 6c 69 74 65 33 5f 76 74  egin)(sqlite3_vt
37490 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e  ab *pVTab);.  in
374a0 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74  t (*xSync)(sqlit
374b0 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b  e3_vtab *pVTab);
374c0 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6d 6d 69 74  .  int (*xCommit
374d0 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
374e0 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a  pVTab);.  int (*
374f0 78 52 6f 6c 6c 62 61 63 6b 29 28 73 71 6c 69 74  xRollback)(sqlit
37500 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b  e3_vtab *pVTab);
37510 0a 20 20 69 6e 74 20 28 2a 78 46 69 6e 64 46 75  .  int (*xFindFu
37520 6e 63 74 69 6f 6e 29 28 73 71 6c 69 74 65 33 5f  nction)(sqlite3_
37530 76 74 61 62 20 2a 70 56 74 61 62 2c 20 69 6e 74  vtab *pVtab, int
37540 20 6e 41 72 67 2c 20 63 6f 6e 73 74 20 63 68 61   nArg, const cha
37550 72 20 2a 7a 4e 61 6d 65 2c 0a 20 20 20 20 20 20  r *zName,.      
37560 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
37570 20 76 6f 69 64 20 28 2a 2a 70 78 46 75 6e 63 29   void (**pxFunc)
37580 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
37590 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
375a0 6c 75 65 2a 2a 29 2c 0a 20 20 20 20 20 20 20 20  lue**),.        
375b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76                 v
375c0 6f 69 64 20 2a 2a 70 70 41 72 67 29 3b 0a 20 20  oid **ppArg);.  
375d0 69 6e 74 20 28 2a 78 52 65 6e 61 6d 65 29 28 73  int (*xRename)(s
375e0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74  qlite3_vtab *pVt
375f0 61 62 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ab, const char *
37600 7a 4e 65 77 29 3b 0a 20 20 2f 2a 20 54 68 65 20  zNew);.  /* The 
37610 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  methods above ar
37620 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f  e in version 1 o
37630 66 20 74 68 65 20 73 71 6c 69 74 65 5f 6d 6f 64  f the sqlite_mod
37640 75 6c 65 20 6f 62 6a 65 63 74 2e 20 54 68 6f 73  ule object. Thos
37650 65 20 0a 20 20 2a 2a 20 62 65 6c 6f 77 20 61 72  e .  ** below ar
37660 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 32 20  e for version 2 
37670 61 6e 64 20 67 72 65 61 74 65 72 2e 20 2a 2f 0a  and greater. */.
37680 20 20 69 6e 74 20 28 2a 78 53 61 76 65 70 6f 69    int (*xSavepoi
37690 6e 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  nt)(sqlite3_vtab
376a0 20 2a 70 56 54 61 62 2c 20 69 6e 74 29 3b 0a 20   *pVTab, int);. 
376b0 20 69 6e 74 20 28 2a 78 52 65 6c 65 61 73 65 29   int (*xRelease)
376c0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
376d0 56 54 61 62 2c 20 69 6e 74 29 3b 0a 20 20 69 6e  VTab, int);.  in
376e0 74 20 28 2a 78 52 6f 6c 6c 62 61 63 6b 54 6f 29  t (*xRollbackTo)
376f0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
37700 56 54 61 62 2c 20 69 6e 74 29 3b 0a 7d 3b 0a 0a  VTab, int);.};..
37710 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
37720 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6e  Virtual Table In
37730 64 65 78 69 6e 67 20 49 6e 66 6f 72 6d 61 74 69  dexing Informati
37740 6f 6e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  on.** KEYWORDS: 
37750 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e  sqlite3_index_in
37760 66 6f 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  fo.**.** The sql
37770 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20  ite3_index_info 
37780 73 74 72 75 63 74 75 72 65 20 61 6e 64 20 69 74  structure and it
37790 73 20 73 75 62 73 74 72 75 63 74 75 72 65 73 20  s substructures 
377a0 69 73 20 75 73 65 64 20 61 73 20 70 61 72 74 0a  is used as part.
377b0 2a 2a 20 6f 66 20 74 68 65 20 5b 76 69 72 74 75  ** of the [virtu
377c0 61 6c 20 74 61 62 6c 65 5d 20 69 6e 74 65 72 66  al table] interf
377d0 61 63 65 20 74 6f 0a 2a 2a 20 70 61 73 73 20 69  ace to.** pass i
377e0 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 6e 74 6f 20  nformation into 
377f0 61 6e 64 20 72 65 63 65 69 76 65 20 74 68 65 20  and receive the 
37800 72 65 70 6c 79 20 66 72 6f 6d 20 74 68 65 20 5b  reply from the [
37810 78 42 65 73 74 49 6e 64 65 78 5d 0a 2a 2a 20 6d  xBestIndex].** m
37820 65 74 68 6f 64 20 6f 66 20 61 20 5b 76 69 72 74  ethod of a [virt
37830 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65  ual table module
37840 5d 2e 20 20 54 68 65 20 66 69 65 6c 64 73 20 75  ].  The fields u
37850 6e 64 65 72 20 2a 2a 49 6e 70 75 74 73 2a 2a 20  nder **Inputs** 
37860 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74  are the.** input
37870 73 20 74 6f 20 78 42 65 73 74 49 6e 64 65 78 20  s to xBestIndex 
37880 61 6e 64 20 61 72 65 20 72 65 61 64 2d 6f 6e 6c  and are read-onl
37890 79 2e 20 20 78 42 65 73 74 49 6e 64 65 78 20 69  y.  xBestIndex i
378a0 6e 73 65 72 74 73 20 69 74 73 0a 2a 2a 20 72 65  nserts its.** re
378b0 73 75 6c 74 73 20 69 6e 74 6f 20 74 68 65 20 2a  sults into the *
378c0 2a 4f 75 74 70 75 74 73 2a 2a 20 66 69 65 6c 64  *Outputs** field
378d0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61  s..**.** ^(The a
378e0 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72 72  Constraint[] arr
378f0 61 79 20 72 65 63 6f 72 64 73 20 57 48 45 52 45  ay records WHERE
37900 20 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69   clause constrai
37910 6e 74 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 3a  nts of the form:
37920 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
37930 74 65 3e 63 6f 6c 75 6d 6e 20 4f 50 20 65 78 70  te>column OP exp
37940 72 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  r</blockquote>.*
37950 2a 0a 2a 2a 20 77 68 65 72 65 20 4f 50 20 69 73  *.** where OP is
37960 20 3d 2c 20 26 6c 74 3b 2c 20 26 6c 74 3b 3d 2c   =, &lt;, &lt;=,
37970 20 26 67 74 3b 2c 20 6f 72 20 26 67 74 3b 3d 2e   &gt;, or &gt;=.
37980 29 5e 20 20 5e 28 54 68 65 20 70 61 72 74 69 63  )^  ^(The partic
37990 75 6c 61 72 20 6f 70 65 72 61 74 6f 72 20 69 73  ular operator is
379a0 0a 2a 2a 20 73 74 6f 72 65 64 20 69 6e 20 61 43  .** stored in aC
379b0 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 6f 70 20 75  onstraint[].op u
379c0 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 0a  sing one of the.
379d0 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 44 45 58  ** [SQLITE_INDEX
379e0 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 45 51 20 7c  _CONSTRAINT_EQ |
379f0 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f   SQLITE_INDEX_CO
37a00 4e 53 54 52 41 49 4e 54 5f 20 76 61 6c 75 65 73  NSTRAINT_ values
37a10 5d 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65 20 69 6e  ].)^.** ^(The in
37a20 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  dex of the colum
37a30 6e 20 69 73 20 73 74 6f 72 65 64 20 69 6e 0a 2a  n is stored in.*
37a40 2a 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e  * aConstraint[].
37a50 69 43 6f 6c 75 6d 6e 2e 29 5e 20 20 5e 28 61 43  iColumn.)^  ^(aC
37a60 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 75 73 61 62  onstraint[].usab
37a70 6c 65 20 69 73 20 54 52 55 45 20 69 66 20 74 68  le is TRUE if th
37a80 65 0a 2a 2a 20 65 78 70 72 20 6f 6e 20 74 68 65  e.** expr on the
37a90 20 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65   right-hand side
37aa0 20 63 61 6e 20 62 65 20 65 76 61 6c 75 61 74 65   can be evaluate
37ab0 64 20 28 61 6e 64 20 74 68 75 73 20 74 68 65 20  d (and thus the 
37ac0 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 69 73  constraint.** is
37ad0 20 75 73 61 62 6c 65 29 20 61 6e 64 20 66 61 6c   usable) and fal
37ae0 73 65 20 69 66 20 69 74 20 63 61 6e 6e 6f 74 2e  se if it cannot.
37af0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 70  )^.**.** ^The op
37b00 74 69 6d 69 7a 65 72 20 61 75 74 6f 6d 61 74 69  timizer automati
37b10 63 61 6c 6c 79 20 69 6e 76 65 72 74 73 20 74 65  cally inverts te
37b20 72 6d 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  rms of the form 
37b30 22 65 78 70 72 20 4f 50 20 63 6f 6c 75 6d 6e 22  "expr OP column"
37b40 0a 2a 2a 20 61 6e 64 20 6d 61 6b 65 73 20 6f 74  .** and makes ot
37b50 68 65 72 20 73 69 6d 70 6c 69 66 69 63 61 74 69  her simplificati
37b60 6f 6e 73 20 74 6f 20 74 68 65 20 57 48 45 52 45  ons to the WHERE
37b70 20 63 6c 61 75 73 65 20 69 6e 20 61 6e 20 61 74   clause in an at
37b80 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 67 65 74 20  tempt to.** get 
37b90 61 73 20 6d 61 6e 79 20 57 48 45 52 45 20 63 6c  as many WHERE cl
37ba0 61 75 73 65 20 74 65 72 6d 73 20 69 6e 74 6f 20  ause terms into 
37bb0 74 68 65 20 66 6f 72 6d 20 73 68 6f 77 6e 20 61  the form shown a
37bc0 62 6f 76 65 20 61 73 20 70 6f 73 73 69 62 6c 65  bove as possible
37bd0 2e 0a 2a 2a 20 5e 54 68 65 20 61 43 6f 6e 73 74  ..** ^The aConst
37be0 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 6f 6e  raint[] array on
37bf0 6c 79 20 72 65 70 6f 72 74 73 20 57 48 45 52 45  ly reports WHERE
37c00 20 63 6c 61 75 73 65 20 74 65 72 6d 73 20 74 68   clause terms th
37c10 61 74 20 61 72 65 0a 2a 2a 20 72 65 6c 65 76 61  at are.** releva
37c20 6e 74 20 74 6f 20 74 68 65 20 70 61 72 74 69 63  nt to the partic
37c30 75 6c 61 72 20 76 69 72 74 75 61 6c 20 74 61 62  ular virtual tab
37c40 6c 65 20 62 65 69 6e 67 20 71 75 65 72 69 65 64  le being queried
37c50 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 66 6f 72 6d 61  ..**.** ^Informa
37c60 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4f  tion about the O
37c70 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 69  RDER BY clause i
37c80 73 20 73 74 6f 72 65 64 20 69 6e 20 61 4f 72 64  s stored in aOrd
37c90 65 72 42 79 5b 5d 2e 0a 2a 2a 20 5e 45 61 63 68  erBy[]..** ^Each
37ca0 20 74 65 72 6d 20 6f 66 20 61 4f 72 64 65 72 42   term of aOrderB
37cb0 79 20 72 65 63 6f 72 64 73 20 61 20 63 6f 6c 75  y records a colu
37cc0 6d 6e 20 6f 66 20 74 68 65 20 4f 52 44 45 52 20  mn of the ORDER 
37cd0 42 59 20 63 6c 61 75 73 65 2e 0a 2a 2a 0a 2a 2a  BY clause..**.**
37ce0 20 54 68 65 20 5b 78 42 65 73 74 49 6e 64 65 78   The [xBestIndex
37cf0 5d 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 66 69  ] method must fi
37d00 6c 6c 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73  ll aConstraintUs
37d10 61 67 65 5b 5d 20 77 69 74 68 20 69 6e 66 6f 72  age[] with infor
37d20 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20  mation.** about 
37d30 77 68 61 74 20 70 61 72 61 6d 65 74 65 72 73 20  what parameters 
37d40 74 6f 20 70 61 73 73 20 74 6f 20 78 46 69 6c 74  to pass to xFilt
37d50 65 72 2e 20 20 5e 49 66 20 61 72 67 76 49 6e 64  er.  ^If argvInd
37d60 65 78 3e 30 20 74 68 65 6e 0a 2a 2a 20 74 68 65  ex>0 then.** the
37d70 20 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65   right-hand side
37d80 20 6f 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f   of the correspo
37d90 6e 64 69 6e 67 20 61 43 6f 6e 73 74 72 61 69 6e  nding aConstrain
37da0 74 5b 5d 20 69 73 20 65 76 61 6c 75 61 74 65 64  t[] is evaluated
37db0 0a 2a 2a 20 61 6e 64 20 62 65 63 6f 6d 65 73 20  .** and becomes 
37dc0 74 68 65 20 61 72 67 76 49 6e 64 65 78 2d 74 68  the argvIndex-th
37dd0 20 65 6e 74 72 79 20 69 6e 20 61 72 67 76 2e 20   entry in argv. 
37de0 20 5e 28 49 66 20 61 43 6f 6e 73 74 72 61 69 6e   ^(If aConstrain
37df0 74 55 73 61 67 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a  tUsage[].omit.**
37e00 20 69 73 20 74 72 75 65 2c 20 74 68 65 6e 20 74   is true, then t
37e10 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73  he constraint is
37e20 20 61 73 73 75 6d 65 64 20 74 6f 20 62 65 20 66   assumed to be f
37e30 75 6c 6c 79 20 68 61 6e 64 6c 65 64 20 62 79 20  ully handled by 
37e40 74 68 65 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74  the.** virtual t
37e50 61 62 6c 65 20 61 6e 64 20 69 73 20 6e 6f 74 20  able and is not 
37e60 63 68 65 63 6b 65 64 20 61 67 61 69 6e 20 62 79  checked again by
37e70 20 53 51 4c 69 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a   SQLite.)^.**.**
37e80 20 5e 54 68 65 20 69 64 78 4e 75 6d 20 61 6e 64   ^The idxNum and
37e90 20 69 64 78 50 74 72 20 76 61 6c 75 65 73 20 61   idxPtr values a
37ea0 72 65 20 72 65 63 6f 72 64 65 64 20 61 6e 64 20  re recorded and 
37eb0 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 0a  passed into the.
37ec0 2a 2a 20 5b 78 46 69 6c 74 65 72 5d 20 6d 65 74  ** [xFilter] met
37ed0 68 6f 64 2e 0a 2a 2a 20 5e 5b 73 71 6c 69 74 65  hod..** ^[sqlite
37ee0 33 5f 66 72 65 65 28 29 5d 20 69 73 20 75 73 65  3_free()] is use
37ef0 64 20 74 6f 20 66 72 65 65 20 69 64 78 50 74 72  d to free idxPtr
37f00 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a   if and only if.
37f10 2a 2a 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78  ** needToFreeIdx
37f20 50 74 72 20 69 73 20 74 72 75 65 2e 0a 2a 2a 0a  Ptr is true..**.
37f30 2a 2a 20 5e 54 68 65 20 6f 72 64 65 72 42 79 43  ** ^The orderByC
37f40 6f 6e 73 75 6d 65 64 20 6d 65 61 6e 73 20 74 68  onsumed means th
37f50 61 74 20 6f 75 74 70 75 74 20 66 72 6f 6d 20 5b  at output from [
37f60 78 46 69 6c 74 65 72 5d 2f 5b 78 4e 65 78 74 5d  xFilter]/[xNext]
37f70 20 77 69 6c 6c 20 6f 63 63 75 72 20 69 6e 0a 2a   will occur in.*
37f80 2a 20 74 68 65 20 63 6f 72 72 65 63 74 20 6f 72  * the correct or
37f90 64 65 72 20 74 6f 20 73 61 74 69 73 66 79 20 74  der to satisfy t
37fa0 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75  he ORDER BY clau
37fb0 73 65 20 73 6f 20 74 68 61 74 20 6e 6f 20 73 65  se so that no se
37fc0 70 61 72 61 74 65 0a 2a 2a 20 73 6f 72 74 69 6e  parate.** sortin
37fd0 67 20 73 74 65 70 20 69 73 20 72 65 71 75 69 72  g step is requir
37fe0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 65  ed..**.** ^The e
37ff0 73 74 69 6d 61 74 65 64 43 6f 73 74 20 76 61 6c  stimatedCost val
38000 75 65 20 69 73 20 61 6e 20 65 73 74 69 6d 61 74  ue is an estimat
38010 65 20 6f 66 20 74 68 65 20 63 6f 73 74 20 6f 66  e of the cost of
38020 20 64 6f 69 6e 67 20 74 68 65 0a 2a 2a 20 70 61   doing the.** pa
38030 72 74 69 63 75 6c 61 72 20 6c 6f 6f 6b 75 70 2e  rticular lookup.
38040 20 20 41 20 66 75 6c 6c 20 73 63 61 6e 20 6f 66    A full scan of
38050 20 61 20 74 61 62 6c 65 20 77 69 74 68 20 4e 20   a table with N 
38060 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68  entries should h
38070 61 76 65 0a 2a 2a 20 61 20 63 6f 73 74 20 6f 66  ave.** a cost of
38080 20 4e 2e 20 20 41 20 62 69 6e 61 72 79 20 73 65   N.  A binary se
38090 61 72 63 68 20 6f 66 20 61 20 74 61 62 6c 65 20  arch of a table 
380a0 6f 66 20 4e 20 65 6e 74 72 69 65 73 20 73 68 6f  of N entries sho
380b0 75 6c 64 20 68 61 76 65 20 61 0a 2a 2a 20 63 6f  uld have a.** co
380c0 73 74 20 6f 66 20 61 70 70 72 6f 78 69 6d 61 74  st of approximat
380d0 65 6c 79 20 6c 6f 67 28 4e 29 2e 0a 2a 2f 0a 73  ely log(N)..*/.s
380e0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e  truct sqlite3_in
380f0 64 65 78 5f 69 6e 66 6f 20 7b 0a 20 20 2f 2a 20  dex_info {.  /* 
38100 49 6e 70 75 74 73 20 2a 2f 0a 20 20 69 6e 74 20  Inputs */.  int 
38110 6e 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20  nConstraint;    
38120 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
38130 20 6f 66 20 65 6e 74 72 69 65 73 20 69 6e 20 61   of entries in a
38140 43 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20  Constraint */.  
38150 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
38160 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74 20  ndex_constraint 
38170 7b 0a 20 20 20 20 20 69 6e 74 20 69 43 6f 6c 75  {.     int iColu
38180 6d 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  mn;             
38190 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6f 6e 20 6c 65   /* Column on le
381a0 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20  ft-hand side of 
381b0 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20  constraint */.  
381c0 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72     unsigned char
381d0 20 6f 70 3b 20 20 20 20 20 20 20 20 20 2f 2a 20   op;         /* 
381e0 43 6f 6e 73 74 72 61 69 6e 74 20 6f 70 65 72 61  Constraint opera
381f0 74 6f 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69  tor */.     unsi
38200 67 6e 65 64 20 63 68 61 72 20 75 73 61 62 6c 65  gned char usable
38210 3b 20 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66  ;     /* True if
38220 20 74 68 69 73 20 63 6f 6e 73 74 72 61 69 6e 74   this constraint
38230 20 69 73 20 75 73 61 62 6c 65 20 2a 2f 0a 20 20   is usable */.  
38240 20 20 20 69 6e 74 20 69 54 65 72 6d 4f 66 66 73     int iTermOffs
38250 65 74 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  et;          /* 
38260 55 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  Used internally 
38270 2d 20 78 42 65 73 74 49 6e 64 65 78 20 73 68 6f  - xBestIndex sho
38280 75 6c 64 20 69 67 6e 6f 72 65 20 2a 2f 0a 20 20  uld ignore */.  
38290 7d 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74 3b 20  } *aConstraint; 
382a0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 54 61             /* Ta
382b0 62 6c 65 20 6f 66 20 57 48 45 52 45 20 63 6c 61  ble of WHERE cla
382c0 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20  use constraints 
382d0 2a 2f 0a 20 20 69 6e 74 20 6e 4f 72 64 65 72 42  */.  int nOrderB
382e0 79 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  y;              
382f0 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 74 65 72  /* Number of ter
38300 6d 73 20 69 6e 20 74 68 65 20 4f 52 44 45 52 20  ms in the ORDER 
38310 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a 20 20 73  BY clause */.  s
38320 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e  truct sqlite3_in
38330 64 65 78 5f 6f 72 64 65 72 62 79 20 7b 0a 20 20  dex_orderby {.  
38340 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20     int iColumn; 
38350 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
38360 43 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 20 2a 2f  Column number */
38370 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63  .     unsigned c
38380 68 61 72 20 64 65 73 63 3b 20 20 20 20 20 20 20  har desc;       
38390 2f 2a 20 54 72 75 65 20 66 6f 72 20 44 45 53 43  /* True for DESC
383a0 2e 20 20 46 61 6c 73 65 20 66 6f 72 20 41 53 43  .  False for ASC
383b0 2e 20 2a 2f 0a 20 20 7d 20 2a 61 4f 72 64 65 72  . */.  } *aOrder
383c0 42 79 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  By;             
383d0 20 20 2f 2a 20 54 68 65 20 4f 52 44 45 52 20 42    /* The ORDER B
383e0 59 20 63 6c 61 75 73 65 20 2a 2f 0a 20 20 2f 2a  Y clause */.  /*
383f0 20 4f 75 74 70 75 74 73 20 2a 2f 0a 20 20 73 74   Outputs */.  st
38400 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64  ruct sqlite3_ind
38410 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74 5f 75 73  ex_constraint_us
38420 61 67 65 20 7b 0a 20 20 20 20 69 6e 74 20 61 72  age {.    int ar
38430 67 76 49 6e 64 65 78 3b 20 20 20 20 20 20 20 20  gvIndex;        
38440 20 20 20 2f 2a 20 69 66 20 3e 30 2c 20 63 6f 6e     /* if >0, con
38450 73 74 72 61 69 6e 74 20 69 73 20 70 61 72 74 20  straint is part 
38460 6f 66 20 61 72 67 76 20 74 6f 20 78 46 69 6c 74  of argv to xFilt
38470 65 72 20 2a 2f 0a 20 20 20 20 75 6e 73 69 67 6e  er */.    unsign
38480 65 64 20 63 68 61 72 20 6f 6d 69 74 3b 20 20 20  ed char omit;   
38490 20 20 20 2f 2a 20 44 6f 20 6e 6f 74 20 63 6f 64     /* Do not cod
384a0 65 20 61 20 74 65 73 74 20 66 6f 72 20 74 68 69  e a test for thi
384b0 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a  s constraint */.
384c0 20 20 7d 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74    } *aConstraint
384d0 55 73 61 67 65 3b 0a 20 20 69 6e 74 20 69 64 78  Usage;.  int idx
384e0 4e 75 6d 3b 20 20 20 20 20 20 20 20 20 20 20 20  Num;            
384f0 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 75 73      /* Number us
38500 65 64 20 74 6f 20 69 64 65 6e 74 69 66 79 20 74  ed to identify t
38510 68 65 20 69 6e 64 65 78 20 2a 2f 0a 20 20 63 68  he index */.  ch
38520 61 72 20 2a 69 64 78 53 74 72 3b 20 20 20 20 20  ar *idxStr;     
38530 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 69           /* Stri
38540 6e 67 2c 20 70 6f 73 73 69 62 6c 79 20 6f 62 74  ng, possibly obt
38550 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74  ained from sqlit
38560 65 33 5f 6d 61 6c 6c 6f 63 20 2a 2f 0a 20 20 69  e3_malloc */.  i
38570 6e 74 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78  nt needToFreeIdx
38580 53 74 72 3b 20 20 20 20 20 20 2f 2a 20 46 72 65  Str;      /* Fre
38590 65 20 69 64 78 53 74 72 20 75 73 69 6e 67 20 73  e idxStr using s
385a0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 66  qlite3_free() if
385b0 20 74 72 75 65 20 2a 2f 0a 20 20 69 6e 74 20 6f   true */.  int o
385c0 72 64 65 72 42 79 43 6f 6e 73 75 6d 65 64 3b 20  rderByConsumed; 
385d0 20 20 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66        /* True if
385e0 20 6f 75 74 70 75 74 20 69 73 20 61 6c 72 65 61   output is alrea
385f0 64 79 20 6f 72 64 65 72 65 64 20 2a 2f 0a 20 20  dy ordered */.  
38600 64 6f 75 62 6c 65 20 65 73 74 69 6d 61 74 65 64  double estimated
38610 43 6f 73 74 3b 20 20 20 20 20 20 2f 2a 20 45 73  Cost;      /* Es
38620 74 69 6d 61 74 65 64 20 63 6f 73 74 20 6f 66 20  timated cost of 
38630 75 73 69 6e 67 20 74 68 69 73 20 69 6e 64 65 78  using this index
38640 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
38650 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20  PI3REF: Virtual 
38660 54 61 62 6c 65 20 43 6f 6e 73 74 72 61 69 6e 74  Table Constraint
38670 20 4f 70 65 72 61 74 6f 72 20 43 6f 64 65 73 0a   Operator Codes.
38680 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63 72  **.** These macr
38690 6f 73 20 64 65 66 69 6e 65 64 20 74 68 65 20 61  os defined the a
386a0 6c 6c 6f 77 65 64 20 76 61 6c 75 65 73 20 66 6f  llowed values fo
386b0 72 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  r the.** [sqlite
386c0 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 5d 2e 61 43  3_index_info].aC
386d0 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 6f 70 20 66  onstraint[].op f
386e0 69 65 6c 64 2e 20 20 45 61 63 68 20 76 61 6c 75  ield.  Each valu
386f0 65 20 72 65 70 72 65 73 65 6e 74 73 0a 2a 2a 20  e represents.** 
38700 61 6e 20 6f 70 65 72 61 74 6f 72 20 74 68 61 74  an operator that
38710 20 69 73 20 70 61 72 74 20 6f 66 20 61 20 63 6f   is part of a co
38720 6e 73 74 72 61 69 6e 74 20 74 65 72 6d 20 69 6e  nstraint term in
38730 20 74 68 65 20 77 48 45 52 45 20 63 6c 61 75 73   the wHERE claus
38740 65 20 6f 66 0a 2a 2a 20 61 20 71 75 65 72 79 20  e of.** a query 
38750 74 68 61 74 20 75 73 65 73 20 61 20 5b 76 69 72  that uses a [vir
38760 74 75 61 6c 20 74 61 62 6c 65 5d 2e 0a 2a 2f 0a  tual table]..*/.
38770 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
38780 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  NDEX_CONSTRAINT_
38790 45 51 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20  EQ    2.#define 
387a0 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e  SQLITE_INDEX_CON
387b0 53 54 52 41 49 4e 54 5f 47 54 20 20 20 20 34 0a  STRAINT_GT    4.
387c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
387d0 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  NDEX_CONSTRAINT_
387e0 4c 45 20 20 20 20 38 0a 23 64 65 66 69 6e