/ Hex Artifact Content
Login

Artifact 7cf6485b8a5cd88139e9d05c2a73368dd79863af:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
07d0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
07e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
07f0: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0800: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0810: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0820: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0830: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0840: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0850: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0860: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
0870: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
0880: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
0890: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08a0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08b0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08c0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
08d0: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
08e0: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
08f0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0900: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0910: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0920: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0930: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0940: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0950: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0960: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
0970: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
0980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0990: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09b0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09c0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
09d0: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
09e0: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
09f0: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a00: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a20: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a30: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a40: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a50: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a60: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0a70: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0a80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0a90: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0aa0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ab0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0ac0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0ad0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0ae0: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0af0: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b00: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b10: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b20: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b30: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b40: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b50: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b60: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0b70: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0b80: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0b90: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0ba0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0bb0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bc0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0bd0: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0be0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0bf0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c00: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c20: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c30: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c40: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c50: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c60: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0c70: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0c80: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0c90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0ca0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0cb0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cc0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0cd0: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0ce0: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0cf0: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d00: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d10: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d20: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d30: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d40: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d50: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d60: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0d70: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0d80: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0d90: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0da0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0db0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0dc0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0dd0: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0de0: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0df0: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e00: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e10: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e20: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e30: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e40: 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a  ro evaluates to.
0e50: 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  ** a string whic
0e60: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70  h identifies a p
0e70: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d  articular check-
0e80: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  in of SQLite.** 
0e90: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69  within its confi
0ea0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
0eb0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68  ent system.  ^Th
0ec0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
0ed0: 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ID.** string con
0ee0: 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61  tains the date a
0ef0: 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63  nd time of the c
0f00: 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e  heck-in (UTC) an
0f10: 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73  d an SHA1.** has
0f20: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
0f30: 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a  source tree..**.
0f40: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
0f50: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
0f60: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
0f70: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
0f80: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  er()], [sqlite3_
0f90: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20  sourceid()],.** 
0fa0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
0fb0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
0fc0: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
0fd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
0fe0: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d  ERSION        "-
0ff0: 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65  -VERS--".#define
1000: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
1010: 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e  NUMBER --VERSION
1020: 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e  -NUMBER--.#defin
1030: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
1040: 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43  ID      "--SOURC
1050: 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43  E-ID--"../*.** C
1060: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1070: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
1080: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59  n Numbers.** KEY
1090: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
10a0: 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f  ersion, sqlite3_
10b0: 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54  sourceid.**.** T
10c0: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
10d0: 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65  provide the same
10e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20   information as 
10f0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  the [SQLITE_VERS
1100: 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  ION],.** [SQLITE
1110: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d  _VERSION_NUMBER]
1120: 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f  , and [SQLITE_SO
1130: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72  URCE_ID] C prepr
1140: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a  ocessor macros.*
1150: 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69  * but are associ
1160: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69  ated with the li
1170: 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66  brary instead of
1180: 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65   the header file
1190: 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a  .  ^(Cautious.**
11a0: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
11b0: 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72  ht include asser
11c0: 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69  t() statements i
11d0: 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74  n their applicat
11e0: 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79  ion to.** verify
11f0: 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74   that values ret
1200: 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69  urned by these i
1210: 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20  nterfaces match 
1220: 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a  the macros in.**
1230: 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64   the header, and
1240: 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61   thus insure tha
1250: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
1260: 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  n is.** compiled
1270: 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c   with matching l
1280: 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65  ibrary and heade
1290: 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c  r files..**.** <
12a0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
12b0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69  .** assert( sqli
12c0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
12d0: 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f  umber()==SQLITE_
12e0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29  VERSION_NUMBER )
12f0: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72  ;.** assert( str
1300: 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72  cmp(sqlite3_sour
1310: 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f  ceid(),SQLITE_SO
1320: 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a  URCE_ID)==0 );.*
1330: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70  * assert( strcmp
1340: 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  (sqlite3_libvers
1350: 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52  ion(),SQLITE_VER
1360: 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c  SION)==0 );.** <
1370: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1380: 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1390: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
13a0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
13b0: 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74  t contains the t
13c0: 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56  ext of [SQLITE_V
13d0: 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f  ERSION].** macro
13e0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
13f0: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e  libversion() fun
1400: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20  ction returns a 
1410: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
1420: 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  * to the sqlite3
1430: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
1440: 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65  g constant.  The
1450: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1460: 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f  ion().** functio
1470: 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f  n is provided fo
1480: 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69  r use in DLLs si
1490: 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73  nce DLL users us
14a0: 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76  ually do not hav
14b0: 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65  e.** direct acce
14c0: 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e  ss to string con
14d0: 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68  stants within th
14e0: 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20  e DLL.  ^The.** 
14f0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1500: 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63  on_number() func
1510: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20  tion returns an 
1520: 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f  integer equal to
1530: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
1540: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54  ION_NUMBER].  ^T
1550: 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  he sqlite3_sourc
1560: 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  eid() function r
1570: 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69  eturns .** a poi
1580: 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67  nter to a string
1590: 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20   constant whose 
15a0: 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d  value is the sam
15b0: 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51  e as the .** [SQ
15c0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20  LITE_SOURCE_ID] 
15d0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
15e0: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  acro..**.** See 
15f0: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65  also: [sqlite_ve
1600: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
1610: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
1620: 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54  ]..*/.SQLITE_EXT
1630: 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73  ERN const char s
1640: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
1650: 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
1660: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1670: 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68  (void);.const ch
1680: 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72  ar *sqlite3_sour
1690: 63 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20  ceid(void);.int 
16a0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
16b0: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b  on_number(void);
16c0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16d0: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61  : Run-Time Libra
16e0: 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f  ry Compilation O
16f0: 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69  ptions Diagnosti
1700: 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  cs.**.** ^The sq
1710: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1720: 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74  ion_used() funct
1730: 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72  ion returns 0 or
1740: 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e   1 .** indicatin
1750: 67 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70  g whether the sp
1760: 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77  ecified option w
1770: 61 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a  as defined at .*
1780: 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  * compile time. 
1790: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72   ^The SQLITE_ pr
17a0: 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74  efix may be omit
17b0: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a  ted from the .**
17c0: 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73   option name pas
17d0: 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  sed to sqlite3_c
17e0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
17f0: 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  d().  .**.** ^Th
1800: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  e sqlite3_compil
1810: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75  eoption_get() fu
1820: 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74  nction allows it
1830: 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20  erating.** over 
1840: 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69  the list of opti
1850: 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65  ons that were de
1860: 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  fined at compile
1870: 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75   time by.** retu
1880: 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63  rning the N-th c
1890: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69  ompile time opti
18a0: 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20  on string.  ^If 
18b0: 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
18c0: 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  e,.** sqlite3_co
18d0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
18e0: 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
18f0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
1900: 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66  SQLITE_ .** pref
1910: 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  ix is omitted fr
1920: 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72  om any strings r
1930: 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73  eturned by .** s
1940: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1950: 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a  tion_get()..**.*
1960: 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74  * ^Support for t
1970: 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75  he diagnostic fu
1980: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f  nctions sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
19a0: 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ed().** and sqli
19b0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19c0: 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f  n_get() may be o
19d0: 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66  mitted by specif
19e0: 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51  ying the .** [SQ
19f0: 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c  LITE_OMIT_COMPIL
1a00: 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f  EOPTION_DIAGS] o
1a10: 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65  ption at compile
1a20: 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   time..**.** See
1a30: 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74   also: SQL funct
1a40: 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d  ions [sqlite_com
1a50: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1a60: 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
1a70: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
1a80: 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b  get()] and the [
1a90: 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20  compile_options 
1aa0: 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e  pragma]..*/.#ifn
1ab0: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
1ac0: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49  COMPILEOPTION_DI
1ad0: 41 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  AGS.int sqlite3_
1ae0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
1af0: 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  ed(const char *z
1b00: 4f 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20  OptName);.const 
1b10: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
1b20: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1b30: 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a  int N);.#endif..
1b40: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b50: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
1b60: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68  he Library Is Th
1b70: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e  readsafe.**.** ^
1b80: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65  The sqlite3_thre
1b90: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
1ba0: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69  n returns zero i
1bb0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
1bc0: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70   SQLite was comp
1bd0: 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69  iled with mutexi
1be0: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20  ng code omitted 
1bf0: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53  due to the.** [S
1c00: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1c10: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
1c20: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20  ption being set 
1c30: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  to 0..**.** SQLi
1c40: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c  te can be compil
1c50: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f  ed with or witho
1c60: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65  ut mutexes.  Whe
1c70: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  n.** the [SQLITE
1c80: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70  _THREADSAFE] C p
1c90: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
1ca0: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74  o is 1 or 2, mut
1cb0: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
1cc0: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69  led and SQLite i
1cd0: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57  s threadsafe.  W
1ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  hen the.** [SQLI
1cf0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
1d00: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74  acro is 0, .** t
1d10: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f  he mutexes are o
1d20: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74  mitted.  Without
1d30: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74   the mutexes, it
1d40: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20   is not safe.** 
1d50: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f  to use SQLite co
1d60: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20  ncurrently from 
1d70: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68  more than one th
1d80: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62  read..**.** Enab
1d90: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63  ling mutexes inc
1da0: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65  urs a measurable
1db0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e   performance pen
1dc0: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73  alty..** So if s
1dd0: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73  peed is of utmos
1de0: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74  t importance, it
1df0: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20   makes sense to 
1e00: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d  disable.** the m
1e10: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72  utexes.  But for
1e20: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c   maximum safety,
1e30: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20   mutexes should 
1e40: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e  be enabled..** ^
1e50: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  The default beha
1e60: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65  vior is for mute
1e70: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65  xes to be enable
1e80: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  d..**.** This in
1e90: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
1ea0: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63  sed by an applic
1eb0: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75  ation to make su
1ec0: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76  re that the.** v
1ed0: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
1ee0: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b   that it is link
1ef0: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20  ing against was 
1f00: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
1f10: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74   the desired set
1f20: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c  ting of the [SQL
1f30: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
1f40: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  macro..**.** Thi
1f50: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79  s interface only
1f60: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20   reports on the 
1f70: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74  compile-time mut
1f80: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66  ex setting.** of
1f90: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
1fa0: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20  EADSAFE] flag.  
1fb0: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
1fc0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51  piled with.** SQ
1fd0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
1fe0: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74  1 or =2 then mut
1ff0: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
2000: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
2010: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
2020: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
2030: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
2040: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
2050: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
2060: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
2070: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
2080: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
2090: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
20a0: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
20b0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
20c0: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e  ].  ^(The return
20d0: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a   value of the.**
20e0: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
20f0: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73  afe() function s
2100: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f  hows only the co
2110: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69  mpile-time setti
2120: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20  ng of.** thread 
2130: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20  safety, not any 
2140: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73  run-time changes
2150: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67   to that setting
2160: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69   made by.** sqli
2170: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e  te3_config(). In
2180: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2190: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
21a0: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65  rom sqlite3_thre
21b0: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75  adsafe().** is u
21c0: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c  nchanged by call
21d0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  s to sqlite3_con
21e0: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  fig().)^.**.** S
21f0: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
2200: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
2210: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
2220: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
2230: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2240: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64  _threadsafe(void
2250: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2260: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
2270: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a  nection Handle.*
2280: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74  * KEYWORDS: {dat
2290: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22a0: 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  } {database conn
22b0: 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45  ections}.**.** E
22c0: 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20  ach open SQLite 
22d0: 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72  database is repr
22e0: 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69  esented by a poi
22f0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
2300: 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70  nce of.** the op
2310: 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e  aque structure n
2320: 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20  amed "sqlite3". 
2330: 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f   It is useful to
2340: 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c   think of an sql
2350: 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ite3.** pointer 
2360: 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54  as an object.  T
2370: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
2380: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
2390: 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  en16()], and.** 
23a0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
23b0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61  ()] interfaces a
23c0: 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74  re its construct
23d0: 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ors, and [sqlite
23e0: 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e  3_close()].** an
23f0: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
2400: 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73 20 64  _v2()] are its d
2410: 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65  estructors.  The
2420: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
2430: 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  r.** interfaces 
2440: 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c  (such as.** [sql
2450: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2460: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
2470: 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c  ate_function()],
2480: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2490: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
24a0: 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72   to name but thr
24b0: 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74  ee) that are met
24c0: 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71  hods on an.** sq
24d0: 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f  lite3 object..*/
24e0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
24f0: 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b  sqlite3 sqlite3;
2500: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2510: 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72  : 64-Bit Integer
2520: 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Types.** KEYWOR
2530: 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  DS: sqlite_int64
2540: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a   sqlite_uint64.*
2550: 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
2560: 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70  re is no cross-p
2570: 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73  latform way to s
2580: 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e  pecify 64-bit in
2590: 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53  teger types.** S
25a0: 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74  QLite includes t
25b0: 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62  ypedefs for 64-b
25c0: 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e  it signed and un
25d0: 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e  signed integers.
25e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
25f0: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  e3_int64 and sql
2600: 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20  ite3_uint64 are 
2610: 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 79  the preferred ty
2620: 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a  pe definitions..
2630: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e  ** The sqlite_in
2640: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2650: 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 20  int64 types are 
2660: 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61  supported for ba
2670: 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61  ckwards.** compa
2680: 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a  tibility only..*
2690: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
26a0: 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  3_int64 and sqli
26b0: 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63  te_int64 types c
26c0: 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72  an store integer
26d0: 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65   values.** betwe
26e0: 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 35  en -922337203685
26f0: 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32  4775808 and +922
2700: 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30 37  3372036854775807
2710: 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68   inclusive.  ^Th
2720: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e  e.** sqlite3_uin
2730: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2740: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
2750: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
2760: 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e  lues .** between
2770: 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34   0 and +18446744
2780: 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 63  073709551615 inc
2790: 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65  lusive..*/.#ifde
27a0: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
27b0: 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51  YPE.  typedef SQ
27c0: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
27d0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20  sqlite_int64;.  
27e0: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64  typedef unsigned
27f0: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
2800: 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  PE sqlite_uint64
2810: 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28  ;.#elif defined(
2820: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66  _MSC_VER) || def
2830: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
2840: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69  _).  typedef __i
2850: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36  nt64 sqlite_int6
2860: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2870: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71  igned __int64 sq
2880: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
2890: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e  se.  typedef lon
28a0: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
28b0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
28c0: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67  ef unsigned long
28d0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
28e0: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a  _uint64;.#endif.
28f0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69  typedef sqlite_i
2900: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74  nt64 sqlite3_int
2910: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69  64;.typedef sqli
2920: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  te_uint64 sqlite
2930: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a  3_uint64;../*.**
2940: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f   If compiling fo
2950: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68  r a processor th
2960: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e  at lacks floatin
2970: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c  g point support,
2980: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69  .** substitute i
2990: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74  nteger for float
29a0: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69  ing-point..*/.#i
29b0: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
29c0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
29d0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
29e0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
29f0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2a00: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
2a10: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2a20: 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ion.**.** ^The s
2a30: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61  qlite3_close() a
2a40: 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nd sqlite3_close
2a50: 5f 76 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61  _v2() routines a
2a60: 72 65 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a  re destructors.*
2a70: 2a 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  * for the [sqlit
2a80: 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e  e3] object..** ^
2a90: 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
2aa0: 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c  _close() and sql
2ab0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
2ac0: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
2ad0: 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69   if.** the [sqli
2ae0: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73  te3] object is s
2af0: 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74  uccessfully dest
2b00: 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73  royed and all as
2b10: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f  sociated.** reso
2b20: 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f  urces are deallo
2b30: 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  cated..**.** ^If
2b40: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2b50: 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f  nnection is asso
2b60: 63 69 61 74 65 64 20 77 69 74 68 20 75 6e 66 69  ciated with unfi
2b70: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64  nalized prepared
2b80: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  .** statements o
2b90: 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c  r unfinished sql
2ba0: 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65  ite3_backup obje
2bb0: 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33  cts then sqlite3
2bc0: 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c  _close().** will
2bd0: 20 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 62   leave the datab
2be0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
2bf0: 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  pen and return [
2c00: 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a  SQLITE_BUSY]..**
2c10: 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f   ^If sqlite3_clo
2c20: 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65  se_v2() is calle
2c30: 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a  d with unfinaliz
2c40: 65 64 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ed prepared stat
2c50: 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 20 75 6e  ements.** and un
2c60: 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33  finished sqlite3
2c70: 5f 62 61 63 6b 75 70 73 2c 20 74 68 65 6e 20 74  _backups, then t
2c80: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2c90: 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a  ection becomes.*
2ca0: 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a  * an unusable "z
2cb0: 6f 6d 62 69 65 22 20 77 68 69 63 68 20 77 69 6c  ombie" which wil
2cc0: 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  l automatically 
2cd0: 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 77  be deallocated w
2ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20  hen the.** last 
2cf0: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d00: 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 20  nt is finalized 
2d10: 6f 72 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69  or the last sqli
2d20: 74 65 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a  te3_backup is.**
2d30: 20 66 69 6e 69 73 68 65 64 2e 20 20 54 68 65 20   finished.  The 
2d40: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
2d50: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
2d60: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
2d70: 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61   with.** host la
2d80: 6e 67 75 61 67 65 73 20 74 68 61 74 20 61 72 65  nguages that are
2d90: 20 67 61 72 62 61 67 65 20 63 6f 6c 6c 65 63 74   garbage collect
2da0: 65 64 2c 20 61 6e 64 20 77 68 65 72 65 20 74 68  ed, and where th
2db0: 65 20 6f 72 64 65 72 20 69 6e 20 77 68 69 63 68  e order in which
2dc0: 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 73 20  .** destructors 
2dd0: 61 72 65 20 63 61 6c 6c 65 64 20 69 73 20 61 72  are called is ar
2de0: 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41  bitrary..**.** A
2df0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
2e00: 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ld [sqlite3_fina
2e10: 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d  lize | finalize]
2e20: 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73   all [prepared s
2e30: 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b  tatements],.** [
2e40: 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
2e50: 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20  se | close] all 
2e60: 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20  [BLOB handles], 
2e70: 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  and .** [sqlite3
2e80: 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c  _backup_finish |
2e90: 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71   finish] all [sq
2ea0: 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62  lite3_backup] ob
2eb0: 6a 65 63 74 73 20 61 73 73 6f 63 69 61 74 65 64  jects associated
2ec0: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73 71  .** with the [sq
2ed0: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72  lite3] object pr
2ee0: 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e  ior to attemptin
2ef0: 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f  g to close the o
2f00: 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73  bject.  ^If.** s
2f10: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 69  qlite3_close() i
2f20: 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64  s called on a [d
2f30: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2f40: 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68  on] that still h
2f50: 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e  as.** outstandin
2f60: 67 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  g [prepared stat
2f70: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68  ements], [BLOB h
2f80: 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a  andles], and/or.
2f90: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b  ** [sqlite3_back
2fa0: 75 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e  up] objects then
2fb0: 20 69 74 20 72 65 74 75 72 6e 73 20 53 51 4c 49   it returns SQLI
2fc0: 54 45 5f 4f 4b 20 62 75 74 20 74 68 65 20 64 65  TE_OK but the de
2fd0: 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66  allocation.** of
2fe0: 20 72 65 73 6f 75 72 63 65 73 20 69 73 20 64 65   resources is de
2ff0: 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c 6c  ferred until all
3000: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
3010: 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61  ments], [BLOB ha
3020: 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20 5b  ndles],.** and [
3030: 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20  sqlite3_backup] 
3040: 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73 6f  objects are also
3050: 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a 2a   destroyed..**.*
3060: 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74 65  * ^If an [sqlite
3070: 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65 73  3] object is des
3080: 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20 74  troyed while a t
3090: 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f 70  ransaction is op
30a0: 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73  en,.** the trans
30b0: 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61  action is automa
30c0: 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62  tically rolled b
30d0: 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43  ack..**.** The C
30e0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
30f0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d  qlite3_close(C)]
3100: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c   and [sqlite3_cl
3110: 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d 75  ose_v2(C)].** mu
3120: 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e  st be either a N
3130: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f  ULL.** pointer o
3140: 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f  r an [sqlite3] o
3150: 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62  bject pointer ob
3160: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
3170: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
3180: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
3190: 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
31a0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
31b0: 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73  and not previous
31c0: 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43  ly closed..** ^C
31d0: 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  alling sqlite3_c
31e0: 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74 65  lose() or sqlite
31f0: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69 74  3_close_v2() wit
3200: 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
3210: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20  .** argument is 
3220: 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  a harmless no-op
3230: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
3240: 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a 29  _close(sqlite3*)
3250: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c  ;.int sqlite3_cl
3260: 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33 2a 29  ose_v2(sqlite3*)
3270: 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70  ;../*.** The typ
3280: 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b  e for a callback
3290: 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68   function..** Th
32a0: 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e 64  is is legacy and
32b0: 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49 74   deprecated.  It
32c0: 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f 72   is included for
32d0: 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63   historical.** c
32e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e 64  ompatibility and
32f0: 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74   is not document
3300: 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69  ed..*/.typedef i
3310: 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c  nt (*sqlite3_cal
3320: 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74  lback)(void*,int
3330: 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29  ,char**, char**)
3340: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
3350: 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65 72  F: One-Step Quer
3360: 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74 65  y Execution Inte
3370: 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rface.**.** The 
3380: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3390: 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63 6f  nterface is a co
33a0: 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70 65  nvenience wrappe
33b0: 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c  r around.** [sql
33c0: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
33d0: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  )], [sqlite3_ste
33e0: 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  p()], and [sqlit
33f0: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a  e3_finalize()],.
3400: 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 61  ** that allows a
3410: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f  n application to
3420: 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73 74   run multiple st
3430: 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c 0a  atements of SQL.
3440: 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e  ** without havin
3450: 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20 6f  g to use a lot o
3460: 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a  f C code. .**.**
3470: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
3480: 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ec() interface r
3490: 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  uns zero or more
34a0: 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a   UTF-8 encoded,.
34b0: 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70  ** semicolon-sep
34c0: 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65 6d  arate SQL statem
34d0: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f  ents passed into
34e0: 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e   its 2nd argumen
34f0: 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f 6e  t,.** in the con
3500: 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61 74  text of the [dat
3510: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3520: 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 69  ] passed in as i
3530: 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d 65  ts 1st.** argume
3540: 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c  nt.  ^If the cal
3550: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6f  lback function o
3560: 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d 65  f the 3rd argume
3570: 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  nt to.** sqlite3
3580: 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e  _exec() is not N
3590: 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73 20  ULL, then it is 
35a0: 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63 68  invoked for each
35b0: 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 63   result row.** c
35c0: 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68 65  oming out of the
35d0: 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20 73   evaluated SQL s
35e0: 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65  tatements.  ^The
35f0: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
3600: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3610: 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68  () is relayed th
3620: 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74  rough to the 1st
3630: 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63   argument of eac
3640: 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e  h.** callback in
3650: 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74  vocation.  ^If t
3660: 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e  he callback poin
3670: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3680: 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c  xec().** is NULL
3690: 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61  , then no callba
36a0: 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b  ck is ever invok
36b0: 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f  ed and result ro
36c0: 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65  ws are.** ignore
36d0: 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20  d..**.** ^If an 
36e0: 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69  error occurs whi
36f0: 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68  le evaluating th
3700: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
3710: 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20   passed into.** 
3720: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20  sqlite3_exec(), 
3730: 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f  then execution o
3740: 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74  f the current st
3750: 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e  atement stops an
3760: 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20  d.** subsequent 
3770: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73  statements are s
3780: 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65  kipped.  ^If the
3790: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
37a0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
37b0: 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  .** is not NULL 
37c0: 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d  then any error m
37d0: 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65  essage is writte
37e0: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
37f0: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
3800: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
3810: 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63  ] and passed bac
3820: 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74  k through the 5t
3830: 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  h parameter..** 
3840: 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20  To avoid memory 
3850: 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69  leaks, the appli
3860: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e  cation should in
3870: 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72  voke [sqlite3_fr
3880: 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f  ee()].** on erro
3890: 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
38a0: 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75  s returned throu
38b0: 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d  gh the 5th param
38c0: 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71  eter of.** of sq
38d0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 74  lite3_exec() aft
38e0: 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  er the error mes
38f0: 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e  sage string is n
3900: 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e  o longer needed.
3910: 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20  .** ^If the 5th 
3920: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
3930: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e  ite3_exec() is n
3940: 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65  ot NULL and no e
3950: 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20  rrors.** occur, 
3960: 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  then sqlite3_exe
3970: 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f 69  c() sets the poi
3980: 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 20  nter in its 5th 
3990: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
39a0: 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75  NULL before retu
39b0: 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  rning..**.** ^If
39c0: 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63   an sqlite3_exec
39d0: 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  () callback retu
39e0: 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
39f0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3a00: 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
3a10: 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54  rns SQLITE_ABORT
3a20: 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e   without invokin
3a30: 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61  g the callback a
3a40: 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68  gain and.** with
3a50: 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20  out running any 
3a60: 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73  subsequent SQL s
3a70: 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
3a80: 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65   ^The 2nd argume
3a90: 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
3aa0: 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63  3_exec() callbac
3ab0: 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68  k function is th
3ac0: 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63  e.** number of c
3ad0: 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
3ae0: 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20  sult.  ^The 3rd 
3af0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
3b00: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a  sqlite3_exec().*
3b10: 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  * callback is an
3b20: 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
3b30: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62  rs to strings ob
3b40: 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f  tained as if fro
3b50: 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  m.** [sqlite3_co
3b60: 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e  lumn_text()], on
3b70: 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d  e for each colum
3b80: 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65  n.  ^If an eleme
3b90: 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c  nt of a.** resul
3ba0: 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68  t row is NULL th
3bb0: 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  en the correspon
3bc0: 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e  ding string poin
3bd0: 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73  ter for the.** s
3be0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61  qlite3_exec() ca
3bf0: 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c  llback is a NULL
3c00: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
3c10: 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  4th argument to 
3c20: 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65  the.** sqlite3_e
3c30: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69  xec() callback i
3c40: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
3c50: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67  inters to string
3c60: 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20  s where each.** 
3c70: 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 73  entry represents
3c80: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72   the name of cor
3c90: 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c  responding resul
3ca0: 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61  t column as obta
3cb0: 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  ined.** from [sq
3cc0: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
3cd0: 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  e()]..**.** ^If 
3ce0: 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
3cf0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
3d00: 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  c() is a NULL po
3d10: 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72  inter, a pointer
3d20: 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20  .** to an empty 
3d30: 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69  string, or a poi
3d40: 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69  nter that contai
3d50: 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61  ns only whitespa
3d60: 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51  ce and/or .** SQ
3d70: 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e  L comments, then
3d80: 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   no SQL statemen
3d90: 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64  ts are evaluated
3da0: 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73   and the databas
3db0: 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e  e.** is not chan
3dc0: 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72  ged..**.** Restr
3dd0: 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ictions:.**.** <
3de0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  ul>.** <li> The 
3df0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
3e00: 20 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   insure that the
3e10: 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74   1st parameter t
3e20: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
3e30: 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 61  .**      is a va
3e40: 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61  lid and open [da
3e50: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
3e60: 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  n]..** <li> The 
3e70: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
3e80: 20 6e 6f 74 20 63 6c 6f 73 65 20 5b 64 61 74 61   not close [data
3e90: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
3ea0: 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a   specified by.**
3eb0: 20 20 20 20 20 20 74 68 65 20 31 73 74 20 70 61        the 1st pa
3ec0: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
3ed0: 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20  e3_exec() while 
3ee0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3ef0: 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c  s running..** <l
3f00: 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  i> The applicati
3f10: 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69  on must not modi
3f20: 66 79 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  fy the SQL state
3f30: 6d 65 6e 74 20 74 65 78 74 20 70 61 73 73 65 64  ment text passed
3f40: 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68   into.**      th
3f50: 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
3f60: 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  of sqlite3_exec(
3f70: 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f  ) while sqlite3_
3f80: 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e  exec() is runnin
3f90: 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69  g..** </ul>.*/.i
3fa0: 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  nt sqlite3_exec(
3fb0: 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20  .  sqlite3*,    
3fc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
3fe0: 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
3ff0: 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
4000: 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20  r *sql,         
4010: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4020: 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65    /* SQL to be e
4030: 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e  valuated */.  in
4040: 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f  t (*callback)(vo
4050: 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63  id*,int,char**,c
4060: 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c  har**),  /* Call
4070: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f  back function */
4080: 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20  .  void *,      
4090: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
40b0: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f   1st argument to
40c0: 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63   callback */.  c
40d0: 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20  har **errmsg    
40e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40f0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72            /* Err
4100: 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68  or msg written h
4110: 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  ere */.);../*.**
4120: 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c   CAPI3REF: Resul
4130: 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f  t Codes.** KEYWO
4140: 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 7b  RDS: SQLITE_OK {
4150: 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72 72  error code} {err
4160: 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59  or codes}.** KEY
4170: 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63  WORDS: {result c
4180: 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f 64  ode} {result cod
4190: 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53  es}.**.** Many S
41a0: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20  QLite functions 
41b0: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65  return an intege
41c0: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72  r result code fr
41d0: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e  om the set shown
41e0: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65  .** here in orde
41f0: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75  r to indicate su
4200: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
4210: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
4220: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
4230: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
4240: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4250: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
4260: 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  o: [SQLITE_IOERR
4270: 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64  _READ | extended
4280: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2c 0a   result codes],.
4290: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62  ** [sqlite3_vtab
42a0: 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20  _on_conflict()] 
42b0: 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b  [SQLITE_ROLLBACK
42c0: 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d   | result codes]
42d0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
42e0: 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20  ITE_OK          
42f0: 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66   0   /* Successf
4300: 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20  ul result */./* 
4310: 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72  beginning-of-err
4320: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66  or-codes */.#def
4330: 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52  ine SQLITE_ERROR
4340: 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53          1   /* S
4350: 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73  QL error or miss
4360: 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  ing database */.
4370: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4380: 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20  NTERNAL     2   
4390: 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69  /* Internal logi
43a0: 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74  c error in SQLit
43b0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
43c0: 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20 20  ITE_PERM        
43d0: 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70   3   /* Access p
43e0: 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64  ermission denied
43f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4400: 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20 20  TE_ABORT        
4410: 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20  4   /* Callback 
4420: 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74 65  routine requeste
4430: 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64  d an abort */.#d
4440: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
4450: 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f 2a  Y         5   /*
4460: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66 69   The database fi
4470: 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a  le is locked */.
4480: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
4490: 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20 20  OCKED       6   
44a0: 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74 68  /* A table in th
44b0: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f  e database is lo
44c0: 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  cked */.#define 
44d0: 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20  SQLITE_NOMEM    
44e0: 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c      7   /* A mal
44f0: 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a  loc() failed */.
4500: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
4510: 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 20  EADONLY     8   
4520: 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77 72  /* Attempt to wr
4530: 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 64  ite a readonly d
4540: 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69  atabase */.#defi
4550: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  ne SQLITE_INTERR
4560: 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f 70  UPT    9   /* Op
4570: 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74  eration terminat
4580: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ed by sqlite3_in
4590: 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 66  terrupt()*/.#def
45a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
45b0: 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 53         10   /* S
45c0: 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b  ome kind of disk
45d0: 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 72   I/O error occur
45e0: 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  red */.#define S
45f0: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20 20  QLITE_CORRUPT   
4600: 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64 61    11   /* The da
4610: 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61 67  tabase disk imag
4620: 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a  e is malformed *
4630: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4640: 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 20  _NOTFOUND    12 
4650: 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63    /* Unknown opc
4660: 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33 5f 66  ode in sqlite3_f
4670: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f  ile_control() */
4680: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4690: 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20  FULL        13  
46a0: 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61   /* Insertion fa
46b0: 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 74  iled because dat
46c0: 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f  abase is full */
46d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
46e0: 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20  CANTOPEN    14  
46f0: 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70   /* Unable to op
4700: 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
4710: 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  file */.#define 
4720: 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20  SQLITE_PROTOCOL 
4730: 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74 61 62     15   /* Datab
4740: 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f  ase lock protoco
4750: 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  l error */.#defi
4760: 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20  ne SQLITE_EMPTY 
4770: 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61        16   /* Da
4780: 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 79 20  tabase is empty 
4790: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
47a0: 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31 37  E_SCHEMA      17
47b0: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
47c0: 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  se schema change
47d0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
47e0: 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20  ITE_TOOBIG      
47f0: 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f  18   /* String o
4800: 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73  r BLOB exceeds s
4810: 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65  ize limit */.#de
4820: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
4830: 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20  TRAINT  19   /* 
4840: 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e  Abort due to con
4850: 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
4860: 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
4870: 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20  ITE_MISMATCH    
4880: 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70  20   /* Data typ
4890: 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64  e mismatch */.#d
48a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53  efine SQLITE_MIS
48b0: 55 53 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a  USE      21   /*
48c0: 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 69 6e   Library used in
48d0: 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65  correctly */.#de
48e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46  fine SQLITE_NOLF
48f0: 53 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20  S       22   /* 
4900: 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 65 73  Uses OS features
4910: 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f   not supported o
4920: 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e  n host */.#defin
4930: 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20  e SQLITE_AUTH   
4940: 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74       23   /* Aut
4950: 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65  horization denie
4960: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4970: 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20  ITE_FORMAT      
4980: 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72  24   /* Auxiliar
4990: 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61  y database forma
49a0: 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  t error */.#defi
49b0: 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20  ne SQLITE_RANGE 
49c0: 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e        25   /* 2n
49d0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
49e0: 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20  qlite3_bind out 
49f0: 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66  of range */.#def
4a00: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44  ine SQLITE_NOTAD
4a10: 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46  B      26   /* F
4a20: 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20  ile opened that 
4a30: 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73  is not a databas
4a40: 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e  e file */.#defin
4a50: 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20  e SQLITE_ROW    
4a60: 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c       100  /* sql
4a70: 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20  ite3_step() has 
4a80: 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64  another row read
4a90: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4aa0: 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20  ITE_DONE        
4ab0: 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  101  /* sqlite3_
4ac0: 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69 73  step() has finis
4ad0: 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f  hed executing */
4ae0: 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72  ./* end-of-error
4af0: 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  -codes */../*.**
4b00: 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e   CAPI3REF: Exten
4b10: 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73  ded Result Codes
4b20: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65  .** KEYWORDS: {e
4b30: 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
4b40: 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65 72  de} {extended er
4b50: 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45  ror codes}.** KE
4b60: 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65  YWORDS: {extende
4b70: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b  d result code} {
4b80: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
4b90: 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  codes}.**.** In 
4ba0: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
4bb0: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
4bc0: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
4bd0: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20  eturn one of 26 
4be0: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49  integer.** [SQLI
4bf0: 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63  TE_OK | result c
4c00: 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c  odes].  However,
4c10: 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73 20   experience has 
4c20: 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79 20  shown that many 
4c30: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73 75  of.** these resu
4c40: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f 6f  lt codes are too
4c50: 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64 2e   coarse-grained.
4c60: 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 72    They do not pr
4c70: 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68  ovide as.** much
4c80: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
4c90: 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 70  ut problems as p
4ca0: 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74  rogrammers might
4cb0: 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66   like.  In an ef
4cc0: 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65  fort to.** addre
4cd0: 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20 76  ss this, newer v
4ce0: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4cf0: 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38  e (version 3.3.8
4d00: 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c   and later) incl
4d10: 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66  ude.** support f
4d20: 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65  or additional re
4d30: 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20  sult codes that 
4d40: 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74  provide more det
4d50: 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f  ailed informatio
4d60: 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72  n.** about error
4d70: 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64 20  s. The extended 
4d80: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4d90: 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
4da0: 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72  bled.** on a per
4db0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
4dc0: 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67  tion basis using
4dd0: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
4de0: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
4df0: 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a  _codes()] API..*
4e00: 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65  *.** Some of the
4e10: 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65 6e   available exten
4e20: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4e30: 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 72 65   are listed here
4e40: 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70  ..** One may exp
4e50: 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ect the number o
4e60: 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  f extended resul
4e70: 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65 20  t codes will be 
4e80: 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74  expand.** over t
4e90: 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20 74  ime.  Software t
4ea0: 68 61 74 20 75 73 65 73 20 65 78 74 65 6e 64 65  hat uses extende
4eb0: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 73  d result codes s
4ec0: 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20  hould expect.** 
4ed0: 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75 6c  to see new resul
4ee0: 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75 72  t codes in futur
4ef0: 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
4f00: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
4f10: 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74  SQLITE_OK result
4f20: 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65 72   code will never
4f30: 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20 49   be extended.  I
4f40: 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a  t will always.**
4f50: 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72 6f   be exactly zero
4f60: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
4f70: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20  ITE_IOERR_READ  
4f80: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4f90: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c  ITE_IOERR | (1<<
4fa0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4fb0: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
4fc0: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  EAD        (SQLI
4fd0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38  TE_IOERR | (2<<8
4fe0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4ff0: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20  E_IOERR_WRITE   
5000: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5010: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29  E_IOERR | (3<<8)
5020: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5030: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20  _IOERR_FSYNC    
5040: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5050: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29  _IOERR | (4<<8))
5060: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5070: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20  IOERR_DIR_FSYNC 
5080: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5090: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a  IOERR | (5<<8)).
50a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
50b0: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20  OERR_TRUNCATE   
50c0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
50d0: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23  OERR | (6<<8)).#
50e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
50f0: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20  ERR_FSTAT       
5100: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5110: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  ERR | (7<<8)).#d
5120: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5130: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  RR_UNLOCK       
5140: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5150: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  RR | (8<<8)).#de
5160: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5170: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_RDLOCK        
5180: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5190: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  R | (9<<8)).#def
51a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
51b0: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
51c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
51d0: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66   | (10<<8)).#def
51e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
51f0: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20  _BLOCKED        
5200: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5210: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66   | (11<<8)).#def
5220: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5230: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20  _NOMEM          
5240: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5250: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66   | (12<<8)).#def
5260: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5270: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20  _ACCESS         
5280: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5290: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66   | (13<<8)).#def
52a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
52b0: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f  _CHECKRESERVEDLO
52c0: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52  CK (SQLITE_IOERR
52d0: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66   | (14<<8)).#def
52e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
52f0: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  _LOCK           
5300: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5310: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66   | (15<<8)).#def
5320: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5330: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20  _CLOSE          
5340: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5350: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66   | (16<<8)).#def
5360: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5370: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20  _DIR_CLOSE      
5380: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5390: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66   | (17<<8)).#def
53a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
53b0: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20  _SHMOPEN        
53c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
53d0: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66   | (18<<8)).#def
53e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
53f0: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20  _SHMSIZE        
5400: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5410: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66   | (19<<8)).#def
5420: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5430: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20  _SHMLOCK        
5440: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5450: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66   | (20<<8)).#def
5460: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5470: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20  _SHMMAP         
5480: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5490: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66   | (21<<8)).#def
54a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54b0: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20  _SEEK           
54c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
54d0: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66   | (22<<8)).#def
54e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54f0: 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20  _DELETE_NOENT   
5500: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5510: 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66   | (23<<8)).#def
5520: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
5530: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  D_SHAREDCACHE   
5540: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
5550: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65  D |  (1<<8)).#de
5560: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
5570: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
5580: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
5590: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64     |  (1<<8)).#d
55a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
55b0: 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20  TOPEN_NOTEMPDIR 
55c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
55d0: 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a  TOPEN | (1<<8)).
55e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
55f0: 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20 20  ANTOPEN_ISDIR   
5600: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
5610: 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29  ANTOPEN | (2<<8)
5620: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5630: 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 41  _CANTOPEN_FULLPA
5640: 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  TH       (SQLITE
5650: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c 3c  _CANTOPEN | (3<<
5660: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5670: 54 45 5f 43 4f 52 52 55 50 54 5f 56 54 41 42 20  TE_CORRUPT_VTAB 
5680: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5690: 54 45 5f 43 4f 52 52 55 50 54 20 7c 20 28 31 3c  TE_CORRUPT | (1<
56a0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
56b0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43  ITE_READONLY_REC
56c0: 4f 56 45 52 59 20 20 20 20 20 20 20 28 53 51 4c  OVERY       (SQL
56d0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
56e0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
56f0: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43  QLITE_READONLY_C
5700: 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20 28 53  ANTLOCK       (S
5710: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c  QLITE_READONLY |
5720: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
5730: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f   SQLITE_ABORT_RO
5740: 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 20 20 20  LLBACK          
5750: 28 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20  (SQLITE_ABORT | 
5760: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
5770: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5780: 54 5f 55 4e 49 51 55 45 20 20 20 20 20 20 20 28  T_UNIQUE       (
5790: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
57a0: 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  T | (1<<8)).#def
57b0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
57c0: 52 41 49 4e 54 5f 52 41 49 53 45 20 20 20 20 20  RAINT_RAISE     
57d0: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
57e0: 52 41 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a  RAINT | (2<<8)).
57f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5800: 4f 4e 53 54 52 41 49 4e 54 5f 46 4f 52 45 49 47  ONSTRAINT_FOREIG
5810: 4e 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43  NKEY   (SQLITE_C
5820: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c  ONSTRAINT | (3<<
5830: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5840: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 48  TE_CONSTRAINT_CH
5850: 45 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c 49  ECK        (SQLI
5860: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5870: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (4<<8)).#define 
5880: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5890: 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20 20 28  T_PRIMARYKEY   (
58a0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
58b0: 54 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66  T | (5<<8)).#def
58c0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
58d0: 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20  RAINT_NOTNULL   
58e0: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
58f0: 52 41 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a  RAINT | (6<<8)).
5900: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5910: 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d 4d 49 54  ONSTRAINT_COMMIT
5920: 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54 45 5f 43  HOOK   (SQLITE_C
5930: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c  ONSTRAINT | (7<<
5940: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5950: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 56 54  TE_CONSTRAINT_VT
5960: 41 42 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  AB         (SQLI
5970: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5980: 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (8<<8)).#define 
5990: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
59a0: 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 28  T_FUNCTION     (
59b0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
59c0: 54 20 7c 20 28 39 3c 3c 38 29 29 0a 0a 2f 2a 0a  T | (9<<8))../*.
59d0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
59e0: 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e  gs For File Open
59f0: 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a   Operations.**.*
5a00: 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 6c 75  * These bit valu
5a10: 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  es are intended 
5a20: 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a  for use in the.*
5a30: 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  * 3rd parameter 
5a40: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
5a50: 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72  open_v2()] inter
5a60: 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74  face and.** in t
5a70: 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
5a80: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
5a90: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
5aa0: 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  od..*/.#define S
5ab0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
5ac0: 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30  NLY         0x00
5ad0: 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f  000001  /* Ok fo
5ae0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5af0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5b00: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
5b10: 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30  RITE        0x00
5b20: 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f  000002  /* Ok fo
5b30: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5b40: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5b50: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
5b60: 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  E           0x00
5b70: 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f  000004  /* Ok fo
5b80: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5b90: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5ba0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
5bb0: 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30  EONCLOSE    0x00
5bc0: 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f  000008  /* VFS o
5bd0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5be0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
5bf0: 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30  SIVE        0x00
5c00: 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f  000010  /* VFS o
5c10: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5c20: 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50  QLITE_OPEN_AUTOP
5c30: 52 4f 58 59 20 20 20 20 20 20 20 20 30 78 30 30  ROXY        0x00
5c40: 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f  000020  /* VFS o
5c50: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5c60: 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20  QLITE_OPEN_URI  
5c70: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
5c80: 30 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f  000040  /* Ok fo
5c90: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5ca0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5cb0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52  QLITE_OPEN_MEMOR
5cc0: 59 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  Y           0x00
5cd0: 30 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f  000080  /* Ok fo
5ce0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5cf0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5d00: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
5d10: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
5d20: 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f  000100  /* VFS o
5d30: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5d40: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
5d50: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
5d60: 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f  000200  /* VFS o
5d70: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5d80: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53  QLITE_OPEN_TRANS
5d90: 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30  IENT_DB     0x00
5da0: 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f  000400  /* VFS o
5db0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5dc0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
5dd0: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
5de0: 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f  000800  /* VFS o
5df0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5e00: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
5e10: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
5e20: 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  001000  /* VFS o
5e30: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5e40: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
5e50: 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30  URNAL       0x00
5e60: 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  002000  /* VFS o
5e70: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5e80: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
5e90: 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30  R_JOURNAL   0x00
5ea0: 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  004000  /* VFS o
5eb0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5ec0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
5ed0: 45 58 20 20 20 20 20 20 20 20 20 20 30 78 30 30  EX          0x00
5ee0: 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  008000  /* Ok fo
5ef0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5f00: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5f10: 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
5f20: 55 54 45 58 20 20 20 20 20 20 20 20 30 78 30 30  UTEX        0x00
5f30: 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  010000  /* Ok fo
5f40: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5f50: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5f60: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
5f70: 44 43 41 43 48 45 20 20 20 20 20 20 30 78 30 30  DCACHE      0x00
5f80: 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  020000  /* Ok fo
5f90: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5fa0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5fb0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
5fc0: 54 45 43 41 43 48 45 20 20 20 20 20 30 78 30 30  TECACHE     0x00
5fd0: 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  040000  /* Ok fo
5fe0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5ff0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6000: 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20  QLITE_OPEN_WAL  
6010: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6020: 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  080000  /* VFS o
6030: 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72  nly */../* Reser
6040: 76 65 64 3a 20 20 20 20 20 20 20 20 20 20 20 20  ved:            
6050: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6060: 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a  0F00000 */../*.*
6070: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69  * CAPI3REF: Devi
6080: 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69  ce Characteristi
6090: 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65  cs.**.** The xDe
60a0: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
60b0: 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  ics method of th
60c0: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
60d0: 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74  thods].** object
60e0: 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65   returns an inte
60f0: 67 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76  ger which is a v
6100: 65 63 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a  ector of these.*
6110: 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70  * bit values exp
6120: 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72  ressing I/O char
6130: 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74  acteristics of t
6140: 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a  he mass storage.
6150: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68  ** device that h
6160: 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68  olds the file th
6170: 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  at the [sqlite3_
6180: 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72  io_methods].** r
6190: 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20  efers to..**.** 
61a0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
61b0: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
61c0: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
61d0: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
61e0: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
61f0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
6200: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
6210: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
6220: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
6230: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
6240: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
6250: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
6260: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
6270: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
6280: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
6290: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
62a0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
62b0: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
62c0: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
62d0: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
62e0: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
62f0: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
6300: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
6310: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
6320: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
6330: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
6340: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
6350: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
6360: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
6370: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
6380: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
6390: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
63a0: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
63b0: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
63c0: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
63d0: 69 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49  ite().  The SQLI
63e0: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41  TE_IOCAP_POWERSA
63f0: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f  FE_OVERWRITE pro
6400: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
6410: 0a 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74  .** after reboot
6420: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61   following a cra
6430: 73 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73  sh or power loss
6440: 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73  , the only bytes
6450: 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68   in a.** file th
6460: 61 74 20 77 65 72 65 20 77 72 69 74 74 65 6e 20  at were written 
6470: 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  at the applicati
6480: 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68  on level might h
6490: 61 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61  ave changed.** a
64a0: 6e 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74  nd that adjacent
64b0: 20 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74   bytes, even byt
64c0: 65 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61  es within the sa
64d0: 6d 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a  me sector are.**
64e0: 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62   guaranteed to b
64f0: 65 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2f 0a  e unchanged..*/.
6500: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6510: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20  OCAP_ATOMIC     
6520: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6530: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53  000001.#define S
6540: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6550: 49 43 35 31 32 20 20 20 20 20 20 20 20 20 20 20  IC512           
6560: 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64     0x00000002.#d
6570: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6580: 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20  AP_ATOMIC1K     
6590: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
65a0: 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c  0004.#define SQL
65b0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
65c0: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  2K              
65d0: 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66   0x00000008.#def
65e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
65f0: 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20  _ATOMIC4K       
6600: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6610: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
6620: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b  E_IOCAP_ATOMIC8K
6630: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
6640: 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e  x00000020.#defin
6650: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6660: 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20  TOMIC16K        
6670: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
6680: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6690: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20  IOCAP_ATOMIC32K 
66a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
66b0: 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20  0000080.#define 
66c0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
66d0: 4d 49 43 36 34 4b 20 20 20 20 20 20 20 20 20 20  MIC64K          
66e0: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23      0x00000100.#
66f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6700: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
6710: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6720: 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00200.#define SQ
6730: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
6740: 4e 54 49 41 4c 20 20 20 20 20 20 20 20 20 20 20  NTIAL           
6750: 20 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65    0x00000400.#de
6760: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6770: 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48  P_UNDELETABLE_WH
6780: 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30  EN_OPEN  0x00000
6790: 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  800.#define SQLI
67a0: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41  TE_IOCAP_POWERSA
67b0: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20  FE_OVERWRITE    
67c0: 30 78 30 30 30 30 31 30 30 30 0a 0a 2f 2a 0a 2a  0x00001000../*.*
67d0: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65  * CAPI3REF: File
67e0: 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a   Locking Levels.
67f0: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
6800: 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69  s one of these i
6810: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
6820: 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61   the second.** a
6830: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73  rgument to calls
6840: 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65   it makes to the
6850: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e   xLock() and xUn
6860: 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a  lock() methods.*
6870: 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  * of an [sqlite3
6880: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
6890: 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ect..*/.#define 
68a0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
68b0: 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
68c0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
68d0: 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a  SHARED        1.
68e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
68f0: 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20  OCK_RESERVED    
6900: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
6910: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20  TE_LOCK_PENDING 
6920: 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
6930: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
6940: 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a  USIVE     4../*.
6950: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e  ** CAPI3REF: Syn
6960: 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70  chronization Typ
6970: 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68  e Flags.**.** Wh
6980: 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65  en SQLite invoke
6990: 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65  s the xSync() me
69a0: 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73  thod of an.** [s
69b0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
69c0: 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65  s] object it use
69d0: 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  s a combination 
69e0: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65  of.** these inte
69f0: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
6a00: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
6a10: 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  t..**.** When th
6a20: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
6a30: 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75  TAONLY flag is u
6a40: 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  sed, it means th
6a50: 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f  at the.** sync o
6a60: 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65  peration only ne
6a70: 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74  eds to flush dat
6a80: 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67  a to mass storag
6a90: 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66  e.  Inode.** inf
6aa0: 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f  ormation need no
6ab0: 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66  t be flushed. If
6ac0: 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20   the lower four 
6ad0: 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67  bits of the flag
6ae0: 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45  .** equal SQLITE
6af0: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68  _SYNC_NORMAL, th
6b00: 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20  at means to use 
6b10: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73  normal fsync() s
6b20: 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20  emantics..** If 
6b30: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62  the lower four b
6b40: 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45  its equal SQLITE
6b50: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74  _SYNC_FULL, that
6b60: 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65   means.** to use
6b70: 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20   Mac OS X style 
6b80: 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64  fullsync instead
6b90: 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a   of fsync()..**.
6ba0: 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73  ** Do not confus
6bb0: 65 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e  e the SQLITE_SYN
6bc0: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c  C_NORMAL and SQL
6bd0: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c  ITE_SYNC_FULL fl
6be0: 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ags.** with the 
6bf0: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e  [PRAGMA synchron
6c00: 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20  ous]=NORMAL and 
6c10: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e  [PRAGMA synchron
6c20: 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74  ous]=FULL.** set
6c30: 74 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e  tings.  The [syn
6c40: 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d  chronous pragma]
6c50: 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e   determines when
6c60: 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a   calls to the.**
6c70: 20 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f   xSync VFS metho
6c80: 64 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c  d occur and appl
6c90: 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63  ies uniformly ac
6ca0: 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72  ross all platfor
6cb0: 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  ms..** The SQLIT
6cc0: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e  E_SYNC_NORMAL an
6cd0: 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  d SQLITE_SYNC_FU
6ce0: 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69  LL flags determi
6cf0: 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65  ne how.** energe
6d00: 74 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20  tic or rigorous 
6d10: 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20  or forceful the 
6d20: 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20  sync operations 
6d30: 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20  are and.** only 
6d40: 6d 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63  make a differenc
6d50: 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72  e on Mac OSX for
6d60: 20 74 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c   the default SQL
6d70: 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68  ite code..** (Th
6d80: 69 72 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d  ird-party VFS im
6d90: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69  plementations mi
6da0: 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68  ght also make th
6db0: 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a  e distinction.**
6dc0: 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f   between SQLITE_
6dd0: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
6de0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
6df0: 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a  , but among the.
6e00: 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  ** operating sys
6e10: 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75  tems natively su
6e20: 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74  pported by SQLit
6e30: 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a  e, only Mac OSX.
6e40: 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20 74  ** cares about t
6e50: 68 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a  he difference.).
6e60: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6e70: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20  E_SYNC_NORMAL   
6e80: 20 20 20 20 20 30 78 30 30 30 30 32 0a 23 64 65       0x00002.#de
6e90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
6ea0: 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30  _FULL          0
6eb0: 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53  x00003.#define S
6ec0: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
6ed0: 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30 31 30  NLY      0x00010
6ee0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
6ef0: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f  : OS Interface O
6f00: 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a  pen File Handle.
6f10: 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65  **.** An [sqlite
6f20: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72  3_file] object r
6f30: 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65  epresents an ope
6f40: 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a  n file in the .*
6f50: 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c  * [sqlite3_vfs |
6f60: 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61   OS interface la
6f70: 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61  yer].  Individua
6f80: 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a  l OS interface.*
6f90: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
6fa0: 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74  s will.** want t
6fb0: 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20  o subclass this 
6fc0: 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64  object by append
6fd0: 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66  ing additional f
6fe0: 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65  ields.** for the
6ff0: 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65  ir own use.  The
7000: 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20   pMethods entry 
7010: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
7020: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69  an.** [sqlite3_i
7030: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
7040: 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d  t that defines m
7050: 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f  ethods for perfo
7060: 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65  rming.** I/O ope
7070: 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f  rations on the o
7080: 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70  pen file..*/.typ
7090: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
70a0: 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33  te3_file sqlite3
70b0: 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71  _file;.struct sq
70c0: 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63  lite3_file {.  c
70d0: 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69  onst struct sqli
70e0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a  te3_io_methods *
70f0: 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65  pMethods;  /* Me
7100: 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65  thods for an ope
7110: 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  n file */.};../*
7120: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
7130: 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20   Interface File 
7140: 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20  Virtual Methods 
7150: 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65  Object.**.** Eve
7160: 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62  ry file opened b
7170: 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  y the [sqlite3_v
7180: 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64  fs.xOpen] method
7190: 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a   populates an.**
71a0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
71b0: 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65  object (or, more
71c0: 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62   commonly, a sub
71d0: 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20  class of the.** 
71e0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
71f0: 62 6a 65 63 74 29 20 77 69 74 68 20 61 20 70 6f  bject) with a po
7200: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
7210: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
7220: 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a  ect..** This obj
7230: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
7240: 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20  methods used to 
7250: 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20  perform various 
7260: 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67  operations.** ag
7270: 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66  ainst the open f
7280: 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64 20  ile represented 
7290: 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
72a0: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  file] object..**
72b0: 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69  .** If the [sqli
72c0: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d  te3_vfs.xOpen] m
72d0: 65 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 73  ethod sets the s
72e0: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
72f0: 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a  hods element .**
7300: 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70   to a non-NULL p
7310: 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65  ointer, then the
7320: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
7330: 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f  ods.xClose metho
7340: 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f  d.** may be invo
7350: 6b 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 20  ked even if the 
7360: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
7370: 65 6e 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61  en] reported tha
7380: 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68  t it failed.  Th
7390: 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f  e.** only way to
73a0: 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20   prevent a call 
73b0: 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77  to xClose follow
73c0: 69 6e 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71  ing a failed [sq
73d0: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
73e0: 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b  .** is for the [
73f0: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
7400: 6e 5d 20 74 6f 20 73 65 74 20 74 68 65 20 73 71  n] to set the sq
7410: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
7420: 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74  ods element.** t
7430: 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68  o NULL..**.** Th
7440: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
7450: 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65   to xSync may be
7460: 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
7470: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a  SYNC_NORMAL] or.
7480: 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ** [SQLITE_SYNC_
7490: 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73  FULL].  The firs
74a0: 74 20 63 68 6f 69 63 65 20 69 73 20 74 68 65 20  t choice is the 
74b0: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a  normal fsync()..
74c0: 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68  ** The second ch
74d0: 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53  oice is a Mac OS
74e0: 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e   X style fullsyn
74f0: 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  c.  The [SQLITE_
7500: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a  SYNC_DATAONLY].*
7510: 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52  * flag may be OR
7520: 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74  ed in to indicat
7530: 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20  e that only the 
7540: 64 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65  data of the file
7550: 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20  .** and not its 
7560: 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62  inode needs to b
7570: 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20  e synced..**.** 
7580: 54 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  The integer valu
7590: 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e  es to xLock() an
75a0: 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20  d xUnlock() are 
75b0: 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a  one of.** <ul>.*
75c0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
75d0: 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c  OCK_NONE],.** <l
75e0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
75f0: 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e  SHARED],.** <li>
7600: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45   [SQLITE_LOCK_RE
7610: 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e  SERVED],.** <li>
7620: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45   [SQLITE_LOCK_PE
7630: 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c  NDING], or.** <l
7640: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
7650: 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c  EXCLUSIVE]..** <
7660: 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20  /ul>.** xLock() 
7670: 69 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f  increases the lo
7680: 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65  ck. xUnlock() de
7690: 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b  creases the lock
76a0: 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52  ..** The xCheckR
76b0: 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65  eservedLock() me
76c0: 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74  thod checks whet
76d0: 68 65 72 20 61 6e 79 20 64 61 74 61 62 61 73 65  her any database
76e0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20   connection,.** 
76f0: 65 69 74 68 65 72 20 69 6e 20 74 68 69 73 20 70  either in this p
7700: 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d  rocess or in som
7710: 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c  e other process,
7720: 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45   is holding a RE
7730: 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49  SERVED,.** PENDI
7740: 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45  NG, or EXCLUSIVE
7750: 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c   lock on the fil
7760: 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 74  e.  It returns t
7770: 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61  rue.** if such a
7780: 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64   lock exists and
7790: 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65   false otherwise
77a0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c  ..**.** The xFil
77b0: 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f  eControl() metho
77c0: 64 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 69  d is a generic i
77d0: 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61 6c  nterface that al
77e0: 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56  lows custom.** V
77f0: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
7800: 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63  ns to directly c
7810: 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66  ontrol an open f
7820: 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  ile using the.**
7830: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
7840: 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66  ontrol()] interf
7850: 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  ace.  The second
7860: 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69   "op" argument i
7870: 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20  s an.** integer 
7880: 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69  opcode.  The thi
7890: 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  rd argument is a
78a0: 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72   generic pointer
78b0: 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20   intended to.** 
78c0: 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63  point to a struc
78d0: 74 75 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f  ture that may co
78e0: 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20  ntain arguments 
78f0: 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68 69 63  or space in whic
7900: 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65  h to.** write re
7910: 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f  turn values.  Po
7920: 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72  tential uses for
7930: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20   xFileControl() 
7940: 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63  might be.** func
7950: 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20  tions to enable 
7960: 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77  blocking locks w
7970: 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f  ith timeouts, to
7980: 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c   change the.** l
7990: 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20  ocking strategy 
79a0: 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20  (for example to 
79b0: 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63  use dot-file loc
79c0: 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a  ks), to inquire.
79d0: 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74 61  ** about the sta
79e0: 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f  tus of a lock, o
79f0: 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65  r to break stale
7a00: 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c   locks.  The SQL
7a10: 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65  ite.** core rese
7a20: 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73  rves all opcodes
7a30: 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 66   less than 100 f
7a40: 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a  or its own use..
7a50: 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ** A [SQLITE_FCN
7a60: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c  TL_LOCKSTATE | l
7a70: 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20  ist of opcodes] 
7a80: 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69 73  less than 100 is
7a90: 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41   available..** A
7aa0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
7ab0: 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d   define a custom
7ac0: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
7ad0: 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20  thod should use 
7ae0: 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74  opcodes.** great
7af0: 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61  er than 100 to a
7b00: 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20  void conflicts. 
7b10: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
7b20: 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72  ions should.** r
7b30: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f  eturn [SQLITE_NO
7b40: 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65  TFOUND] for file
7b50: 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73   control opcodes
7b60: 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f   that they do no
7b70: 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a  t.** recognize..
7b80: 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f  **.** The xSecto
7b90: 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72  rSize() method r
7ba0: 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f  eturns the secto
7bb0: 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a  r size of the.**
7bc0: 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e 64   device that und
7bd0: 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e  erlies the file.
7be0: 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a    The sector siz
7bf0: 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69  e is the.** mini
7c00: 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20 63  mum write that c
7c10: 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20  an be performed 
7c20: 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62 69  without disturbi
7c30: 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65  ng.** other byte
7c40: 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20  s in the file.  
7c50: 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61  The xDeviceChara
7c60: 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20  cteristics().** 
7c70: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61  method returns a
7c80: 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73 63   bit vector desc
7c90: 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73  ribing behaviors
7ca0: 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72   of the.** under
7cb0: 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a  lying device:.**
7cc0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
7cd0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
7ce0: 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  TOMIC].** <li> [
7cf0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7d00: 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC512].** <li> 
7d10: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
7d20: 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC1K].** <li> 
7d30: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
7d40: 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC2K].** <li> 
7d50: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
7d60: 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC4K].** <li> 
7d70: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
7d80: 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC8K].** <li> 
7d90: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
7da0: 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC16K].** <li>
7db0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
7dc0: 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC32K].** <li
7dd0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
7de0: 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC64K].** <l
7df0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
7e00: 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a  _SAFE_APPEND].**
7e10: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
7e20: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a  CAP_SEQUENTIAL].
7e30: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54  ** </ul>.**.** T
7e40: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
7e50: 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20  ATOMIC property 
7e60: 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77  means that all w
7e70: 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20  rites of.** any 
7e80: 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e  size are atomic.
7e90: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
7ea0: 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c  AP_ATOMICnnn val
7eb0: 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74  ues.** mean that
7ec0: 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b   writes of block
7ed0: 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62  s that are nnn b
7ee0: 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64  ytes in size and
7ef0: 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20  .** are aligned 
7f00: 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68  to an address wh
7f10: 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ich is an intege
7f20: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a  r multiple of.**
7f30: 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e   nnn are atomic.
7f40: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
7f50: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76  AP_SAFE_APPEND v
7f60: 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68  alue means.** th
7f70: 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20  at when data is 
7f80: 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69  appended to a fi
7f90: 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20  le, the data is 
7fa0: 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73  appended.** firs
7fb0: 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20  t then the size 
7fc0: 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65  of the file is e
7fd0: 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74  xtended, never t
7fe0: 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20  he other.** way 
7ff0: 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c  around.  The SQL
8000: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
8010: 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65  TIAL property me
8020: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f  ans that.** info
8030: 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74  rmation is writt
8040: 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68  en to disk in th
8050: 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20  e same order as 
8060: 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69  calls.** to xWri
8070: 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78  te()..**.** If x
8080: 52 65 61 64 28 29 20 72 65 74 75 72 6e 73 20 53  Read() returns S
8090: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52  QLITE_IOERR_SHOR
80a0: 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20 61  T_READ it must a
80b0: 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74  lso fill.** in t
80c0: 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f  he unread portio
80d0: 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  ns of the buffer
80e0: 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20   with zeros.  A 
80f0: 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c  VFS that.** fail
8100: 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73  s to zero-fill s
8110: 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68 74  hort reads might
8120: 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20   seem to work.  
8130: 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c  However,.** fail
8140: 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c  ure to zero-fill
8150: 20 73 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c   short reads wil
8160: 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61  l eventually lea
8170: 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65  d to.** database
8180: 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a   corruption..*/.
8190: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
81a0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
81b0: 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  s sqlite3_io_met
81c0: 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c  hods;.struct sql
81d0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
81e0: 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e  {.  int iVersion
81f0: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65  ;.  int (*xClose
8200: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
8210: 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29  ;.  int (*xRead)
8220: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8230: 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c  void*, int iAmt,
8240: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69   sqlite3_int64 i
8250: 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Ofst);.  int (*x
8260: 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66  Write)(sqlite3_f
8270: 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ile*, const void
8280: 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c  *, int iAmt, sql
8290: 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74  ite3_int64 iOfst
82a0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e  );.  int (*xTrun
82b0: 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69  cate)(sqlite3_fi
82c0: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  le*, sqlite3_int
82d0: 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20  64 size);.  int 
82e0: 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33  (*xSync)(sqlite3
82f0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67  _file*, int flag
8300: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c  s);.  int (*xFil
8310: 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66  eSize)(sqlite3_f
8320: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
8330: 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69  t64 *pSize);.  i
8340: 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69  nt (*xLock)(sqli
8350: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b  te3_file*, int);
8360: 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b  .  int (*xUnlock
8370: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8380: 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78   int);.  int (*x
8390: 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63  CheckReservedLoc
83a0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
83b0: 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b  , int *pResOut);
83c0: 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f  .  int (*xFileCo
83d0: 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66  ntrol)(sqlite3_f
83e0: 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f  ile*, int op, vo
83f0: 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74  id *pArg);.  int
8400: 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28   (*xSectorSize)(
8410: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
8420: 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43    int (*xDeviceC
8430: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 29 28  haracteristics)(
8440: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
8450: 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f    /* Methods abo
8460: 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72  ve are valid for
8470: 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20   version 1 */.  
8480: 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 73  int (*xShmMap)(s
8490: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
84a0: 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c  t iPg, int pgsz,
84b0: 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74   int, void volat
84c0: 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  ile**);.  int (*
84d0: 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65  xShmLock)(sqlite
84e0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66  3_file*, int off
84f0: 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20  set, int n, int 
8500: 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 28  flags);.  void (
8510: 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28 73 71  *xShmBarrier)(sq
8520: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
8530: 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29  int (*xShmUnmap)
8540: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8550: 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b  int deleteFlag);
8560: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
8570: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
8580: 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20  r version 2 */. 
8590: 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d   /* Additional m
85a0: 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64  ethods may be ad
85b0: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
85c0: 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  leases */.};../*
85d0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74  .** CAPI3REF: St
85e0: 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74  andard File Cont
85f0: 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a  rol Opcodes.**.*
8600: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
8610: 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70  constants are op
8620: 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78 46  codes for the xF
8630: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
8640: 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  d.** of the [sql
8650: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
8660: 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20   object and for 
8670: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
8680: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20  e_control()].** 
8690: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
86a0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
86b0: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70  TL_LOCKSTATE] op
86c0: 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72  code is used for
86d0: 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69   debugging.  Thi
86e0: 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73  s.** opcode caus
86f0: 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74  es the xFileCont
8700: 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72  rol method to wr
8710: 69 74 65 20 74 68 65 20 63 75 72 72 65 6e 74 20  ite the current 
8720: 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20  state of.** the 
8730: 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51  lock (one of [SQ
8740: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c  LITE_LOCK_NONE],
8750: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48   [SQLITE_LOCK_SH
8760: 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ARED],.** [SQLIT
8770: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d  E_LOCK_RESERVED]
8780: 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  , [SQLITE_LOCK_P
8790: 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c  ENDING], or [SQL
87a0: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
87b0: 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20  VE]).** into an 
87c0: 69 6e 74 65 67 65 72 20 74 68 61 74 20 74 68 65  integer that the
87d0: 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70   pArg argument p
87e0: 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63  oints to. This c
87f0: 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20  apability.** is 
8800: 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74  used during test
8810: 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65  ing and only nee
8820: 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ds to be support
8830: 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54  ed when SQLITE_T
8840: 45 53 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65  EST.** is define
8850: 64 2e 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  d..** <ul>.** <l
8860: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
8870: 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20  _SIZE_HINT]].** 
8880: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
8890: 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63  L_SIZE_HINT] opc
88a0: 6f 64 65 20 69 73 20 75 73 65 64 20 62 79 20 53  ode is used by S
88b0: 51 4c 69 74 65 20 74 6f 20 67 69 76 65 20 74 68  QLite to give th
88c0: 65 20 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61  e VFS.** layer a
88d0: 20 68 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72   hint of how lar
88e0: 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
88f0: 66 69 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20 74  file will grow t
8900: 6f 20 62 65 20 64 75 72 69 6e 67 20 74 68 65 0a  o be during the.
8910: 2a 2a 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73  ** current trans
8920: 61 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 68 69  action.  This hi
8930: 6e 74 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e  nt is not guaran
8940: 74 65 65 64 20 74 6f 20 62 65 20 61 63 63 75 72  teed to be accur
8950: 61 74 65 20 62 75 74 20 69 74 0a 2a 2a 20 69 73  ate but it.** is
8960: 20 6f 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54   often close.  T
8970: 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 56 46  he underlying VF
8980: 53 20 6d 69 67 68 74 20 63 68 6f 6f 73 65 20 74  S might choose t
8990: 6f 20 70 72 65 61 6c 6c 6f 63 61 74 65 20 64 61  o preallocate da
89a0: 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73  tabase.** file s
89b0: 70 61 63 65 20 62 61 73 65 64 20 6f 6e 20 74 68  pace based on th
89c0: 69 73 20 68 69 6e 74 20 69 6e 20 6f 72 64 65 72  is hint in order
89d0: 20 74 6f 20 68 65 6c 70 20 77 72 69 74 65 73 20   to help writes 
89e0: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  to the database.
89f0: 2a 2a 20 66 69 6c 65 20 72 75 6e 20 66 61 73 74  ** file run fast
8a00: 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  er..**.** <li>[[
8a10: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55  SQLITE_FCNTL_CHU
8a20: 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65  NK_SIZE]].** The
8a30: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43   [SQLITE_FCNTL_C
8a40: 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64  HUNK_SIZE] opcod
8a50: 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 71  e is used to req
8a60: 75 65 73 74 20 74 68 61 74 20 74 68 65 20 56 46  uest that the VF
8a70: 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e 64  S.** extends and
8a80: 20 74 72 75 6e 63 61 74 65 73 20 74 68 65 20 64   truncates the d
8a90: 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 6e 20  atabase file in 
8aa0: 63 68 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65  chunks of a size
8ab0: 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79   specified.** by
8ac0: 20 74 68 65 20 75 73 65 72 2e 20 54 68 65 20 66   the user. The f
8ad0: 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74  ourth argument t
8ae0: 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  o [sqlite3_file_
8af0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c  control()] shoul
8b00: 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61  d .** point to a
8b10: 6e 20 69 6e 74 65 67 65 72 20 28 74 79 70 65 20  n integer (type 
8b20: 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20  int) containing 
8b30: 74 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69  the new chunk-si
8b40: 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72  ze to use.** for
8b50: 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64   the nominated d
8b60: 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74  atabase. Allocat
8b70: 69 6e 67 20 64 61 74 61 62 61 73 65 20 66 69 6c  ing database fil
8b80: 65 20 73 70 61 63 65 20 69 6e 20 6c 61 72 67 65  e space in large
8b90: 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61 79 20  .** chunks (say 
8ba0: 31 4d 42 20 61 74 20 61 20 74 69 6d 65 29 2c 20  1MB at a time), 
8bb0: 6d 61 79 20 72 65 64 75 63 65 20 66 69 6c 65 2d  may reduce file-
8bc0: 73 79 73 74 65 6d 20 66 72 61 67 6d 65 6e 74 61  system fragmenta
8bd0: 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72  tion and.** impr
8be0: 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  ove performance 
8bf0: 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e  on some systems.
8c00: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
8c10: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50  ITE_FCNTL_FILE_P
8c20: 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20  OINTER]].** The 
8c30: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49  [SQLITE_FCNTL_FI
8c40: 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f  LE_POINTER] opco
8c50: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62  de is used to ob
8c60: 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a  tain a pointer.*
8c70: 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  * to the [sqlite
8c80: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61  3_file] object a
8c90: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61  ssociated with a
8ca0: 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61   particular data
8cb0: 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
8cc0: 6f 6e 2e 20 20 53 65 65 20 74 68 65 20 5b 73 71  on.  See the [sq
8cd0: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
8ce0: 6f 6c 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74  ol()] documentat
8cf0: 69 6f 6e 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74  ion for.** addit
8d00: 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
8d10: 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  n..**.** <li>[[S
8d20: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
8d30: 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 5e 28  _OMITTED]].** ^(
8d40: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
8d50: 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 20  L_SYNC_OMITTED] 
8d60: 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61  opcode is genera
8d70: 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  ted internally b
8d80: 79 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20  y.** SQLite and 
8d90: 73 65 6e 74 20 74 6f 20 61 6c 6c 20 56 46 53 65  sent to all VFSe
8da0: 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 61 20  s in place of a 
8db0: 63 61 6c 6c 20 74 6f 20 74 68 65 20 78 53 79 6e  call to the xSyn
8dc0: 63 20 6d 65 74 68 6f 64 0a 2a 2a 20 77 68 65 6e  c method.** when
8dd0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
8de0: 6e 6e 65 63 74 69 6f 6e 20 68 61 73 20 5b 50 52  nnection has [PR
8df0: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
8e00: 5d 20 73 65 74 20 74 6f 20 4f 46 46 2e 29 5e 0a  ] set to OFF.)^.
8e10: 2a 2a 20 53 6f 6d 65 20 73 70 65 63 69 61 6c 69  ** Some speciali
8e20: 7a 65 64 20 56 46 53 65 73 20 6e 65 65 64 20 74  zed VFSes need t
8e30: 68 69 73 20 73 69 67 6e 61 6c 20 69 6e 20 6f 72  his signal in or
8e40: 64 65 72 20 74 6f 20 6f 70 65 72 61 74 65 20 63  der to operate c
8e50: 6f 72 72 65 63 74 6c 79 0a 2a 2a 20 77 68 65 6e  orrectly.** when
8e60: 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f   [PRAGMA synchro
8e70: 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41 20 73 79  nous | PRAGMA sy
8e80: 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69  nchronous=OFF] i
8e90: 73 20 73 65 74 2c 20 62 75 74 20 6d 6f 73 74 20  s set, but most 
8ea0: 0a 2a 2a 20 56 46 53 65 73 20 64 6f 20 6e 6f 74  .** VFSes do not
8eb0: 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61   need this signa
8ec0: 6c 20 61 6e 64 20 73 68 6f 75 6c 64 20 73 69 6c  l and should sil
8ed0: 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69  ently ignore thi
8ee0: 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a 20 41 70 70  s opcode..** App
8ef0: 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  lications should
8f00: 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74   not call [sqlit
8f10: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
8f20: 29 5d 20 77 69 74 68 20 74 68 69 73 0a 2a 2a 20  )] with this.** 
8f30: 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20  opcode as doing 
8f40: 73 6f 20 6d 61 79 20 64 69 73 72 75 70 74 20 74  so may disrupt t
8f50: 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20  he operation of 
8f60: 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20  the specialized 
8f70: 56 46 53 65 73 0a 2a 2a 20 74 68 61 74 20 64 6f  VFSes.** that do
8f80: 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a   require it.  .*
8f90: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
8fa0: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56  E_FCNTL_WIN32_AV
8fb0: 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65  _RETRY]].** ^The
8fc0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57   [SQLITE_FCNTL_W
8fd0: 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f  IN32_AV_RETRY] o
8fe0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
8ff0: 20 63 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d   configure autom
9000: 61 74 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f  atic.** retry co
9010: 75 6e 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61  unts and interva
9020: 6c 73 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64  ls for certain d
9030: 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f  isk I/O operatio
9040: 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69  ns for the.** wi
9050: 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f  ndows [VFS] in o
9060: 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20  rder to provide 
9070: 72 6f 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68  robustness in th
9080: 65 20 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a  e presence of.**
9090: 20 61 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67   anti-virus prog
90a0: 72 61 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c  rams.  By defaul
90b0: 74 2c 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56  t, the windows V
90c0: 46 53 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69  FS will retry fi
90d0: 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65  le read,.** file
90e0: 20 77 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65   write, and file
90f0: 20 64 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f   delete operatio
9100: 6e 73 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65  ns up to 10 time
9110: 73 2c 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a  s, with a delay.
9120: 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65  ** of 25 millise
9130: 63 6f 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65  conds before the
9140: 20 66 69 72 73 74 20 72 65 74 72 79 20 61 6e 64   first retry and
9150: 20 77 69 74 68 20 74 68 65 20 64 65 6c 61 79 20   with the delay 
9160: 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79  increasing.** by
9170: 20 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32   an additional 2
9180: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77  5 milliseconds w
9190: 69 74 68 20 65 61 63 68 20 73 75 62 73 65 71 75  ith each subsequ
91a0: 65 6e 74 20 72 65 74 72 79 2e 20 20 54 68 69 73  ent retry.  This
91b0: 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77  .** opcode allow
91c0: 73 20 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75  s these two valu
91d0: 65 73 20 28 31 30 20 72 65 74 72 69 65 73 20 61  es (10 retries a
91e0: 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e  nd 25 millisecon
91f0: 64 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20  ds of delay).** 
9200: 74 6f 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20  to be adjusted. 
9210: 20 54 68 65 20 76 61 6c 75 65 73 20 61 72 65 20   The values are 
9220: 63 68 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20  changed for all 
9230: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
9240: 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74  ions.** within t
9250: 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e  he same process.
9260: 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69    The argument i
9270: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
9280: 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a  n array of two.*
9290: 2a 20 69 6e 74 65 67 65 72 73 20 77 68 65 72 65  * integers where
92a0: 20 74 68 65 20 66 69 72 73 74 20 69 6e 74 65 67   the first integ
92b0: 65 72 20 69 20 74 68 65 20 6e 65 77 20 72 65 74  er i the new ret
92c0: 72 79 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 65  ry count and the
92d0: 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67   second.** integ
92e0: 65 72 20 69 73 20 74 68 65 20 64 65 6c 61 79 2e  er is the delay.
92f0: 20 20 49 66 20 65 69 74 68 65 72 20 69 6e 74 65    If either inte
9300: 67 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c  ger is negative,
9310: 20 74 68 65 6e 20 74 68 65 20 73 65 74 74 69 6e   then the settin
9320: 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e  g.** is not chan
9330: 67 65 64 20 62 75 74 20 69 6e 73 74 65 61 64 20  ged but instead 
9340: 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20  the prior value 
9350: 6f 66 20 74 68 61 74 20 73 65 74 74 69 6e 67 20  of that setting 
9360: 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e  is written.** in
9370: 74 6f 20 74 68 65 20 61 72 72 61 79 20 65 6e 74  to the array ent
9380: 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65  ry, allowing the
9390: 20 63 75 72 72 65 6e 74 20 72 65 74 72 79 20 73   current retry s
93a0: 65 74 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a  ettings to be.**
93b0: 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20   interrogated.  
93c0: 54 68 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 61  The zDbName para
93d0: 6d 65 74 65 72 20 69 73 20 69 67 6e 6f 72 65 64  meter is ignored
93e0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
93f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49  LITE_FCNTL_PERSI
9400: 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65  ST_WAL]].** ^The
9410: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
9420: 45 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f  ERSIST_WAL] opco
9430: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65  de is used to se
9440: 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a  t or query the.*
9450: 2a 20 70 65 72 73 69 73 74 65 6e 74 20 5b 57 41  * persistent [WA
9460: 4c 20 7c 20 57 72 69 74 65 20 41 68 65 61 64 20  L | Write Ahead 
9470: 4c 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 42  Log] setting.  B
9480: 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 61  y default, the a
9490: 75 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74  uxiliary.** writ
94a0: 65 20 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 20  e ahead log and 
94b0: 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69  shared memory fi
94c0: 6c 65 73 20 75 73 65 64 20 66 6f 72 20 74 72 61  les used for tra
94d0: 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c  nsaction control
94e0: 0a 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 69  .** are automati
94f0: 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 68  cally deleted wh
9500: 65 6e 20 74 68 65 20 6c 61 74 65 73 74 20 63 6f  en the latest co
9510: 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20  nnection to the 
9520: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73  database.** clos
9530: 65 73 2e 20 20 53 65 74 74 69 6e 67 20 70 65 72  es.  Setting per
9540: 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65  sistent WAL mode
9550: 20 63 61 75 73 65 73 20 74 68 6f 73 65 20 66 69   causes those fi
9560: 6c 65 73 20 74 6f 20 70 65 72 73 69 73 74 20 61  les to persist a
9570: 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20  fter.** close.  
9580: 50 65 72 73 69 73 74 69 6e 67 20 74 68 65 20 66  Persisting the f
9590: 69 6c 65 73 20 69 73 20 75 73 65 66 75 6c 20 77  iles is useful w
95a0: 68 65 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73  hen other proces
95b0: 73 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a  ses that do not.
95c0: 2a 2a 20 68 61 76 65 20 77 72 69 74 65 20 70 65  ** have write pe
95d0: 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20  rmission on the 
95e0: 64 69 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69  directory contai
95f0: 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73  ning the databas
9600: 65 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74  e file want.** t
9610: 6f 20 72 65 61 64 20 74 68 65 20 64 61 74 61 62  o read the datab
9620: 61 73 65 20 66 69 6c 65 2c 20 61 73 20 74 68 65  ase file, as the
9630: 20 57 41 4c 20 61 6e 64 20 73 68 61 72 65 64 20   WAL and shared 
9640: 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 73  memory files mus
9650: 74 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72  t exist.** in or
9660: 64 65 72 20 66 6f 72 20 74 68 65 20 64 61 74 61  der for the data
9670: 62 61 73 65 20 74 6f 20 62 65 20 72 65 61 64 61  base to be reada
9680: 62 6c 65 2e 20 20 54 68 65 20 66 6f 75 72 74 68  ble.  The fourth
9690: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
96a0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
96b0: 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68  ontrol()] for th
96c0: 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64  is opcode should
96d0: 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   be a pointer to
96e0: 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20   an integer..** 
96f0: 54 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20  That integer is 
9700: 30 20 74 6f 20 64 69 73 61 62 6c 65 20 70 65 72  0 to disable per
9710: 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65  sistent WAL mode
9720: 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20   or 1 to enable 
9730: 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41  persistent.** WA
9740: 4c 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20  L mode.  If the 
9750: 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74  integer is -1, t
9760: 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72  hen it is overwr
9770: 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63  itten with the c
9780: 75 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65  urrent.** WAL pe
9790: 72 73 69 73 74 65 6e 63 65 20 73 65 74 74 69 6e  rsistence settin
97a0: 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  g..**.** <li>[[S
97b0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45  QLITE_FCNTL_POWE
97c0: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d  RSAFE_OVERWRITE]
97d0: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
97e0: 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46  E_FCNTL_POWERSAF
97f0: 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63  E_OVERWRITE] opc
9800: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73  ode is used to s
9810: 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a  et or query the.
9820: 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 22 70  ** persistent "p
9830: 6f 77 65 72 73 61 66 65 2d 6f 76 65 72 77 72 69  owersafe-overwri
9840: 74 65 22 20 6f 72 20 22 50 53 4f 57 22 20 73 65  te" or "PSOW" se
9850: 74 74 69 6e 67 2e 20 20 54 68 65 20 50 53 4f 57  tting.  The PSOW
9860: 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65   setting.** dete
9870: 72 6d 69 6e 65 73 20 74 68 65 20 5b 53 51 4c 49  rmines the [SQLI
9880: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41  TE_IOCAP_POWERSA
9890: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 62 69  FE_OVERWRITE] bi
98a0: 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65 76  t of the.** xDev
98b0: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
98c0: 63 73 20 6d 65 74 68 6f 64 73 2e 20 54 68 65 20  cs methods. The 
98d0: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
98e0: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
98f0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
9900: 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20  for this opcode 
9910: 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e  should be a poin
9920: 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
9930: 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67  r..** That integ
9940: 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  er is 0 to disab
9950: 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d  le zero-damage m
9960: 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62  ode or 1 to enab
9970: 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a  le zero-damage.*
9980: 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20  * mode.  If the 
9990: 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74  integer is -1, t
99a0: 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72  hen it is overwr
99b0: 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63  itten with the c
99c0: 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64  urrent.** zero-d
99d0: 61 6d 61 67 65 20 6d 6f 64 65 20 73 65 74 74 69  amage mode setti
99e0: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ng..**.** <li>[[
99f0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45  SQLITE_FCNTL_OVE
9a00: 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65  RWRITE]].** ^The
9a10: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f   [SQLITE_FCNTL_O
9a20: 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65  VERWRITE] opcode
9a30: 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 53   is invoked by S
9a40: 51 4c 69 74 65 20 61 66 74 65 72 20 6f 70 65 6e  QLite after open
9a50: 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65 20 74  ing.** a write t
9a60: 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e  ransaction to in
9a70: 64 69 63 61 74 65 20 74 68 61 74 2c 20 75 6e 6c  dicate that, unl
9a80: 65 73 73 20 69 74 20 69 73 20 72 6f 6c 6c 65 64  ess it is rolled
9a90: 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a   back for some.*
9aa0: 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e  * reason, the en
9ab0: 74 69 72 65 20 64 61 74 61 62 61 73 65 20 66 69  tire database fi
9ac0: 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76 65 72 77  le will be overw
9ad0: 72 69 74 74 65 6e 20 62 79 20 74 68 65 20 63 75  ritten by the cu
9ae0: 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61  rrent .** transa
9af0: 63 74 69 6f 6e 2e 20 54 68 69 73 20 69 73 20 75  ction. This is u
9b00: 73 65 64 20 62 79 20 56 41 43 55 55 4d 20 6f 70  sed by VACUUM op
9b10: 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  erations..**.** 
9b20: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
9b30: 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20  TL_VFSNAME]].** 
9b40: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
9b50: 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f  TL_VFSNAME] opco
9b60: 64 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  de can be used t
9b70: 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6e 61 6d  o obtain the nam
9b80: 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46  es of.** all [VF
9b90: 53 65 73 5d 20 69 6e 20 74 68 65 20 56 46 53 20  Ses] in the VFS 
9ba0: 73 74 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65  stack.  The name
9bb0: 73 20 61 72 65 20 6f 66 20 61 6c 6c 20 56 46 53  s are of all VFS
9bc0: 20 73 68 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a   shims and the.*
9bd0: 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c  * final bottom-l
9be0: 65 76 65 6c 20 56 46 53 20 61 72 65 20 77 72 69  evel VFS are wri
9bf0: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  tten into memory
9c00: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a   obtained from .
9c10: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
9c20: 6f 63 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65  oc()] and the re
9c30: 73 75 6c 74 20 69 73 20 73 74 6f 72 65 64 20 69  sult is stored i
9c40: 6e 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 69  n the char* vari
9c50: 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68 65  able.** that the
9c60: 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
9c70: 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66 69  r of [sqlite3_fi
9c80: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f  le_control()] po
9c90: 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20  ints to..** The 
9ca0: 63 61 6c 6c 65 72 20 69 73 20 72 65 73 70 6f 6e  caller is respon
9cb0: 73 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e  sible for freein
9cc0: 67 20 74 68 65 20 6d 65 6d 6f 72 79 20 77 68 65  g the memory whe
9cd0: 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77 69 74 68  n done.  As with
9ce0: 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e  .** all file-con
9cf0: 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68  trol actions, th
9d00: 65 72 65 20 69 73 20 6e 6f 20 67 75 61 72 61 6e  ere is no guaran
9d10: 74 65 65 20 74 68 61 74 20 74 68 69 73 20 77 69  tee that this wi
9d20: 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64  ll actually.** d
9d30: 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c  o anything.  Cal
9d40: 6c 65 72 73 20 73 68 6f 75 6c 64 20 69 6e 69 74  lers should init
9d50: 69 61 6c 69 7a 65 20 74 68 65 20 63 68 61 72 2a  ialize the char*
9d60: 20 76 61 72 69 61 62 6c 65 20 74 6f 20 61 20 4e   variable to a N
9d70: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69  ULL.** pointer i
9d80: 6e 20 63 61 73 65 20 74 68 69 73 20 66 69 6c 65  n case this file
9d90: 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20  -control is not 
9da0: 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68  implemented.  Th
9db0: 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a  is file-control.
9dc0: 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66  ** is intended f
9dd0: 6f 72 20 64 69 61 67 6e 6f 73 74 69 63 20 75 73  or diagnostic us
9de0: 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  e only..**.** <l
9df0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9e00: 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68  _PRAGMA]].** ^Wh
9e10: 65 6e 65 76 65 72 20 61 20 5b 50 52 41 47 4d 41  enever a [PRAGMA
9e20: 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 70  ] statement is p
9e30: 61 72 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54  arsed, an [SQLIT
9e40: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
9e50: 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  .** file control
9e60: 20 69 73 20 73 65 6e 74 20 74 6f 20 74 68 65 20   is sent to the 
9e70: 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  open [sqlite3_fi
9e80: 6c 65 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72 65  le] object corre
9e90: 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74  sponding.** to t
9ea0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
9eb0: 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 70 72   to which the pr
9ec0: 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 72  agma statement r
9ed0: 65 66 65 72 73 2e 20 5e 54 68 65 20 61 72 67 75  efers. ^The argu
9ee0: 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  ment.** to the [
9ef0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
9f00: 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  GMA] file contro
9f10: 6c 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  l is an array of
9f20: 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  .** pointers to 
9f30: 73 74 72 69 6e 67 73 20 28 63 68 61 72 2a 2a 29  strings (char**)
9f40: 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 73 65   in which the se
9f50: 63 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20  cond element of 
9f60: 74 68 65 20 61 72 72 61 79 0a 2a 2a 20 69 73 20  the array.** is 
9f70: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
9f80: 70 72 61 67 6d 61 20 61 6e 64 20 74 68 65 20 74  pragma and the t
9f90: 68 69 72 64 20 65 6c 65 6d 65 6e 74 20 69 73 20  hird element is 
9fa0: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  the argument to 
9fb0: 74 68 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72  the.** pragma or
9fc0: 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 70 72 61   NULL if the pra
9fd0: 67 6d 61 20 68 61 73 20 6e 6f 20 61 72 67 75 6d  gma has no argum
9fe0: 65 6e 74 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c  ent.  ^The handl
9ff0: 65 72 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51  er for an.** [SQ
a000: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
a010: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
a020: 63 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d  can optionally m
a030: 61 6b 65 20 74 68 65 20 66 69 72 73 74 20 65 6c  ake the first el
a040: 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20  ement.** of the 
a050: 63 68 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20  char** argument 
a060: 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e  point to a strin
a070: 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  g obtained from 
a080: 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  [sqlite3_mprintf
a090: 28 29 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71  ()].** or the eq
a0a0: 75 69 76 61 6c 65 6e 74 20 61 6e 64 20 74 68 61  uivalent and tha
a0b0: 74 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65  t string will be
a0c0: 63 6f 6d 65 20 74 68 65 20 72 65 73 75 6c 74 20  come the result 
a0d0: 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 6f 72  of the pragma or
a0e0: 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65  .** the error me
a0f0: 73 73 61 67 65 20 69 66 20 74 68 65 20 70 72 61  ssage if the pra
a100: 67 6d 61 20 66 61 69 6c 73 2e 20 5e 49 66 20 74  gma fails. ^If t
a110: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  he.** [SQLITE_FC
a120: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
a130: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73   control returns
a140: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e   [SQLITE_NOTFOUN
a150: 44 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20  D], then normal 
a160: 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f  .** [PRAGMA] pro
a170: 63 65 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65  cessing continue
a180: 73 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  s.  ^If the [SQL
a190: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
a1a0: 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f  ].** file contro
a1b0: 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  l returns [SQLIT
a1c0: 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20  E_OK], then the 
a1d0: 70 61 72 73 65 72 20 61 73 73 75 6d 65 73 20 74  parser assumes t
a1e0: 68 61 74 20 74 68 65 0a 2a 2a 20 56 46 53 20 68  hat the.** VFS h
a1f0: 61 73 20 68 61 6e 64 6c 65 64 20 74 68 65 20 50  as handled the P
a200: 52 41 47 4d 41 20 69 74 73 65 6c 66 20 61 6e 64  RAGMA itself and
a210: 20 74 68 65 20 70 61 72 73 65 72 20 67 65 6e 65   the parser gene
a220: 72 61 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a  rates a no-op.**
a230: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
a240: 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 5b 53  ent.  ^If the [S
a250: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
a260: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  MA] file control
a270: 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20   returns.** any 
a280: 72 65 73 75 6c 74 20 63 6f 64 65 20 6f 74 68 65  result code othe
a290: 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f  r than [SQLITE_O
a2a0: 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f  K] or [SQLITE_NO
a2b0: 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65  TFOUND], that me
a2c0: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  ans.** that the 
a2d0: 56 46 53 20 65 6e 63 6f 75 6e 74 65 72 65 64 20  VFS encountered 
a2e0: 61 6e 20 65 72 72 6f 72 20 77 68 69 6c 65 20 68  an error while h
a2f0: 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50 52 41  andling the [PRA
a300: 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20  GMA] and the.** 
a310: 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74  compilation of t
a320: 68 65 20 50 52 41 47 4d 41 20 66 61 69 6c 73 20  he PRAGMA fails 
a330: 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20  with an error.  
a340: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
a350: 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69  TL_PRAGMA].** fi
a360: 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72  le control occur
a370: 73 20 61 74 20 74 68 65 20 62 65 67 69 6e 6e 69  s at the beginni
a380: 6e 67 20 6f 66 20 70 72 61 67 6d 61 20 73 74 61  ng of pragma sta
a390: 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69 73 20  tement analysis 
a3a0: 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20  and so.** it is 
a3b0: 61 62 6c 65 20 74 6f 20 6f 76 65 72 72 69 64 65  able to override
a3c0: 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d   built-in [PRAGM
a3d0: 41 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  A] statements..*
a3e0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
a3f0: 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44  E_FCNTL_BUSYHAND
a400: 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68 69 73 20 66  LER]].** ^This f
a410: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79 20  ile-control may 
a420: 62 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51  be invoked by SQ
a430: 4c 69 74 65 20 6f 6e 20 74 68 65 20 64 61 74 61  Lite on the data
a440: 62 61 73 65 20 66 69 6c 65 20 68 61 6e 64 6c 65  base file handle
a450: 0a 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66 74 65  .** shortly afte
a460: 72 20 69 74 20 69 73 20 6f 70 65 6e 65 64 20 69  r it is opened i
a470: 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69  n order to provi
a480: 64 65 20 61 20 63 75 73 74 6f 6d 20 56 46 53 20  de a custom VFS 
a490: 77 69 74 68 20 61 63 63 65 73 73 0a 2a 2a 20 74  with access.** t
a4a0: 6f 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  o the connection
a4b0: 73 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63  s busy-handler c
a4c0: 61 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61 72 67  allback. The arg
a4d0: 75 6d 65 6e 74 20 69 73 20 6f 66 20 74 79 70 65  ument is of type
a4e0: 20 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20   (void **).** - 
a4f0: 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 20  an array of two 
a500: 28 76 6f 69 64 20 2a 29 20 76 61 6c 75 65 73 2e  (void *) values.
a510: 20 54 68 65 20 66 69 72 73 74 20 28 76 6f 69 64   The first (void
a520: 20 2a 29 20 61 63 74 75 61 6c 6c 79 20 70 6f 69   *) actually poi
a530: 6e 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75 6e 63  nts.** to a func
a540: 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 28 69 6e  tion of type (in
a550: 74 20 28 2a 29 28 76 6f 69 64 20 2a 29 29 2e 20  t (*)(void *)). 
a560: 49 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 76 6f  In order to invo
a570: 6b 65 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  ke the connectio
a580: 6e 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c  ns.** busy-handl
a590: 65 72 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f  er, this functio
a5a0: 6e 20 73 68 6f 75 6c 64 20 62 65 20 69 6e 76 6f  n should be invo
a5b0: 6b 65 64 20 77 69 74 68 20 74 68 65 20 73 65 63  ked with the sec
a5c0: 6f 6e 64 20 28 76 6f 69 64 20 2a 29 20 69 6e 0a  ond (void *) in.
a5d0: 2a 2a 20 74 68 65 20 61 72 72 61 79 20 61 73 20  ** the array as 
a5e0: 74 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e  the only argumen
a5f0: 74 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73  t. If it returns
a600: 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
a610: 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a  the operation.**
a620: 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 72 69   should be retri
a630: 65 64 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e  ed. If it return
a640: 73 20 7a 65 72 6f 2c 20 74 68 65 20 63 75 73 74  s zero, the cust
a650: 6f 6d 20 56 46 53 20 73 68 6f 75 6c 64 20 61 62  om VFS should ab
a660: 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63 75 72  andon the.** cur
a670: 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 2e 0a  rent operation..
a680: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
a690: 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c  TE_FCNTL_TEMPFIL
a6a0: 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c  ENAME]].** ^Appl
a6b0: 69 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e 76 6f  ication can invo
a6c0: 6b 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e  ke this file-con
a6d0: 74 72 6f 6c 20 74 6f 20 68 61 76 65 20 53 51 4c  trol to have SQL
a6e0: 69 74 65 20 67 65 6e 65 72 61 74 65 20 61 0a 2a  ite generate a.*
a6f0: 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  * temporary file
a700: 6e 61 6d 65 20 75 73 69 6e 67 20 74 68 65 20 73  name using the s
a710: 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 74 68  ame algorithm th
a720: 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74  at is followed t
a730: 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65  o generate.** te
a740: 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65  mporary filename
a750: 73 20 66 6f 72 20 54 45 4d 50 20 74 61 62 6c 65  s for TEMP table
a760: 73 20 61 6e 64 20 6f 74 68 65 72 20 69 6e 74 65  s and other inte
a770: 72 6e 61 6c 20 75 73 65 73 2e 20 20 54 68 65 0a  rnal uses.  The.
a780: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  ** argument shou
a790: 6c 64 20 62 65 20 61 20 63 68 61 72 2a 2a 20 77  ld be a char** w
a7a0: 68 69 63 68 20 77 69 6c 6c 20 62 65 20 66 69 6c  hich will be fil
a7b0: 6c 65 64 20 77 69 74 68 20 74 68 65 20 66 69 6c  led with the fil
a7c0: 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e  ename.** written
a7d0: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
a7e0: 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
a7f0: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20  te3_malloc()].  
a800: 54 68 65 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c  The caller shoul
a810: 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c  d.** invoke [sql
a820: 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20  ite3_free()] on 
a830: 74 68 65 20 72 65 73 75 6c 74 20 74 6f 20 61 76  the result to av
a840: 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61  oid a memory lea
a850: 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  k..**.** </ul>.*
a860: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
a870: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
a880: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
a890: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
a8a0: 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  GET_LOCKPROXYFIL
a8b0: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a  E             2.
a8c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
a8d0: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
a8e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23               3.#
a8f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41  define SQLITE_LA
a900: 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20  ST_ERRNO        
a910: 20 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64              4.#d
a920: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
a930: 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20  TL_SIZE_HINT    
a940: 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65             5.#de
a950: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
a960: 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20  L_CHUNK_SIZE    
a970: 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66            6.#def
a980: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
a990: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20  _FILE_POINTER   
a9a0: 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69           7.#defi
a9b0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
a9c0: 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20  SYNC_OMITTED    
a9d0: 20 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e          8.#defin
a9e0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57  e SQLITE_FCNTL_W
a9f0: 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20  IN32_AV_RETRY   
aa00: 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65         9.#define
aa10: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45   SQLITE_FCNTL_PE
aa20: 52 53 49 53 54 5f 57 41 4c 20 20 20 20 20 20 20  RSIST_WAL       
aa30: 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20       10.#define 
aa40: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45  SQLITE_FCNTL_OVE
aa50: 52 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20  RWRITE          
aa60: 20 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53      11.#define S
aa70: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e  QLITE_FCNTL_VFSN
aa80: 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 20 20  AME             
aa90: 20 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51     12.#define SQ
aaa0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52  LITE_FCNTL_POWER
aab0: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20  SAFE_OVERWRITE  
aac0: 20 20 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c    13.#define SQL
aad0: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
aae0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
aaf0: 20 31 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   14.#define SQLI
ab00: 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e  TE_FCNTL_BUSYHAN
ab10: 44 4c 45 52 20 20 20 20 20 20 20 20 20 20 20 20  DLER            
ab20: 31 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  15.#define SQLIT
ab30: 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45  E_FCNTL_TEMPFILE
ab40: 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 31  NAME           1
ab50: 36 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  6../*.** CAPI3RE
ab60: 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a  F: Mutex Handle.
ab70: 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20  **.** The mutex 
ab80: 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51  module within SQ
ab90: 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71  Lite defines [sq
aba0: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20  lite3_mutex] to 
abb0: 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63  be an.** abstrac
abc0: 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74  t type for a mut
abd0: 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20  ex object.  The 
abe0: 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65  SQLite core neve
abf0: 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68  r looks.** at th
ac00: 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65  e internal repre
ac10: 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20  sentation of an 
ac20: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e  [sqlite3_mutex].
ac30: 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61    It only.** dea
ac40: 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73  ls with pointers
ac50: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
ac60: 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a  _mutex] object..
ac70: 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72  **.** Mutexes ar
ac80: 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20  e created using 
ac90: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61  [sqlite3_mutex_a
aca0: 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65  lloc()]..*/.type
acb0: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
acc0: 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33  e3_mutex sqlite3
acd0: 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _mutex;../*.** C
ace0: 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65  API3REF: OS Inte
acf0: 72 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a  rface Object.**.
ad00: 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
ad10: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  f the sqlite3_vf
ad20: 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73  s object defines
ad30: 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62   the interface b
ad40: 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51  etween.** the SQ
ad50: 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68  Lite core and th
ad60: 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65  e underlying ope
ad70: 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20  rating system.  
ad80: 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20  The "vfs".** in 
ad90: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
ada0: 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f  object stands fo
adb0: 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20  r "virtual file 
adc0: 73 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a  system".  See.**
add0: 20 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20   the [VFS | VFS 
ade0: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66  documentation] f
adf0: 6f 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72  or further infor
ae00: 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  mation..**.** Th
ae10: 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69  e value of the i
ae20: 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73  Version field is
ae30: 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74   initially 1 but
ae40: 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 69   may be larger i
ae50: 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73  n.** future vers
ae60: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20  ions of SQLite. 
ae70: 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   Additional fiel
ae80: 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64  ds may be append
ae90: 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62  ed to this.** ob
aea0: 6a 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 56  ject when the iV
aeb0: 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20  ersion value is 
aec0: 69 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65  increased.  Note
aed0: 20 74 68 61 74 20 74 68 65 20 73 74 72 75 63 74   that the struct
aee0: 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71  ure.** of the sq
aef0: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74  lite3_vfs object
af00: 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20   changes in the 
af10: 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77  transaction betw
af20: 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65  een.** SQLite ve
af30: 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20  rsion 3.5.9 and 
af40: 33 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68  3.6.0 and yet th
af50: 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64  e iVersion field
af60: 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69   was not.** modi
af70: 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fied..**.** The 
af80: 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69  szOsFile field i
af90: 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  s the size of th
afa0: 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71  e subclassed [sq
afb0: 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73  lite3_file].** s
afc0: 74 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79  tructure used by
afd0: 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61   this VFS.  mxPa
afe0: 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61  thname is the ma
aff0: 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a  ximum length of.
b000: 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e  ** a pathname in
b010: 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a   this VFS..**.**
b020: 20 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69   Registered sqli
b030: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20  te3_vfs objects 
b040: 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69  are kept on a li
b050: 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64  nked list formed
b060: 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74   by.** the pNext
b070: 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b   pointer.  The [
b080: 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69  sqlite3_vfs_regi
b090: 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  ster()].** and [
b0a0: 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65  sqlite3_vfs_unre
b0b0: 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66  gister()] interf
b0c0: 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73  aces manage this
b0d0: 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68   list.** in a th
b0e0: 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20  read-safe way.  
b0f0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  The [sqlite3_vfs
b100: 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61  _find()] interfa
b110: 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74  ce.** searches t
b120: 68 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65  he list.  Neithe
b130: 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
b140: 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56  n code nor the V
b150: 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  FS.** implementa
b160: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20  tion should use 
b170: 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65  the pNext pointe
b180: 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65  r..**.** The pNe
b190: 78 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 20  xt field is the 
b1a0: 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68  only field in th
b1b0: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a  e sqlite3_vfs.**
b1c0: 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20   structure that 
b1d0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72  SQLite will ever
b1e0: 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65   modify.  SQLite
b1f0: 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73   will only acces
b200: 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74  s.** or modify t
b210: 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20  his field while 
b220: 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63  holding a partic
b230: 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65  ular static mute
b240: 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  x..** The applic
b250: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76  ation should nev
b260: 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69  er modify anythi
b270: 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71  ng within the sq
b280: 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a  lite3_vfs.** obj
b290: 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a  ect once the obj
b2a0: 65 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67  ect has been reg
b2b0: 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  istered..**.** T
b2c0: 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68  he zName field h
b2d0: 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  olds the name of
b2e0: 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e   the VFS module.
b2f0: 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a    The name must.
b300: 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72  ** be unique acr
b310: 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75  oss all VFS modu
b320: 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c  les..**.** [[sql
b330: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d  ite3_vfs.xOpen]]
b340: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72  .** ^SQLite guar
b350: 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
b360: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  zFilename parame
b370: 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20  ter to xOpen.** 
b380: 69 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c  is either a NULL
b390: 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69   pointer or stri
b3a0: 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  ng obtained.** f
b3b0: 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d  rom xFullPathnam
b3c0: 65 28 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69  e() with an opti
b3d0: 6f 6e 61 6c 20 73 75 66 66 69 78 20 61 64 64 65  onal suffix adde
b3e0: 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66  d..** ^If a suff
b3f0: 69 78 20 69 73 20 61 64 64 65 64 20 74 6f 20 74  ix is added to t
b400: 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72  he zFilename par
b410: 61 6d 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a  ameter, it will.
b420: 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20  ** consist of a 
b430: 73 69 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61  single "-" chara
b440: 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79  cter followed by
b450: 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a   no more than.**
b460: 20 31 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63   11 alphanumeric
b470: 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72   and/or "-" char
b480: 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69  acters..** ^SQLi
b490: 74 65 20 66 75 72 74 68 65 72 20 67 75 61 72 61  te further guara
b4a0: 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68  ntees that.** th
b4b0: 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65  e string will be
b4c0: 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61   valid and uncha
b4d0: 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73  nged until xClos
b4e0: 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64  e() is.** called
b4f0: 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65  . Because of the
b500: 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e   previous senten
b510: 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  ce,.** the [sqli
b520: 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61  te3_file] can sa
b530: 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69  fely store a poi
b540: 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66  nter to the.** f
b550: 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65  ilename if it ne
b560: 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20  eds to remember 
b570: 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72  the filename for
b580: 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a   some reason..**
b590: 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d   If the zFilenam
b5a0: 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78  e parameter to x
b5b0: 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70  Open is a NULL p
b5c0: 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65  ointer then xOpe
b5d0: 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74  n.** must invent
b5e0: 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61   its own tempora
b5f0: 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20  ry name for the 
b600: 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72  file.  ^Whenever
b610: 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61   the .** xFilena
b620: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  me parameter is 
b630: 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73  NULL it will als
b640: 6f 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68  o be the case th
b650: 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20  at the.** flags 
b660: 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69  parameter will i
b670: 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f  nclude [SQLITE_O
b680: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
b690: 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c  E]..**.** The fl
b6a0: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
b6b0: 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73  xOpen() includes
b6c0: 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e   all bits set in
b6d0: 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72  .** the flags ar
b6e0: 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
b6f0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20  e3_open_v2()].  
b700: 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f  Or if [sqlite3_o
b710: 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71  pen()].** or [sq
b720: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20  lite3_open16()] 
b730: 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c  is used, then fl
b740: 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20  ags includes at 
b750: 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45  least.** [SQLITE
b760: 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
b770: 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   | [SQLITE_OPEN_
b780: 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20  CREATE]. .** If 
b790: 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20  xOpen() opens a 
b7a0: 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74  file read-only t
b7b0: 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75  hen it sets *pOu
b7c0: 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63  tFlags to.** inc
b7d0: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  lude [SQLITE_OPE
b7e0: 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74  N_READONLY].  Ot
b7f0: 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75  her bits in *pOu
b800: 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65  tFlags may be se
b810: 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74  t..**.** ^(SQLit
b820: 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20  e will also add 
b830: 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
b840: 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68  wing flags to th
b850: 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c  e xOpen().** cal
b860: 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  l, depending on 
b870: 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67  the object being
b880: 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c   opened:.**.** <
b890: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  ul>.** <li>  [SQ
b8a0: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
b8b0: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
b8c0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f  ITE_OPEN_MAIN_JO
b8d0: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
b8e0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d  [SQLITE_OPEN_TEM
b8f0: 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  P_DB].** <li>  [
b900: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
b910: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  _JOURNAL].** <li
b920: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
b930: 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a  TRANSIENT_DB].**
b940: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
b950: 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a  PEN_SUBJOURNAL].
b960: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
b970: 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55  _OPEN_MASTER_JOU
b980: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
b990: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d  SQLITE_OPEN_WAL]
b9a0: 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  .** </ul>)^.**.*
b9b0: 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69  * The file I/O i
b9c0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61  mplementation ca
b9d0: 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74  n use the object
b9e0: 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a   type flags to.*
b9f0: 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77 61 79  * change the way
ba00: 20 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66   it deals with f
ba10: 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70  iles.  For examp
ba20: 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  le, an applicati
ba30: 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20  on.** that does 
ba40: 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63  not care about c
ba50: 72 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72  rash recovery or
ba60: 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20   rollback might 
ba70: 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e  make.** the open
ba80: 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69   of a journal fi
ba90: 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69  le a no-op.  Wri
baa0: 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72  tes to this jour
bab0: 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73  nal would.** als
bac0: 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64  o be no-ops, and
bad0: 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   any attempt to 
bae0: 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c  read the journal
baf0: 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a   would return.**
bb00: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20   SQLITE_IOERR.  
bb10: 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  Or the implement
bb20: 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f  ation might reco
bb30: 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61 74  gnize that a dat
bb40: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69  abase.** file wi
bb50: 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65  ll be doing page
bb60: 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20  -aligned sector 
bb70: 72 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73  reads and writes
bb80: 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20   in a random.** 
bb90: 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70  order and set up
bba0: 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74   its I/O subsyst
bbb0: 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a  em accordingly..
bbc0: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67  **.** SQLite mig
bbd0: 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20  ht also add one 
bbe0: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
bbf0: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f   flags to the xO
bc00: 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a  pen method:.**.*
bc10: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
bc20: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
bc30: 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c  TEONCLOSE].** <l
bc40: 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  i> [SQLITE_OPEN_
bc50: 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f  EXCLUSIVE].** </
bc60: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  ul>.**.** The [S
bc70: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
bc80: 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d  EONCLOSE] flag m
bc90: 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68  eans the file sh
bca0: 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74  ould be.** delet
bcb0: 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c  ed when it is cl
bcc0: 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c  osed.  ^The [SQL
bcd0: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
bce0: 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20  NCLOSE].** will 
bcf0: 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20  be set for TEMP 
bd00: 64 61 74 61 62 61 73 65 73 20 61 6e 64 20 74 68  databases and th
bd10: 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72  eir journals, tr
bd20: 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62  ansient.** datab
bd30: 61 73 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75  ases, and subjou
bd40: 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rnals..**.** ^Th
bd50: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  e [SQLITE_OPEN_E
bd60: 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69  XCLUSIVE] flag i
bd70: 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e  s always used in
bd80: 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20   conjunction.** 
bd90: 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
bda0: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c  _OPEN_CREATE] fl
bdb0: 61 67 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f  ag, which are bo
bdc0: 74 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61  th directly.** a
bdd0: 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20  nalogous to the 
bde0: 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45  O_EXCL and O_CRE
bdf0: 41 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20  AT flags of the 
be00: 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20  POSIX open().** 
be10: 41 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45  API.  The SQLITE
be20: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20  _OPEN_EXCLUSIVE 
be30: 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65  flag, when paire
be40: 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53  d with the .** S
be50: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
be60: 45 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e  E, is used to in
be70: 64 69 63 61 74 65 20 74 68 61 74 20 66 69 6c 65  dicate that file
be80: 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a   should always.*
be90: 2a 20 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e  * be created, an
bea0: 64 20 74 68 61 74 20 69 74 20 69 73 20 61 6e 20  d that it is an 
beb0: 65 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65  error if it alre
bec0: 61 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49  ady exists..** I
bed0: 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20  t is <i>not</i> 
bee0: 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65  used to indicate
bef0: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
bf00: 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66   be opened .** f
bf10: 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63  or exclusive acc
bf20: 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c  ess..**.** ^At l
bf30: 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79  east szOsFile by
bf40: 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72  tes of memory ar
bf50: 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53  e allocated by S
bf60: 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64  QLite.** to hold
bf70: 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66   the  [sqlite3_f
bf80: 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70  ile] structure p
bf90: 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69  assed as the thi
bfa0: 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74  rd.** argument t
bfb0: 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f  o xOpen.  The xO
bfc0: 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20  pen method does 
bfd0: 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61  not have to.** a
bfe0: 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72 75  llocate the stru
bff0: 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64  cture; it should
c000: 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e   just fill it in
c010: 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20  .  Note that.** 
c020: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
c030: 20 6d 75 73 74 20 73 65 74 20 74 68 65 20 73 71   must set the sq
c040: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
c050: 6f 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a  ods to either.**
c060: 20 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65   a valid [sqlite
c070: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
c080: 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e  ject or to NULL.
c090: 20 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a    xOpen must do.
c0a0: 2a 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66 20  ** this even if 
c0b0: 74 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20  the open fails. 
c0c0: 20 53 51 4c 69 74 65 20 65 78 70 65 63 74 73 20   SQLite expects 
c0d0: 74 68 61 74 20 74 68 65 20 73 71 6c 69 74 65 33  that the sqlite3
c0e0: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a  _file.pMethods.*
c0f0: 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62  * element will b
c100: 65 20 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f  e valid after xO
c110: 70 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61  pen returns rega
c120: 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75  rdless of the su
c130: 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c  ccess.** or fail
c140: 75 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e  ure of the xOpen
c150: 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73   call..**.** [[s
c160: 71 6c 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65  qlite3_vfs.xAcce
c170: 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61  ss]].** ^The fla
c180: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
c190: 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20  Access() may be 
c1a0: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45  [SQLITE_ACCESS_E
c1b0: 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73  XISTS].** to tes
c1c0: 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65  t for the existe
c1d0: 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f  nce of a file, o
c1e0: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  r [SQLITE_ACCESS
c1f0: 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a  _READWRITE] to.*
c200: 2a 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61  * test whether a
c210: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
c220: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20  e and writable, 
c230: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  or [SQLITE_ACCES
c240: 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65  S_READ].** to te
c250: 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c  st whether a fil
c260: 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65  e is at least re
c270: 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69  adable.   The fi
c280: 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64  le can be a.** d
c290: 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20  irectory..**.** 
c2a0: 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77  ^SQLite will alw
c2b0: 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20  ays allocate at 
c2c0: 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65  least mxPathname
c2d0: 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65  +1 bytes for the
c2e0: 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65  .** output buffe
c2f0: 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e  r xFullPathname.
c300: 20 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65    The exact size
c310: 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62   of the output b
c320: 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f  uffer.** is also
c330: 20 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72   passed as a par
c340: 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20  ameter to both  
c350: 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20  methods. If the 
c360: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a  output buffer.**
c370: 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e   is not large en
c380: 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41  ough, [SQLITE_CA
c390: 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62  NTOPEN] should b
c3a0: 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63  e returned. Sinc
c3b0: 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e  e this is.** han
c3c0: 64 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20  dled as a fatal 
c3d0: 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c  error by SQLite,
c3e0: 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74   vfs implementat
c3f0: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65  ions should ende
c400: 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65  avor.** to preve
c410: 6e 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69  nt this by setti
c420: 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f  ng mxPathname to
c430: 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20   a sufficiently 
c440: 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a  large value..**.
c450: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65  ** The xRandomne
c460: 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20  ss(), xSleep(), 
c470: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20  xCurrentTime(), 
c480: 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65  and xCurrentTime
c490: 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72  Int64().** inter
c4a0: 66 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74  faces are not st
c4b0: 72 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66  rictly a part of
c4c0: 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c   the filesystem,
c4d0: 20 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a   but they are.**
c4e0: 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65   included in the
c4f0: 20 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66   VFS structure f
c500: 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e  or completeness.
c510: 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e  .** The xRandomn
c520: 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61  ess() function a
c530: 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72  ttempts to retur
c540: 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a  n nBytes bytes.*
c550: 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74  * of good-qualit
c560: 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  y randomness int
c570: 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74  o zOut.  The ret
c580: 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20  urn value is.** 
c590: 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65  the actual numbe
c5a0: 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61  r of bytes of ra
c5b0: 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65  ndomness obtaine
c5c0: 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70  d..** The xSleep
c5d0: 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73  () method causes
c5e0: 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72   the calling thr
c5f0: 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72  ead to sleep for
c600: 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65   at.** least the
c610: 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f   number of micro
c620: 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20  seconds given.  
c630: 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d  ^The xCurrentTim
c640: 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65  e().** method re
c650: 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44  turns a Julian D
c660: 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68  ay Number for th
c670: 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61  e current date a
c680: 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20  nd time as.** a 
c690: 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
c6a0: 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43  alue..** ^The xC
c6b0: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
c6c0: 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  ) method returns
c6d0: 2c 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c  , as an integer,
c6e0: 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44   the Julian.** D
c6f0: 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70  ay Number multip
c700: 6c 69 65 64 20 62 79 20 38 36 34 30 30 30 30 30  lied by 86400000
c710: 20 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20   (the number of 
c720: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20  milliseconds in 
c730: 0a 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61  .** a 24-hour da
c740: 79 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65  y).  .** ^SQLite
c750: 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43   will use the xC
c760: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
c770: 29 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20  ) method to get 
c780: 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64  the current.** d
c790: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20  ate and time if 
c7a0: 74 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61  that method is a
c7b0: 76 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65  vailable (if iVe
c7c0: 72 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a  rsion is 2 or .*
c7d0: 2a 20 67 72 65 61 74 65 72 20 61 6e 64 20 74 68  * greater and th
c7e0: 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74  e function point
c7f0: 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20  er is not NULL) 
c800: 61 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61  and will fall ba
c810: 63 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e  ck.** to xCurren
c820: 74 54 69 6d 65 28 29 20 69 66 20 78 43 75 72 72  tTime() if xCurr
c830: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69  entTimeInt64() i
c840: 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a  s unavailable..*
c850: 2a 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79  *.** ^The xSetSy
c860: 73 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74  stemCall(), xGet
c870: 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e  SystemCall(), an
c880: 64 20 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c  d xNestSystemCal
c890: 6c 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  l() interfaces.*
c8a0: 2a 20 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62  * are not used b
c8b0: 79 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72  y the SQLite cor
c8c0: 65 2e 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e  e.  These option
c8d0: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  al interfaces ar
c8e0: 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79  e provided.** by
c8f0: 20 73 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66   some VFSes to f
c900: 61 63 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e  acilitate testin
c910: 67 20 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64  g of the VFS cod
c920: 65 2e 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67  e. By overriding
c930: 20 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c   .** system call
c940: 73 20 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73  s with functions
c950: 20 75 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72   under its contr
c960: 6f 6c 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72  ol, a test progr
c970: 61 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61  am can.** simula
c980: 74 65 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72  te faults and er
c990: 72 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74  ror conditions t
c9a0: 68 61 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77  hat would otherw
c9b0: 69 73 65 20 62 65 20 64 69 66 66 69 63 75 6c 74  ise be difficult
c9c0: 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c  .** or impossibl
c9d0: 65 20 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68  e to induce.  Th
c9e0: 65 20 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20  e set of system 
c9f0: 63 61 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62  calls that can b
ca00: 65 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20  e overridden.** 
ca10: 76 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20  varies from one 
ca20: 56 46 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20  VFS to another, 
ca30: 61 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72  and from one ver
ca40: 73 69 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65  sion of the same
ca50: 20 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e   VFS to the.** n
ca60: 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ext.  Applicatio
ca70: 6e 73 20 74 68 61 74 20 75 73 65 20 74 68 65 73  ns that use thes
ca80: 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73  e interfaces mus
ca90: 74 20 62 65 20 70 72 65 70 61 72 65 64 20 66 6f  t be prepared fo
caa0: 72 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20  r any.** or all 
cab0: 6f 66 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  of these interfa
cac0: 63 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f  ces to be NULL o
cad0: 72 20 66 6f 72 20 74 68 65 69 72 20 62 65 68 61  r for their beha
cae0: 76 69 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a  vior to change.*
caf0: 2a 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61  * from one relea
cb00: 73 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20  se to the next. 
cb10: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75   Applications mu
cb20: 73 74 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74  st not attempt t
cb30: 6f 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20  o access.** any 
cb40: 6f 66 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73  of these methods
cb50: 20 69 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e   if the iVersion
cb60: 20 6f 66 20 74 68 65 20 56 46 53 20 69 73 20 6c   of the VFS is l
cb70: 65 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74  ess than 3..*/.t
cb80: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
cb90: 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65  lite3_vfs sqlite
cba0: 33 5f 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76  3_vfs;.typedef v
cbb0: 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79  oid (*sqlite3_sy
cbc0: 73 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29  scall_ptr)(void)
cbd0: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
cbe0: 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65  _vfs {.  int iVe
cbf0: 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20  rsion;          
cc00: 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76    /* Structure v
cc10: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63  ersion number (c
cc20: 75 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20  urrently 3) */. 
cc30: 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20   int szOsFile;  
cc40: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a            /* Siz
cc50: 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20  e of subclassed 
cc60: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a  sqlite3_file */.
cc70: 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65    int mxPathname
cc80: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61  ;          /* Ma
cc90: 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e  ximum file pathn
cca0: 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20  ame length */.  
ccb0: 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65  sqlite3_vfs *pNe
ccc0: 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74  xt;      /* Next
ccd0: 20 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20   registered VFS 
cce0: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
ccf0: 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a  *zName;       /*
cd00: 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69   Name of this vi
cd10: 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65  rtual file syste
cd20: 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70  m */.  void *pAp
cd30: 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20  pData;          
cd40: 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70  /* Pointer to ap
cd50: 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66  plication-specif
cd60: 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74  ic data */.  int
cd70: 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65   (*xOpen)(sqlite
cd80: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
cd90: 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74  ar *zName, sqlit
cda0: 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20  e3_file*,.      
cdb0: 20 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61           int fla
cdc0: 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61  gs, int *pOutFla
cdd0: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65  gs);.  int (*xDe
cde0: 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lete)(sqlite3_vf
cdf0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
ce00: 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44  zName, int syncD
ce10: 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63  ir);.  int (*xAc
ce20: 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66  cess)(sqlite3_vf
ce30: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
ce40: 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73  zName, int flags
ce50: 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b  , int *pResOut);
ce60: 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61  .  int (*xFullPa
ce70: 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f  thname)(sqlite3_
ce80: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
ce90: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75   *zName, int nOu
cea0: 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a  t, char *zOut);.
ceb0: 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65    void *(*xDlOpe
cec0: 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  n)(sqlite3_vfs*,
ced0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69   const char *zFi
cee0: 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20  lename);.  void 
cef0: 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69  (*xDlError)(sqli
cf00: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42  te3_vfs*, int nB
cf10: 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d  yte, char *zErrM
cf20: 73 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a  sg);.  void (*(*
cf30: 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f  xDlSym)(sqlite3_
cf40: 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73  vfs*,void*, cons
cf50: 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29  t char *zSymbol)
cf60: 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20  )(void);.  void 
cf70: 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69  (*xDlClose)(sqli
cf80: 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29  te3_vfs*, void*)
cf90: 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f  ;.  int (*xRando
cfa0: 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76  mness)(sqlite3_v
cfb0: 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  fs*, int nByte, 
cfc0: 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69  char *zOut);.  i
cfd0: 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c  nt (*xSleep)(sql
cfe0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d  ite3_vfs*, int m
cff0: 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20  icroseconds);.  
d000: 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69  int (*xCurrentTi
d010: 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  me)(sqlite3_vfs*
d020: 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e  , double*);.  in
d030: 74 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f  t (*xGetLastErro
d040: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  r)(sqlite3_vfs*,
d050: 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20   int, char *);. 
d060: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
d070: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
d080: 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74  n version 1 of t
d090: 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62  he sqlite_vfs ob
d0a0: 6a 65 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69  ject.  ** defini
d0b0: 74 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61  tion.  Those tha
d0c0: 74 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64  t follow are add
d0d0: 65 64 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20  ed in version 2 
d0e0: 6f 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20  or later.  */.  
d0f0: 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69  int (*xCurrentTi
d100: 6d 65 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33  meInt64)(sqlite3
d110: 5f 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69  _vfs*, sqlite3_i
d120: 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a  nt64*);.  /*.  *
d130: 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62  * The methods ab
d140: 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69  ove are in versi
d150: 6f 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74  ons 1 and 2 of t
d160: 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62  he sqlite_vfs ob
d170: 6a 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65  ject..  ** Those
d180: 20 62 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76   below are for v
d190: 65 72 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65  ersion 3 and gre
d1a0: 61 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74  ater..  */.  int
d1b0: 20 28 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c   (*xSetSystemCal
d1c0: 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  l)(sqlite3_vfs*,
d1d0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
d1e0: 6d 65 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63  me, sqlite3_sysc
d1f0: 61 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69  all_ptr);.  sqli
d200: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20  te3_syscall_ptr 
d210: 28 2a 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c  (*xGetSystemCall
d220: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
d230: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
d240: 65 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  e);.  const char
d250: 20 2a 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43   *(*xNextSystemC
d260: 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73  all)(sqlite3_vfs
d270: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
d280: 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a  Name);.  /*.  **
d290: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f   The methods abo
d2a0: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f  ve are in versio
d2b0: 6e 73 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f  ns 1 through 3 o
d2c0: 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73  f the sqlite_vfs
d2d0: 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65   object..  ** Ne
d2e0: 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20  w fields may be 
d2f0: 61 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75  appended in figu
d300: 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68  re versions.  Th
d310: 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20  e iVersion.  ** 
d320: 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65  value will incre
d330: 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68  ment whenever th
d340: 69 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a  is happens. .  *
d350: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
d360: 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20  3REF: Flags for 
d370: 74 68 65 20 78 41 63 63 65 73 73 20 56 46 53 20  the xAccess VFS 
d380: 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65  method.**.** The
d390: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
d3a0: 61 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64  ants can be used
d3b0: 20 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61   as the third pa
d3c0: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68  rameter to.** th
d3d0: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
d3e0: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
d3f0: 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68  vfs] object.  Th
d400: 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20  ey determine.** 
d410: 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72  what kind of per
d420: 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63  missions the xAc
d430: 63 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c  cess method is l
d440: 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57  ooking for..** W
d450: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
d460: 53 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78 41  S_EXISTS, the xA
d470: 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20  ccess method.** 
d480: 73 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68  simply checks wh
d490: 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 65  ether the file e
d4a0: 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53  xists..** With S
d4b0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
d4c0: 44 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63  DWRITE, the xAcc
d4d0: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68  ess method.** ch
d4e0: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
d4f0: 20 6e 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79   named directory
d500: 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c   is both readabl
d510: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a  e and writable.*
d520: 2a 20 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64  * (in other word
d530: 73 2c 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20  s, if files can 
d540: 62 65 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65  be added, remove
d550: 64 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77  d, and renamed w
d560: 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72  ithin.** the dir
d570: 65 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20  ectory)..** The 
d580: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
d590: 41 44 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74  ADWRITE constant
d5a0: 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73   is currently us
d5b0: 65 64 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a  ed only by the.*
d5c0: 2a 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69  * [temp_store_di
d5d0: 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c  rectory pragma],
d5e0: 20 74 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75   though this cou
d5f0: 6c 64 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66  ld change in a f
d600: 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65  uture.** release
d610: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57   of SQLite..** W
d620: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
d630: 53 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63 63  S_READ, the xAcc
d640: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68  ess method.** ch
d650: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
d660: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
d670: 65 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41  e.  The SQLITE_A
d680: 43 43 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74  CCESS_READ const
d690: 61 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e  ant is.** curren
d6a0: 74 6c 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75  tly unused, thou
d6b0: 67 68 20 69 74 20 6d 69 67 68 74 20 62 65 20 75  gh it might be u
d6c0: 73 65 64 20 69 6e 20 61 20 66 75 74 75 72 65 20  sed in a future 
d6d0: 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51  release of.** SQ
d6e0: 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  Lite..*/.#define
d6f0: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45   SQLITE_ACCESS_E
d700: 58 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69  XISTS    0.#defi
d710: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
d720: 5f 52 45 41 44 57 52 49 54 45 20 31 20 20 20 2f  _READWRITE 1   /
d730: 2a 20 55 73 65 64 20 62 79 20 50 52 41 47 4d 41  * Used by PRAGMA
d740: 20 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65   temp_store_dire
d750: 63 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65  ctory */.#define
d760: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
d770: 45 41 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20  EAD      2   /* 
d780: 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  Unused */../*.**
d790: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73   CAPI3REF: Flags
d7a0: 20 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63   for the xShmLoc
d7b0: 6b 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a  k VFS method.**.
d7c0: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  ** These integer
d7d0: 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e   constants defin
d7e0: 65 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f  e the various lo
d7f0: 63 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73  cking operations
d800: 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74  .** allowed by t
d810: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
d820: 6f 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69  od of [sqlite3_i
d830: 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65  o_methods].  The
d840: 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72  .** following ar
d850: 65 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c  e the only legal
d860: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66   combinations of
d870: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a   flags to the.**
d880: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
d890: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
d8a0: 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d  <li>  SQLITE_SHM
d8b0: 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53  _LOCK | SQLITE_S
d8c0: 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69  HM_SHARED.** <li
d8d0: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  >  SQLITE_SHM_LO
d8e0: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
d8f0: 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69  EXCLUSIVE.** <li
d900: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e  >  SQLITE_SHM_UN
d910: 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
d920: 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e  M_SHARED.** <li>
d930: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c    SQLITE_SHM_UNL
d940: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
d950: 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f  _EXCLUSIVE.** </
d960: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75  ul>.**.** When u
d970: 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61  nlocking, the sa
d980: 6d 65 20 53 48 41 52 45 44 20 6f 72 20 45 58 43  me SHARED or EXC
d990: 4c 55 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74  LUSIVE flag must
d9a0: 20 62 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a   be supplied as.
d9b0: 2a 2a 20 77 61 73 20 67 69 76 65 6e 20 6e 6f 20  ** was given no 
d9c0: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
d9d0: 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20  g lock.  .**.** 
d9e0: 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74  The xShmLock met
d9f0: 68 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69  hod can transiti
da00: 6f 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63  on between unloc
da10: 6b 65 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f  ked and SHARED o
da20: 72 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c  r.** between unl
da30: 6f 63 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53  ocked and EXCLUS
da40: 49 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20  IVE.  It cannot 
da50: 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65  transition betwe
da60: 65 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64  en SHARED.** and
da70: 20 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23   EXCLUSIVE..*/.#
da80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
da90: 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31  M_UNLOCK       1
daa0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
dab0: 53 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20  SHM_LOCK        
dac0: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
dad0: 45 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20  E_SHM_SHARED    
dae0: 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
daf0: 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
db00: 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41  E    8../*.** CA
db10: 50 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20  PI3REF: Maximum 
db20: 78 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a  xShmLock index.*
db30: 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63  *.** The xShmLoc
db40: 6b 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c  k method on [sql
db50: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
db60: 20 6d 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a   may use values.
db70: 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64  ** between 0 and
db80: 20 74 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e   this upper boun
db90: 64 20 61 73 20 69 74 73 20 22 6f 66 66 73 65 74  d as its "offset
dba0: 22 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54  " argument..** T
dbb0: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77  he SQLite core w
dbc0: 69 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70  ill never attemp
dbd0: 74 20 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20  t to acquire or 
dbe0: 72 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63  release a.** loc
dbf0: 6b 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69  k outside of thi
dc00: 73 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69  s range.*/.#defi
dc10: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c  ne SQLITE_SHM_NL
dc20: 4f 43 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f  OCK        8.../
dc30: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
dc40: 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51  nitialize The SQ
dc50: 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a  Lite Library.**.
dc60: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
dc70: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
dc80: 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73  tine initializes
dc90: 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c   the.** SQLite l
dca0: 69 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71  ibrary.  ^The sq
dcb0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
dcc0: 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c   routine.** deal
dcd0: 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f  locates any reso
dce0: 75 72 63 65 73 20 74 68 61 74 20 77 65 72 65 20  urces that were 
dcf0: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c  allocated by sql
dd00: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
dd10: 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  )..** These rout
dd20: 69 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e 65  ines are designe
dd30: 64 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63  d to aid in proc
dd40: 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ess initializati
dd50: 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f  on and.** shutdo
dd60: 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73  wn on embedded s
dd70: 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61  ystems.  Worksta
dd80: 74 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  tion application
dd90: 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74  s using.** SQLit
dda0: 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f  e normally do no
ddb0: 74 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65  t need to invoke
ddc0: 20 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65   either of these
ddd0: 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
dde0: 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   A call to sqlit
ddf0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
de00: 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65  is an "effective
de10: 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a  " call if it is.
de20: 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d  ** the first tim
de30: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
de40: 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
de50: 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66  d during the lif
de60: 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20  etime of.** the 
de70: 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69  process, or if i
de80: 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74  t is the first t
de90: 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ime sqlite3_init
dea0: 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
deb0: 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  ked.** following
dec0: 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   a call to sqlit
ded0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
dee0: 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74  ^(Only an effect
def0: 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73  ive call.** of s
df00: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
df10: 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69  e() does any ini
df20: 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c  tialization.  Al
df30: 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a  l other calls.**
df40: 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f   are harmless no
df50: 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20  -ops.)^.**.** A 
df60: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
df70: 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e  shutdown() is an
df80: 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c   "effective" cal
df90: 6c 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66  l if it is the f
dfa0: 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20  irst.** call to 
dfb0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
dfc0: 28 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73  () since the las
dfd0: 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  t sqlite3_initia
dfe0: 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a  lize().  ^(Only.
dff0: 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20  ** an effective 
e000: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
e010: 73 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20  shutdown() does 
e020: 61 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61  any deinitializa
e030: 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68  tion..** All oth
e040: 65 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74  er valid calls t
e050: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
e060: 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73  wn() are harmles
e070: 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a  s no-ops.)^.**.*
e080: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
e090: 69 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72  itialize() inter
e0a0: 66 61 63 65 20 69 73 20 74 68 72 65 61 64 73 61  face is threadsa
e0b0: 66 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f  fe, but sqlite3_
e0c0: 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73  shutdown().** is
e0d0: 20 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74   not.  The sqlit
e0e0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e  e3_shutdown() in
e0f0: 74 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c  terface must onl
e100: 79 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  y be called from
e110: 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72   a.** single thr
e120: 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b  ead.  All open [
e130: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
e140: 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c  ions] must be cl
e150: 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20  osed and all.** 
e160: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 73  other SQLite res
e170: 6f 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 64  ources must be d
e180: 65 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72  eallocated prior
e190: 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20   to invoking.** 
e1a0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
e1b0: 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20  ()..**.** Among 
e1c0: 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73  other things, ^s
e1d0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
e1e0: 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a  e() will invoke.
e1f0: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  ** sqlite3_os_in
e200: 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79  it().  Similarly
e210: 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64  , ^sqlite3_shutd
e220: 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e  own().** will in
e230: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f  voke sqlite3_os_
e240: 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  end()..**.** ^Th
e250: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
e260: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72  lize() routine r
e270: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
e280: 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a  K] on success..*
e290: 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72  * ^If for some r
e2a0: 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69  eason, sqlite3_i
e2b0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75  nitialize() is u
e2c0: 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c  nable to initial
e2d0: 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61  ize.** the libra
e2e0: 72 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69  ry (perhaps it i
e2f0: 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
e300: 63 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65  cate a needed re
e310: 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61  source such.** a
e320: 73 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65  s a mutex) it re
e330: 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20  turns an [error 
e340: 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e  code] other than
e350: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
e360: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
e370: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
e380: 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20  utine is called 
e390: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61  internally by ma
e3a0: 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69  ny other.** SQLi
e3b0: 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f  te interfaces so
e3c0: 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61   that an applica
e3d0: 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65  tion usually doe
e3e0: 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a  s not need to.**
e3f0: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
e400: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72  initialize() dir
e410: 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d  ectly.  For exam
e420: 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ple, [sqlite3_op
e430: 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73  en()].** calls s
e440: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
e450: 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74  e() so the SQLit
e460: 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62  e library will b
e470: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  e automatically.
e480: 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77  ** initialized w
e490: 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  hen [sqlite3_ope
e4a0: 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69  n()] is called i
e4b0: 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20  f it has not be 
e4c0: 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61  initialized.** a
e4d0: 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65  lready.  ^Howeve
e4e0: 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  r, if SQLite is 
e4f0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
e500: 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  e [SQLITE_OMIT_A
e510: 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70  UTOINIT].** comp
e520: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c  ile-time option,
e530: 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61   then the automa
e540: 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  tic calls to sql
e550: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
e560: 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64  ).** are omitted
e570: 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61   and the applica
e580: 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73  tion must call s
e590: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
e5a0: 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  e() directly.** 
e5b0: 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61  prior to using a
e5c0: 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ny other SQLite 
e5d0: 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20  interface.  For 
e5e0: 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c  maximum portabil
e5f0: 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65  ity,.** it is re
e600: 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61  commended that a
e610: 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61  pplications alwa
e620: 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ys invoke sqlite
e630: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a  3_initialize().*
e640: 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72  * directly prior
e650: 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74   to using any ot
e660: 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
e670: 66 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65  face.  Future re
e680: 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c  leases.** of SQL
e690: 69 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20  ite may require 
e6a0: 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20  this.  In other 
e6b0: 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76  words, the behav
e6c0: 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a  ior exhibited.**
e6d0: 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
e6e0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53  compiled with [S
e6f0: 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49  QLITE_OMIT_AUTOI
e700: 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d  NIT] might becom
e710: 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74  e the.** default
e720: 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d   behavior in som
e730: 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  e future release
e740: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
e750: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73  * The sqlite3_os
e760: 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20  _init() routine 
e770: 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73  does operating-s
e780: 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a  ystem specific.*
e790: 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  * initialization
e7a0: 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c   of the SQLite l
e7b0: 69 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c  ibrary.  The sql
e7c0: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
e7d0: 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20   routine undoes 
e7e0: 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71  the effect of sq
e7f0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e  lite3_os_init().
e800: 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a    Typical tasks.
e810: 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20  ** performed by 
e820: 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69  these routines i
e830: 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f  nclude allocatio
e840: 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f  n or deallocatio
e850: 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72  n.** of static r
e860: 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61  esources, initia
e870: 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62  lization of glob
e880: 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a  al variables,.**
e890: 20 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65   setting up a de
e8a0: 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
e8b0: 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73  fs] module, or s
e8c0: 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64  etting up.** a d
e8d0: 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61  efault configura
e8e0: 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69  tion using [sqli
e8f0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a  te3_config()]..*
e900: 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
e910: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65  tion should neve
e920: 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20  r invoke either 
e930: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
e940: 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
e950: 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c  os_end() directl
e960: 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  y.  The applicat
e970: 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20  ion should only 
e980: 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
e990: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61  3_initialize() a
e9a0: 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  nd sqlite3_shutd
e9b0: 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69  own().  The sqli
e9c0: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a  te3_os_init().**
e9d0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61   interface is ca
e9e0: 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c  lled automatical
e9f0: 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ly by sqlite3_in
ea00: 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a  itialize() and.*
ea10: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  * sqlite3_os_end
ea20: 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20  () is called by 
ea30: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
ea40: 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65  ().  Appropriate
ea50: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
ea60: 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  ons for sqlite3_
ea70: 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71  os_init() and sq
ea80: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
ea90: 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f  * are built into
eaa0: 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20   SQLite when it 
eab0: 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20  is compiled for 
eac0: 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f  Unix, Windows, o
ead0: 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20  r OS/2..** When 
eae0: 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c  [custom builds |
eaf0: 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72   built for other
eb00: 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28   platforms].** (
eb10: 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54  using the [SQLIT
eb20: 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f  E_OS_OTHER=1] co
eb30: 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70  mpile-time.** op
eb40: 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63  tion) the applic
eb50: 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c  ation must suppl
eb60: 79 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70  y a suitable imp
eb70: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a  lementation for.
eb80: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  ** sqlite3_os_in
eb90: 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  it() and sqlite3
eba0: 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61  _os_end().  An a
ebb0: 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c  pplication-suppl
ebc0: 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ied.** implement
ebd0: 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
ebe0: 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71  _os_init() or sq
ebf0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
ec00: 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53  * must return [S
ec10: 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
ec20: 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74  cess and some ot
ec30: 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  her [error code]
ec40: 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65   upon.** failure
ec50: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
ec60: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64  _initialize(void
ec70: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  );.int sqlite3_s
ec80: 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69  hutdown(void);.i
ec90: 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  nt sqlite3_os_in
eca0: 69 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  it(void);.int sq
ecb0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69  lite3_os_end(voi
ecc0: 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  d);../*.** CAPI3
ecd0: 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67  REF: Configuring
ece0: 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72   The SQLite Libr
ecf0: 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ary.**.** The sq
ed00: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
ed10: 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
ed20: 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20   to make global 
ed30: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a  configuration.**
ed40: 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69   changes to SQLi
ed50: 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74  te in order to t
ed60: 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68  une SQLite to th
ed70: 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73  e specific needs
ed80: 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
ed90: 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66  cation.  The def
eda0: 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69  ault configurati
edb0: 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  on is recommende
edc0: 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70  d for most.** ap
edd0: 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73  plications and s
ede0: 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  o this routine i
edf0: 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65  s usually not ne
ee00: 63 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a  cessary.  It is.
ee10: 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73  ** provided to s
ee20: 75 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c  upport rare appl
ee30: 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e  ications with un
ee40: 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a  usual needs..**.
ee50: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
ee60: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
ee70: 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73  e is not threads
ee80: 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63  afe.  The applic
ee90: 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e  ation.** must in
eea0: 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68  sure that no oth
eeb0: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
eec0: 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64  aces are invoked
eed0: 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72   by other.** thr
eee0: 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74  eads while sqlit
eef0: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72  e3_config() is r
ef00: 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72  unning.  Further
ef10: 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f  more, sqlite3_co
ef20: 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e  nfig().** may on
ef30: 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72  ly be invoked pr
ef40: 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69  ior to library i
ef50: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73  nitialization us
ef60: 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
ef70: 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72  initialize()] or
ef80: 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20   after shutdown 
ef90: 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  by [sqlite3_shut
efa0: 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20  down()]..** ^If 
efb0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
efc0: 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72   is called after
efd0: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
efe0: 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f  lize()] and befo
eff0: 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  re.** [sqlite3_s
f000: 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20  hutdown()] then 
f010: 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53  it will return S
f020: 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a  QLITE_MISUSE..**
f030: 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20   Note, however, 
f040: 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f  that ^sqlite3_co
f050: 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61  nfig() can be ca
f060: 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  lled as part of 
f070: 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
f080: 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c  ation of an appl
f090: 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
f0a0: 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74  [sqlite3_os_init
f0b0: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ()]..**.** The f
f0c0: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
f0d0: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
f0e0: 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a  ) is an integer.
f0f0: 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f  ** [configuratio
f100: 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64  n option] that d
f110: 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61  etermines.** wha
f120: 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51  t property of SQ
f130: 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f  Lite is to be co
f140: 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 65  nfigured.  Subse
f150: 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a  quent arguments.
f160: 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e  ** vary dependin
f170: 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67  g on the [config
f180: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a  uration option].
f190: 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ** in the first 
f1a0: 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
f1b0: 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72  ^When a configur
f1c0: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20  ation option is 
f1d0: 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e  set, sqlite3_con
f1e0: 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53  fig() returns [S
f1f0: 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49  QLITE_OK]..** ^I
f200: 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20  f the option is 
f210: 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74  unknown or SQLit
f220: 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73  e is unable to s
f230: 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a  et the option.**
f240: 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69   then this routi
f250: 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e  ne returns a non
f260: 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
f270: 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  e]..*/.int sqlit
f280: 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e  e3_config(int, .
f290: 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ..);../*.** CAPI
f2a0: 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20  3REF: Configure 
f2b0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
f2c0: 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ions.**.** The s
f2d0: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
f2e0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
f2f0: 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e  used to make con
f300: 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68  figuration.** ch
f310: 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61  anges to a [data
f320: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
f330: 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65  .  The interface
f340: 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a   is similar to.*
f350: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
f360: 67 28 29 5d 20 65 78 63 65 70 74 20 74 68 61 74  g()] except that
f370: 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 70 70   the changes app
f380: 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a  ly to a single.*
f390: 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
f3a0: 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69  ection] (specifi
f3b0: 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ed in the first 
f3c0: 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a  argument)..**.**
f3d0: 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
f3e0: 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
f3f0: 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e  db_config(D,V,..
f400: 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53  .)  is the.** [S
f410: 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
f420: 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69  OOKASIDE | confi
f430: 67 75 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d  guration verb] -
f440: 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65   an integer code
f450: 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61   .** that indica
f460: 74 65 73 20 77 68 61 74 20 61 73 70 65 63 74 20  tes what aspect 
f470: 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  of the [database
f480: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20   connection] is 
f490: 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64  being configured
f4a0: 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20  ..** Subsequent 
f4b0: 61 72 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64  arguments vary d
f4c0: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
f4d0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65  configuration ve
f4e0: 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73  rb..**.** ^Calls
f4f0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63   to sqlite3_db_c
f500: 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 20 53  onfig() return S
f510: 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20  QLITE_OK if and 
f520: 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63  only if.** the c
f530: 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65  all is considere
f540: 64 20 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f  d successful..*/
f550: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f  .int sqlite3_db_
f560: 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c  config(sqlite3*,
f570: 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a   int op, ...);..
f580: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
f590: 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f  Memory Allocatio
f5a0: 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a  n Routines.**.**
f5b0: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
f5c0: 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69  this object defi
f5d0: 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  nes the interfac
f5e0: 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65  e between SQLite
f5f0: 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65  .** and low-leve
f600: 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
f610: 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ion routines..**
f620: 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
f630: 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20  is used in only 
f640: 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65  one place in the
f650: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
f660: 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20  e..** A pointer 
f670: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
f680: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73  f this object is
f690: 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f   the argument to
f6a0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
f6b0: 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20  fig()] when the 
f6c0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
f6d0: 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49  tion is.** [SQLI
f6e0: 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
f6f0: 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  ] or [SQLITE_CON
f700: 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20  FIG_GETMALLOC]. 
f710: 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67   .** By creating
f720: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
f730: 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61  this object.** a
f740: 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f  nd passing it to
f750: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
f760: 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ]([SQLITE_CONFIG
f770: 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72  _MALLOC]).** dur
f780: 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ing configuratio
f790: 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  n, an applicatio
f7a0: 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e  n can specify an
f7b0: 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20   alternative.** 
f7c0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
f7d0: 6e 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20  n subsystem for 
f7e0: 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f  SQLite to use fo
f7f0: 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20  r all of its.** 
f800: 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e  dynamic memory n
f810: 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  eeds..**.** Note
f820: 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d   that SQLite com
f830: 65 73 20 77 69 74 68 20 73 65 76 65 72 61 6c 20  es with several 
f840: 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79  [built-in memory
f850: 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20   allocators].** 
f860: 74 68 61 74 20 61 72 65 20 70 65 72 66 65 63 74  that are perfect
f870: 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20  ly adequate for 
f880: 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67  the overwhelming
f890: 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70   majority of app
f8a0: 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64  lications.** and
f8b0: 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63   that this objec
f8c0: 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c  t is only useful
f8d0: 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72   to a tiny minor
f8e0: 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69  ity of applicati
f8f0: 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63  ons.** with spec
f900: 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61  ialized memory a
f910: 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72  llocation requir
f920: 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62  ements.  This ob
f930: 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20  ject is.** also 
f940: 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74  used during test
f950: 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e  ing of SQLite in
f960: 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66   order to specif
f970: 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65  y an alternative
f980: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
f990: 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61  ator that simula
f9a0: 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f  tes memory out-o
f9b0: 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69  f-memory conditi
f9c0: 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20  ons in.** order 
f9d0: 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53  to verify that S
f9e0: 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67  QLite recovers g
f9f0: 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73  racefully from s
fa00: 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e  uch.** condition
fa10: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61  s..**.** The xMa
fa20: 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20  lloc, xRealloc, 
fa30: 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64  and xFree method
fa40: 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65  s must work like
fa50: 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29   the.** malloc()
fa60: 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20  , realloc() and 
fa70: 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73  free() functions
fa80: 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
fa90: 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  rd C library..**
faa0: 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74   ^SQLite guarant
fab0: 65 65 73 20 74 68 61 74 20 74 68 65 20 73 65 63  ees that the sec
fac0: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
fad0: 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61  ** xRealloc is a
fae0: 6c 77 61 79 73 20 61 20 76 61 6c 75 65 20 72 65  lways a value re
faf0: 74 75 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f  turned by a prio
fb00: 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64  r call to xRound
fb10: 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20  up..**.** xSize 
fb20: 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68  should return th
fb30: 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
fb40: 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   of a memory all
fb50: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69  ocation.** previ
fb60: 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66  ously obtained f
fb70: 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78  rom xMalloc or x
fb80: 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c  Realloc.  The al
fb90: 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20  located size.** 
fba0: 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61  is always at lea
fbb0: 73 74 20 61 73 20 62 69 67 20 61 73 20 74 68 65  st as big as the
fbc0: 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 20   requested size 
fbd0: 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65  but may be large
fbe0: 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f  r..**.** The xRo
fbf0: 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74  undup method ret
fc00: 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20  urns what would 
fc10: 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  be the allocated
fc20: 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65   size of.** a me
fc30: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
fc40: 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c  given a particul
fc50: 61 72 20 72 65 71 75 65 73 74 65 64 20 73 69 7a  ar requested siz
fc60: 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a  e.  Most memory.
fc70: 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f  ** allocators ro
fc80: 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c  und up memory al
fc90: 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61  locations at lea
fca0: 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d  st to the next m
fcb0: 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e  ultiple.** of 8.
fcc0: 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72    Some allocator
fcd0: 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20  s round up to a 
fce0: 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20  larger multiple 
fcf0: 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66  or to a power of
fd00: 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d   2..** Every mem
fd10: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
fd20: 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e  equest coming in
fd30: 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65   through [sqlite
fd40: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f  3_malloc()].** o
fd50: 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
fd60: 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c  oc()] first call
fd70: 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20  s xRoundup.  If 
fd80: 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73  xRoundup returns
fd90: 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75   0, .** that cau
fda0: 73 65 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f  ses the correspo
fdb0: 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c  nding memory all
fdc0: 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e  ocation to fail.
fdd0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74  .**.** The xInit
fde0: 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69   method initiali
fdf0: 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  zes the memory a
fe00: 6c 6c 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72 20  llocator.  (For 
fe10: 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d  example,.** it m
fe20: 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e  ight allocate an
fe30: 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 78 65  y require mutexe
fe40: 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20  s or initialize 
fe50: 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a  internal data.**
fe60: 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 54 68   structures.  Th
fe70: 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68  e xShutdown meth
fe80: 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69  od is invoked (i
fe90: 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a  ndirectly) by.**
fea0: 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
feb0: 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64  wn()] and should
fec0: 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20   deallocate any 
fed0: 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 69 72  resources acquir
fee0: 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20  ed.** by xInit. 
fef0: 20 54 68 65 20 70 41 70 70 44 61 74 61 20 70 6f   The pAppData po
ff00: 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 61 73  inter is used as
ff10: 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65   the only parame
ff20: 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20  ter to.** xInit 
ff30: 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a  and xShutdown..*
ff40: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64  *.** SQLite hold
ff50: 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55  s the [SQLITE_MU
ff60: 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45  TEX_STATIC_MASTE
ff70: 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74  R] mutex when it
ff80: 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20   invokes.** the 
ff90: 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f  xInit method, so
ffa0: 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   the xInit metho
ffb0: 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68  d need not be th
ffc0: 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a  readsafe.  The.*
ffd0: 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68  * xShutdown meth
ffe0: 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65  od is only calle
fff0: 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
10000 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69  shutdown()] so i
10010 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65  t does.** not ne
10020 65 64 20 74 6f 20 62 65 20 74 68 72 65 61 64 73  ed to be threads
10030 61 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72  afe either.  For
10040 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f   all other metho
10050 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f  ds, SQLite.** ho
10060 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  lds the [SQLITE_
10070 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d  MUTEX_STATIC_MEM
10080 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20  ] mutex as long 
10090 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  as the.** [SQLIT
100a0 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
100b0 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  US] configuratio
100c0 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e  n option is turn
100d0 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20  ed on (which.** 
100e0 69 74 20 69 73 20 62 79 20 64 65 66 61 75 6c 74  it is by default
100f0 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74  ) and so the met
10100 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74  hods are automat
10110 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65  ically serialize
10120 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69  d..** However, i
10130 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  f [SQLITE_CONFIG
10140 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64  _MEMSTATUS] is d
10150 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68  isabled, then th
10160 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f  e other.** metho
10170 64 73 20 6d 75 73 74 20 62 65 20 74 68 72 65 61  ds must be threa
10180 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61  dsafe or else ma
10190 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72  ke their own arr
101a0 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a  angements for.**
101b0 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a   serialization..
101c0 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c  **.** SQLite wil
101d0 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78  l never invoke x
101e0 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e  Init() more than
101f0 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e   once without an
10200 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20   intervening.** 
10210 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77  call to xShutdow
10220 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  n()..*/.typedef 
10230 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
10240 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74  em_methods sqlit
10250 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a  e3_mem_methods;.
10260 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
10270 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76  em_methods {.  v
10280 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28  oid *(*xMalloc)(
10290 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a  int);         /*
102a0 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   Memory allocati
102b0 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20  on function */. 
102c0 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76   void (*xFree)(v
102d0 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
102e0 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72 20  /* Free a prior 
102f0 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
10300 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63  void *(*xRealloc
10310 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f  )(void*,int);  /
10320 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f  * Resize an allo
10330 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20  cation */.  int 
10340 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b  (*xSize)(void*);
10350 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65             /* Re
10360 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  turn the size of
10370 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a   an allocation *
10380 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64  /.  int (*xRound
10390 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20  up)(int);       
103a0 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72     /* Round up r
103b0 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61  equest size to a
103c0 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a  llocation size *
103d0 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29  /.  int (*xInit)
103e0 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
103f0 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65     /* Initialize
10400 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
10410 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20  cator */.  void 
10420 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69  (*xShutdown)(voi
10430 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69  d*);      /* Dei
10440 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65  nitialize the me
10450 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a  mory allocator *
10460 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61  /.  void *pAppDa
10470 74 61 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  ta;             
10480 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74     /* Argument t
10490 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53  o xInit() and xS
104a0 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a  hutdown() */.};.
104b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
104c0 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f   Configuration O
104d0 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52  ptions.** KEYWOR
104e0 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 69  DS: {configurati
104f0 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a  on option}.**.**
10500 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
10510 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62   are the availab
10520 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69  le integer confi
10530 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
10540 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20   that.** can be 
10550 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69  passed as the fi
10560 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
10570 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  the [sqlite3_con
10580 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
10590 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66  ..**.** New conf
105a0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
105b0 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
105c0 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
105d0 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  s of SQLite..** 
105e0 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75  Existing configu
105f0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
10600 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69  ight be disconti
10610 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69  nued.  Applicati
10620 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68  ons.** should ch
10630 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63  eck the return c
10640 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ode from [sqlite
10650 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d  3_config()] to m
10660 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a  ake sure that.**
10670 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64   the call worked
10680 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
10690 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
106a0 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ace will return 
106b0 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  a.** non-zero [e
106c0 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20  rror code] if a 
106d0 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20  discontinued or 
106e0 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66  unsupported conf
106f0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
10700 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a  .** is invoked..
10710 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b  **.** <dl>.** [[
10720 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
10730 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 74  NGLETHREAD]] <dt
10740 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
10750 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e  INGLETHREAD</dt>
10760 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
10770 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
10780 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
10790 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
107a0 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
107b0 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e  ing mode] to Sin
107c0 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20  gle-thread.  In 
107d0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20  other words, it 
107e0 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20  disables.** all 
107f0 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74  mutexing and put
10800 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20  s SQLite into a 
10810 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20 63 61  mode where it ca
10820 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a  n only be used.*
10830 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68  * by a single th
10840 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69  read.   ^If SQLi
10850 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
10860 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
10870 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
10880 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
10890 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
108a0 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
108b0 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69   it is not possi
108c0 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68  ble to change th
108d0 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
108e0 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61  e] from its defa
108f0 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  ult.** value of 
10900 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e  Single-thread an
10910 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d so [sqlite3_co
10920 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
10930 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urn .** [SQLITE_
10940 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64  ERROR] if called
10950 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
10960 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
10970 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  READ.** configur
10980 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
10990 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
109a0 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
109b0 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  READ]] <dt>SQLIT
109c0 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
109d0 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  READ</dt>.** <dd
109e0 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
109f0 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
10a00 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f  option.  ^This o
10a10 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
10a20 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  * [threading mod
10a30 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65  e] to Multi-thre
10a40 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  ad.  In other wo
10a50 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73  rds, it disables
10a60 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20  .** mutexing on 
10a70 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
10a80 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61  tion] and [prepa
10a90 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
10aa0 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61  bjects..** The a
10ab0 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65  pplication is re
10ac0 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65  sponsible for se
10ad0 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73  rializing access
10ae0 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65   to.** [database
10af0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e   connections] an
10b00 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
10b10 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74  ements].  But ot
10b20 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61  her mutexes.** a
10b30 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68  re enabled so th
10b40 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62  at SQLite will b
10b50 65 20 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e  e safe to use in
10b60 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65   a multi-threade
10b70 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74  d.** environment
10b80 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74   as long as no t
10b90 77 6f 20 74 68 72 65 61 64 73 20 61 74 74 65 6d  wo threads attem
10ba0 70 74 20 74 6f 20 75 73 65 20 74 68 65 20 73 61  pt to use the sa
10bb0 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  me.** [database 
10bc0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74  connection] at t
10bd0 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e  he same time.  ^
10be0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
10bf0 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
10c00 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
10c10 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
10c20 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
10c30 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
10c40 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
10c50 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65  t possible to se
10c60 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65  t the Multi-thre
10c70 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ad [threading mo
10c80 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  de] and.** [sqli
10c90 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
10ca0 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
10cb0 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
10cc0 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53  ed with the.** S
10cd0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
10ce0 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75  TITHREAD configu
10cf0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f  ration option.</
10d00 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
10d10 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
10d20 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  IZED]] <dt>SQLIT
10d30 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
10d40 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ZED</dt>.** <dd>
10d50 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
10d60 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
10d70 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
10d80 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
10d90 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
10da0 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e  ] to Serialized.
10db0 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
10dc0 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61   this option ena
10dd0 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65  bles.** all mute
10de0 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68  xes including th
10df0 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d  e recursive.** m
10e00 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62  utexes on [datab
10e10 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
10e20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
10e30 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73  atement] objects
10e40 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64  ..** In this mod
10e50 65 20 28 77 68 69 63 68 20 69 73 20 74 68 65 20  e (which is the 
10e60 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c  default when SQL
10e70 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
10e80 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  with.** [SQLITE_
10e90 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74  THREADSAFE=1]) t
10ea0 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
10eb0 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65  y will itself se
10ec0 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a  rialize access.*
10ed0 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63  * to [database c
10ee0 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20  onnections] and 
10ef0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
10f00 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68  ents] so that th
10f10 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  e.** application
10f20 20 69 73 20 66 72 65 65 20 74 6f 20 75 73 65 20   is free to use 
10f30 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61  the same [databa
10f40 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
10f50 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70  r the.** same [p
10f60 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
10f70 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20  t] in different 
10f80 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73  threads at the s
10f90 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66  ame time..** ^If
10fa0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
10fb0 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
10fc0 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
10fd0 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
10fe0 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
10ff0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
11000 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
11010 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20  possible to set 
11020 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b  the Serialized [
11030 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
11040 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
11050 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72  config()] will r
11060 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
11070 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77  ROR] if called w
11080 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54  ith the.** SQLIT
11090 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
110a0 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ZED configuratio
110b0 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  n option.</dd>.*
110c0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
110d0 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64  NFIG_MALLOC]] <d
110e0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
110f0 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c  MALLOC</dt>.** <
11100 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
11110 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
11120 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
11130 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
11140 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f  an.** instance o
11150 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
11160 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
11170 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75  cture.  The argu
11180 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a  ment specifies.*
11190 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f  * alternative lo
111a0 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61  w-level memory a
111b0 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
111c0 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e  es to be used in
111d0 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65   place of.** the
111e0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
111f0 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c  on routines buil
11200 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e  t into SQLite.)^
11210 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a   ^SQLite makes.*
11220 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74  * its own privat
11230 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f  e copy of the co
11240 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71  ntent of the [sq
11250 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
11260 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20  s] structure.** 
11270 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69  before the [sqli
11280 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61  te3_config()] ca
11290 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e  ll returns.</dd>
112a0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
112b0 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
112c0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
112d0 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f  NFIG_GETMALLOC</
112e0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
112f0 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
11300 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
11310 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
11320 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
11330 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
11340 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
11350 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20  ds] structure.  
11360 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
11370 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72  _methods].** str
11380 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64  ucture is filled
11390 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
113a0 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f  tly defined memo
113b0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
113c0 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69  utines.)^.** Thi
113d0 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  s option can be 
113e0 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64  used to overload
113f0 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d   the default mem
11400 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
11410 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20  * routines with 
11420 61 20 77 72 61 70 70 65 72 20 74 68 61 74 20 73  a wrapper that s
11430 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72  imulations memor
11440 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
11450 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b  lure or.** track
11460 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20  s memory usage, 
11470 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64  for example. </d
11480 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
11490 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
114a0 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  US]] <dt>SQLITE_
114b0 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
114c0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
114d0 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
114e0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
114f0 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 20 69 6e   of type int, in
11500 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 0a  terpreted as a .
11510 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63  ** boolean, whic
11520 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73  h enables or dis
11530 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63  ables the collec
11540 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61  tion of memory a
11550 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74  llocation .** st
11560 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68 65 6e  atistics. ^(When
11570 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
11580 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72  on statistics ar
11590 65 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20  e disabled, the 
115a0 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51  .** following SQ
115b0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20  Lite interfaces 
115c0 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61  become non-opera
115d0 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c  tional:.**   <ul
115e0 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  >.**   <li> [sql
115f0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
11600 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
11610 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
11620 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20  ghwater()].**   
11630 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f  <li> [sqlite3_so
11640 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28  ft_heap_limit64(
11650 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
11660 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d 0a  lite3_status()].
11670 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20  **   </ul>)^.** 
11680 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69  ^Memory allocati
11690 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72  on statistics ar
116a0 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66  e enabled by def
116b0 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69  ault unless SQLi
116c0 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65  te is.** compile
116d0 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44  d with [SQLITE_D
116e0 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53  EFAULT_MEMSTATUS
116f0 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61 73  ]=0 in which cas
11700 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
11710 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
11720 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62  s are disabled b
11730 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f  y default..** </
11740 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
11750 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
11760 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  H]] <dt>SQLITE_C
11770 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64  ONFIG_SCRATCH</d
11780 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
11790 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
117a0 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
117b0 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51  y buffer that SQ
117c0 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72  Lite can use for
117d0 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f  .** scratch memo
117e0 72 79 2e 20 20 54 68 65 72 65 20 61 72 65 20 74  ry.  There are t
117f0 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20  hree arguments: 
11800 20 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d   A pointer an 8-
11810 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20  byte.** aligned 
11820 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72  memory buffer fr
11830 6f 6d 20 77 68 69 63 68 20 74 68 65 20 73 63 72  om which the scr
11840 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  atch allocations
11850 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77   will be.** draw
11860 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65  n, the size of e
11870 61 63 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f  ach scratch allo
11880 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20  cation (sz),.** 
11890 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20  and the maximum 
118a0 6e 75 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63  number of scratc
118b0 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e  h allocations (N
118c0 29 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72  ).  The sz.** ar
118d0 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61  gument must be a
118e0 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e   multiple of 16.
118f0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
11900 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61  gument must be a
11910 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38   pointer to an 8
11920 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75  -byte aligned bu
11930 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65  ffer.** of at le
11940 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f  ast sz*N bytes o
11950 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51  f memory..** ^SQ
11960 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f  Lite will use no
11970 20 6d 6f 72 65 20 74 68 61 6e 20 74 77 6f 20 73   more than two s
11980 63 72 61 74 63 68 20 62 75 66 66 65 72 73 20 70  cratch buffers p
11990 65 72 20 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a  er thread.  So.*
119a0 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65 20 73 65  * N should be se
119b0 74 20 74 6f 20 74 77 69 63 65 20 74 68 65 20 65  t to twice the e
119c0 78 70 65 63 74 65 64 20 6d 61 78 69 6d 75 6d 20  xpected maximum 
119d0 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65 61 64  number of thread
119e0 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  s..** ^SQLite wi
119f0 6c 6c 20 6e 65 76 65 72 20 72 65 71 75 69 72 65  ll never require
11a00 20 61 20 73 63 72 61 74 63 68 20 62 75 66 66 65   a scratch buffe
11a10 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65 20 74  r that is more t
11a20 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74  han 6.** times t
11a30 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65  he database page
11a40 20 73 69 7a 65 2e 20 5e 49 66 20 53 51 4c 69 74   size. ^If SQLit
11a50 65 20 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64  e needs needs ad
11a60 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61  ditional.** scra
11a70 74 63 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e  tch memory beyon
11a80 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64  d what is provid
11a90 65 64 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69  ed by this confi
11aa0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c  guration option,
11ab0 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74   then .** [sqlit
11ac0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c  e3_malloc()] wil
11ad0 6c 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  l be used to obt
11ae0 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e  ain the memory n
11af0 65 65 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  eeded.</dd>.**.*
11b00 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
11b10 47 5f 50 41 47 45 43 41 43 48 45 5d 5d 20 3c 64  G_PAGECACHE]] <d
11b20 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
11b30 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a  PAGECACHE</dt>.*
11b40 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
11b50 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
11b60 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75  static memory bu
11b70 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  ffer that SQLite
11b80 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20   can use for.** 
11b90 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67  the database pag
11ba0 65 20 63 61 63 68 65 20 77 69 74 68 20 74 68 65  e cache with the
11bb0 20 64 65 66 61 75 6c 74 20 70 61 67 65 20 63 61   default page ca
11bc0 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
11bd0 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f  on.  .** This co
11be0 6e 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75  nfiguration shou
11bf0 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69  ld not be used i
11c00 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
11c10 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20  -define page.** 
11c20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
11c30 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75  tion is loaded u
11c40 73 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f  sing the SQLITE_
11c50 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 6f  CONFIG_PCACHE2 o
11c60 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20  ption..** There 
11c70 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
11c80 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
11c90 6f 6e 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  on: A pointer to
11ca0 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 0a   8-byte aligned.
11cb0 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73  ** memory, the s
11cc0 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67 65  ize of each page
11cd0 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e   buffer (sz), an
11ce0 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  d the number of 
11cf0 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68  pages (N)..** Th
11d00 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68  e sz argument sh
11d10 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65  ould be the size
11d20 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20   of the largest 
11d30 64 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a  database page.**
11d40 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f   (a power of two
11d50 20 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64   between 512 and
11d60 20 33 32 37 36 38 29 20 70 6c 75 73 20 61 20 6c   32768) plus a l
11d70 69 74 74 6c 65 20 65 78 74 72 61 20 66 6f 72 20  ittle extra for 
11d80 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61  each.** page hea
11d90 64 65 72 2e 20 20 5e 54 68 65 20 70 61 67 65 20  der.  ^The page 
11da0 68 65 61 64 65 72 20 73 69 7a 65 20 69 73 20 32  header size is 2
11db0 30 20 74 6f 20 34 30 20 62 79 74 65 73 20 64 65  0 to 40 bytes de
11dc0 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68  pending on.** th
11dd0 65 20 68 6f 73 74 20 61 72 63 68 69 74 65 63 74  e host architect
11de0 75 72 65 2e 20 20 5e 49 74 20 69 73 20 68 61 72  ure.  ^It is har
11df0 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f  mless, apart fro
11e00 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d  m the wasted mem
11e10 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20  ory,.** to make 
11e20 73 7a 20 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20  sz a little too 
11e30 6c 61 72 67 65 2e 20 20 54 68 65 20 66 69 72 73  large.  The firs
11e40 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68  t.** argument sh
11e50 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e  ould point to an
11e60 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61   allocation of a
11e70 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74  t least sz*N byt
11e80 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  es of memory..**
11e90 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73   ^SQLite will us
11ea0 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f  e the memory pro
11eb0 76 69 64 65 64 20 62 79 20 74 68 65 20 66 69 72  vided by the fir
11ec0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  st argument to s
11ed0 61 74 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65  atisfy its.** me
11ee0 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 20 74  mory needs for t
11ef0 68 65 20 66 69 72 73 74 20 4e 20 70 61 67 65 73  he first N pages
11f00 20 74 68 61 74 20 69 74 20 61 64 64 73 20 74 6f   that it adds to
11f10 20 63 61 63 68 65 2e 20 20 5e 49 66 20 61 64 64   cache.  ^If add
11f20 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20  itional.** page 
11f30 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20  cache memory is 
11f40 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68  needed beyond wh
11f50 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62  at is provided b
11f60 79 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74  y this option, t
11f70 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f  hen.** SQLite go
11f80 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d  es to [sqlite3_m
11f90 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65  alloc()] for the
11fa0 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72   additional stor
11fb0 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68  age space..** Th
11fc0 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65  e pointer in the
11fd0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
11fe0 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e  must.** be align
11ff0 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  ed to an 8-byte 
12000 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73  boundary or subs
12010 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20  equent behavior 
12020 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c  of SQLite.** wil
12030 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c  l be undefined.<
12040 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
12050 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d  ITE_CONFIG_HEAP]
12060 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
12070 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a  FIG_HEAP</dt>.**
12080 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
12090 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
120a0 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
120b0 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20  fer that SQLite 
120c0 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20  will use.** for 
120d0 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d  all of its dynam
120e0 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ic memory alloca
120f0 74 69 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e  tion needs beyon
12100 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64  d those provided
12110 0a 2a 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c 49  .** for by [SQLI
12120 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
12130 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43  H] and [SQLITE_C
12140 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d  ONFIG_PAGECACHE]
12150 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74  ..** There are t
12160 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20  hree arguments: 
12170 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  An 8-byte aligne
12180 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  d pointer to the
12190 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20   memory,.** the 
121a0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
121b0 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75  in the memory bu
121c0 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69  ffer, and the mi
121d0 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e  nimum allocation
121e0 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68   size..** ^If th
121f0 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20  e first pointer 
12200 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  (the memory poin
12210 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68  ter) is NULL, th
12220 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72 74  en SQLite revert
12230 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74  s.** to using it
12240 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79  s default memory
12250 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20   allocator (the 
12260 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20  system malloc() 
12270 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c  implementation),
12280 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20  .** undoing any 
12290 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e  prior invocation
122a0 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   of [SQLITE_CONF
122b0 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66  IG_MALLOC].  ^If
122c0 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70   the.** memory p
122d0 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55  ointer is not NU
122e0 4c 4c 20 61 6e 64 20 65 69 74 68 65 72 20 5b 53  LL and either [S
122f0 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
12300 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  SYS3] or.** [SQL
12310 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59  ITE_ENABLE_MEMSY
12320 53 35 5d 20 61 72 65 20 64 65 66 69 6e 65 64 2c  S5] are defined,
12330 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e   then the altern
12340 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  ative memory.** 
12350 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67  allocator is eng
12360 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61  aged to handle a
12370 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65  ll of SQLites me
12380 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12390 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69  needs..** The fi
123a0 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65  rst pointer (the
123b0 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29   memory pointer)
123c0 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64   must be aligned
123d0 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a   to an 8-byte.**
123e0 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62   boundary or sub
123f0 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72  sequent behavior
12400 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20   of SQLite will 
12410 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  be undefined..**
12420 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   The minimum all
12430 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20  ocation size is 
12440 63 61 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e  capped at 2**12.
12450 20 52 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75   Reasonable valu
12460 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69  es.** for the mi
12470 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e  nimum allocation
12480 20 73 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74   size are 2**5 t
12490 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64  hrough 2**8.</dd
124a0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
124b0 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20  _CONFIG_MUTEX]] 
124c0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
124d0 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20  G_MUTEX</dt>.** 
124e0 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
124f0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
12500 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
12510 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
12520 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20   an.** instance 
12530 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
12540 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
12550 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61  tructure.  The a
12560 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65  rgument specifie
12570 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65  s.** alternative
12580 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78   low-level mutex
12590 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
125a0 75 73 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a  used in place.**
125b0 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69   the mutex routi
125c0 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53  nes built into S
125d0 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74  QLite.)^  ^SQLit
125e0 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
125f0 66 20 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74  f the.** content
12600 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
12610 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
12620 73 74 72 75 63 74 75 72 65 20 62 65 66 6f 72 65  structure before
12630 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20   the call to.** 
12640 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
12650 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20  )] returns. ^If 
12660 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
12670 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
12680 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
12690 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
126a0 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
126b0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
126c0 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20  n.** the entire 
126d0 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74  mutexing subsyst
126e0 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  em is omitted fr
126f0 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64  om the build and
12700 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a   hence calls to.
12710 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
12720 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53  ig()] with the S
12730 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
12740 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  EX configuration
12750 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20   option will.** 
12760 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
12770 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  RROR].</dd>.**.*
12780 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
12790 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74  G_GETMUTEX]] <dt
127a0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
127b0 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20  ETMUTEX</dt>.** 
127c0 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
127d0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
127e0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
127f0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
12800 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20   an.** instance 
12810 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
12820 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
12830 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a  tructure.  The.*
12840 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  * [sqlite3_mutex
12850 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72  _methods].** str
12860 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64  ucture is filled
12870 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
12880 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65  tly defined mute
12890 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a  x routines.)^.**
128a0 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
128b0 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
128c0 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
128d0 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f   mutex allocatio
128e0 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69  n.** routines wi
128f0 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65  th a wrapper use
12900 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78  d to track mutex
12910 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f   usage for perfo
12920 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c  rmance.** profil
12930 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20  ing or testing, 
12940 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e  for example.   ^
12950 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
12960 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
12970 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
12980 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
12990 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
129a0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
129b0 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69  then.** the enti
129c0 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73  re mutexing subs
129d0 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64  ystem is omitted
129e0 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20   from the build 
129f0 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20  and hence calls 
12a00 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
12a10 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68  onfig()] with th
12a20 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
12a30 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75  GETMUTEX configu
12a40 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69  ration option wi
12a50 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ll.** return [SQ
12a60 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64  LITE_ERROR].</dd
12a70 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
12a80 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
12a90 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  E]] <dt>SQLITE_C
12aa0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c  ONFIG_LOOKASIDE<
12ab0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
12ac0 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
12ad0 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74   two arguments t
12ae0 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68  hat determine th
12af0 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d  e default.** mem
12b00 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
12b10 6f 72 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65  or the lookaside
12b20 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
12b30 72 20 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61  r on each.** [da
12b40 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
12b50 6e 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 61  n].  The first a
12b60 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a  rgument is the.*
12b70 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c  * size of each l
12b80 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
12b90 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63  slot and the sec
12ba0 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ond is the numbe
12bb0 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c  r of.** slots al
12bc0 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68 20  located to each 
12bd0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
12be0 69 6f 6e 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f  ion.)^  ^(This o
12bf0 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
12c00 2a 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e  * <i>default</i>
12c10 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e   lookaside size.
12c20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43   The [SQLITE_DBC
12c30 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
12c40 0a 2a 2a 20 76 65 72 62 20 74 6f 20 5b 73 71 6c  .** verb to [sql
12c50 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
12c60 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  ] can be used to
12c70 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b   change the look
12c80 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75  aside.** configu
12c90 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69  ration on indivi
12ca0 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  dual connections
12cb0 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .)^ </dd>.**.** 
12cc0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
12cd0 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51  PCACHE2]] <dt>SQ
12ce0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
12cf0 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  HE2</dt>.** <dd>
12d00 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
12d10 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
12d20 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
12d30 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20  a pointer to.** 
12d40 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  an [sqlite3_pcac
12d50 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a  he_methods2] obj
12d60 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63  ect.  This objec
12d70 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20  t specifies the 
12d80 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20  interface.** to 
12d90 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61  a custom page ca
12da0 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
12db0 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d  on.)^  ^SQLite m
12dc0 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
12dd0 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64  he.** object and
12de0 20 75 73 65 73 20 69 74 20 66 6f 72 20 70 61 67   uses it for pag
12df0 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61  e cache memory a
12e00 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e  llocations.</dd>
12e10 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
12e20 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
12e30 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  2]] <dt>SQLITE_C
12e40 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
12e50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
12e60 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
12e70 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
12e80 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
12e90 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
12ea0 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f  [sqlite3_pcache_
12eb0 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74  methods2] object
12ec0 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73  .  SQLite copies
12ed0 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a   of the current.
12ee0 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  ** page cache im
12ef0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74  plementation int
12f00 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e  o that object.)^
12f10 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
12f20 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
12f30 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
12f40 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a  NFIG_LOG</dt>.**
12f50 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54   <dd> ^The SQLIT
12f60 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74  E_CONFIG_LOG opt
12f70 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72  ion takes two ar
12f80 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74  guments: a point
12f90 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74  er to a.** funct
12fa0 69 6f 6e 20 77 69 74 68 20 61 20 63 61 6c 6c 20  ion with a call 
12fb0 73 69 67 6e 61 74 75 72 65 20 6f 66 20 76 6f 69  signature of voi
12fc0 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  d(*)(void*,int,c
12fd0 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a  onst char*), .**
12fe0 20 61 6e 64 20 61 20 70 6f 69 6e 74 65 72 20 74   and a pointer t
12ff0 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74 68 65 20  o void. ^If the 
13000 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72  function pointer
13010 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74   is not NULL, it
13020 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62   is.** invoked b
13030 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  y [sqlite3_log()
13040 5d 20 74 6f 20 70 72 6f 63 65 73 73 20 65 61 63  ] to process eac
13050 68 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e  h logging event.
13060 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e    ^If the.** fun
13070 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73  ction pointer is
13080 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69   NULL, the [sqli
13090 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72  te3_log()] inter
130a0 66 61 63 65 20 62 65 63 6f 6d 65 73 20 61 20 6e  face becomes a n
130b0 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f  o-op..** ^The vo
130c0 69 64 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20  id pointer that 
130d0 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  is the second ar
130e0 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54 45  gument to SQLITE
130f0 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a  _CONFIG_LOG is.*
13100 2a 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68  * passed through
13110 20 61 73 20 74 68 65 20 66 69 72 73 74 20 70 61   as the first pa
13120 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
13130 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
13140 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e  ed logger.** fun
13150 63 74 69 6f 6e 20 77 68 65 6e 65 76 65 72 20 74  ction whenever t
13160 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  hat function is 
13170 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73  invoked.  ^The s
13180 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
13190 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72  to.** the logger
131a0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 63   function is a c
131b0 6f 70 79 20 6f 66 20 74 68 65 20 66 69 72 73 74  opy of the first
131c0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
131d0 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a  e corresponding.
131e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28  ** [sqlite3_log(
131f0 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73 20 69  )] call and is i
13200 6e 74 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20  ntended to be a 
13210 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72  [result code] or
13220 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   an.** [extended
13230 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20   result code].  
13240 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d  ^The third param
13250 65 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74  eter passed to t
13260 68 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20  he logger is.** 
13270 6c 6f 67 20 6d 65 73 73 61 67 65 20 61 66 74 65  log message afte
13280 72 20 66 6f 72 6d 61 74 74 69 6e 67 20 76 69 61  r formatting via
13290 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
132a0 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51  tf()]..** The SQ
132b0 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74  Lite logging int
132c0 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65  erface is not re
132d0 65 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67  entrant; the log
132e0 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ger function.** 
132f0 73 75 70 70 6c 69 65 64 20 62 79 20 74 68 65 20  supplied by the 
13300 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
13310 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20   not invoke any 
13320 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
13330 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d  ..** In a multi-
13340 74 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 61  threaded applica
13350 74 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69 63  tion, the applic
13360 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f  ation-defined lo
13370 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  gger.** function
13380 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73   must be threads
13390 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  afe. </dd>.**.**
133a0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
133b0 5f 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  _URI]] <dt>SQLIT
133c0 45 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20  E_CONFIG_URI.** 
133d0 3c 64 64 3e 20 54 68 69 73 20 6f 70 74 69 6f 6e  <dd> This option
133e0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
133f0 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65  argument of type
13400 20 69 6e 74 2e 20 49 66 20 6e 6f 6e 2d 7a 65 72   int. If non-zer
13410 6f 2c 20 74 68 65 6e 0a 2a 2a 20 55 52 49 20 68  o, then.** URI h
13420 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61  andling is globa
13430 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49 66 20  lly enabled. If 
13440 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  the parameter is
13450 20 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52 49 20   zero, then URI 
13460 68 61 6e 64 6c 69 6e 67 0a 2a 2a 20 69 73 20 67  handling.** is g
13470 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  lobally disabled
13480 2e 20 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e  . If URI handlin
13490 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e  g is globally en
134a0 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e  abled, all filen
134b0 61 6d 65 73 0a 2a 2a 20 70 61 73 73 65 64 20 74  ames.** passed t
134c0 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
134d0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
134e0 6e 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  n_v2()], [sqlite
134f0 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a  3_open16()] or.*
13500 2a 20 73 70 65 63 69 66 69 65 64 20 61 73 20 70  * specified as p
13510 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d 20  art of [ATTACH] 
13520 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e 74  commands are int
13530 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73  erpreted as URIs
13540 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20  , regardless.** 
13550 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
13560 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  t the [SQLITE_OP
13570 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 20  EN_URI] flag is 
13580 73 65 74 20 77 68 65 6e 20 74 68 65 20 64 61 74  set when the dat
13590 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
135a0 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 49  ion is opened. I
135b0 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79  f it is globally
135c0 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e   disabled, filen
135d0 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79  ames are.** only
135e0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
135f0 55 52 49 73 20 69 66 20 74 68 65 20 53 51 4c 49  URIs if the SQLI
13600 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67  TE_OPEN_URI flag
13610 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65   is set when the
13620 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
13630 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65  nection is opene
13640 64 2e 20 42 79 20 64 65 66 61 75 6c 74 2c 20 55  d. By default, U
13650 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
13660 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62  lobally.** disab
13670 6c 65 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74  led. The default
13680 20 76 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68   value may be ch
13690 61 6e 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69  anged by compili
136a0 6e 67 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ng with the.** [
136b0 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20  SQLITE_USE_URI] 
136c0 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a  symbol defined..
136d0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
136e0 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49  ONFIG_COVERING_I
136f0 4e 44 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e  NDEX_SCAN]] <dt>
13700 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f  SQLITE_CONFIG_CO
13710 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
13720 4e 0a 2a 2a 20 3c 64 64 3e 20 54 68 69 73 20 6f  N.** <dd> This o
13730 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
13740 6e 67 6c 65 20 69 6e 74 65 67 65 72 20 61 72 67  ngle integer arg
13750 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 69  ument which is i
13760 6e 74 65 72 70 72 65 74 65 64 20 61 73 0a 2a 2a  nterpreted as.**
13770 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72   a boolean in or
13780 64 65 72 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  der to enable or
13790 20 64 69 73 61 62 6c 65 20 74 68 65 20 75 73 65   disable the use
137a0 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64   of covering ind
137b0 69 63 65 73 20 66 6f 72 0a 2a 2a 20 66 75 6c 6c  ices for.** full
137c0 20 74 61 62 6c 65 20 73 63 61 6e 73 20 69 6e 20   table scans in 
137d0 74 68 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69  the query optimi
137e0 7a 65 72 2e 20 20 54 68 65 20 64 65 66 61 75 6c  zer.  The defaul
137f0 74 20 73 65 74 74 69 6e 67 20 69 73 20 64 65 74  t setting is det
13800 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68  ermined.** by th
13810 65 20 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f  e [SQLITE_ALLOW_
13820 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
13830 43 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  CAN] compile-tim
13840 65 20 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20  e option, or is 
13850 22 6f 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74 20  "on".** if that 
13860 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
13870 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a  ion is omitted..
13880 2a 2a 20 54 68 65 20 61 62 69 6c 69 74 79 20 74  ** The ability t
13890 6f 20 64 69 73 61 62 6c 65 20 74 68 65 20 75 73  o disable the us
138a0 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e  e of covering in
138b0 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74  dices for full t
138c0 61 62 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73  able scans.** is
138d0 20 62 65 63 61 75 73 65 20 73 6f 6d 65 20 69 6e   because some in
138e0 63 6f 72 72 65 63 74 6c 79 20 63 6f 64 65 64 20  correctly coded 
138f0 6c 65 67 61 63 79 20 61 70 70 6c 69 63 61 74 69  legacy applicati
13900 6f 6e 73 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e  ons might malfun
13910 63 74 69 6f 6e 0a 2a 2a 20 6d 61 6c 66 75 6e 63  ction.** malfunc
13920 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 6f 70  tion when the op
13930 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e  timization is en
13940 61 62 6c 65 64 2e 20 20 50 72 6f 76 69 64 69 6e  abled.  Providin
13950 67 20 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f  g the ability to
13960 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74 68 65 20  .** disable the 
13970 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c  optimization all
13980 6f 77 73 20 74 68 65 20 6f 6c 64 65 72 2c 20 62  ows the older, b
13990 75 67 67 79 20 61 70 70 6c 69 63 61 74 69 6f 6e  uggy application
139a0 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a   code to work.**
139b0 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 65 20   without change 
139c0 65 76 65 6e 20 77 69 74 68 20 6e 65 77 65 72 20  even with newer 
139d0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
139e0 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  te..**.** [[SQLI
139f0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
13a00 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ]] [[SQLITE_CONF
13a10 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a  IG_GETPCACHE]].*
13a20 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
13a30 46 49 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53  FIG_PCACHE and S
13a40 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
13a50 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54  PCACHE.** <dd> T
13a60 68 65 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65  hese options are
13a70 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68   obsolete and sh
13a80 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64  ould not be used
13a90 20 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a   by new code..**
13aa0 20 54 68 65 79 20 61 72 65 20 72 65 74 61 69 6e   They are retain
13ab0 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ed for backwards
13ac0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62   compatibility b
13ad0 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70  ut are now no-op
13ae0 73 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a  s..** </dl>.**.*
13af0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
13b00 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64  G_SQLLOG]].** <d
13b10 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
13b20 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68  SQLLOG.** <dd>Th
13b30 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c  is option is onl
13b40 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 73  y available if s
13b50 71 6c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  qlite is compile
13b60 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51  d with the.** SQ
13b70 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c  LITE_ENABLE_SQLL
13b80 4f 47 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72  OG pre-processor
13b90 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 20   macro defined. 
13ba0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
13bb0 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20  nt should.** be 
13bc0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66  a pointer to a f
13bd0 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20  unction of type 
13be0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
13bf0 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61  lite3*,const cha
13c00 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65  r*, int)..** The
13c10 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62   second should b
13c20 65 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 2a  e of type (void*
13c30 29 2e 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  ). The callback 
13c40 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 68  is invoked by th
13c50 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20  e library.** in 
13c60 74 68 72 65 65 20 73 65 70 61 72 61 74 65 20 63  three separate c
13c70 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 69 64  ircumstances, id
13c80 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
13c90 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20  value passed as 
13ca0 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61  the.** fourth pa
13cb0 72 61 6d 65 74 65 72 2e 20 49 66 20 74 68 65 20  rameter. If the 
13cc0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
13cd0 20 69 73 20 30 2c 20 74 68 65 6e 20 74 68 65 20   is 0, then the 
13ce0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
13cf0 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61 73  ion.** passed as
13d00 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
13d10 6d 65 6e 74 20 68 61 73 20 6a 75 73 74 20 62 65  ment has just be
13d20 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65 20 74  en opened. The t
13d30 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  hird argument.**
13d40 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 66   points to a buf
13d50 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  fer containing t
13d60 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d  he name of the m
13d70 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c  ain database fil
13d80 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75  e. If the.** fou
13d90 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
13da0 20 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c   1, then the SQL
13db0 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
13dc0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
13dd0 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f  ter.** points to
13de0 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 65   has just been e
13df0 78 65 63 75 74 65 64 2e 20 4f 72 2c 20 69 66 20  xecuted. Or, if 
13e00 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
13e10 65 74 65 72 20 69 73 20 32 2c 20 74 68 65 6e 0a  eter is 2, then.
13e20 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  ** the connectio
13e30 6e 20 62 65 69 6e 67 20 70 61 73 73 65 64 20 61  n being passed a
13e40 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
13e50 61 6d 65 74 65 72 20 69 73 20 62 65 69 6e 67 20  ameter is being 
13e60 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74  closed. The.** t
13e70 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69  hird parameter i
13e80 73 20 70 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e  s passed NULL In
13e90 20 74 68 69 73 20 63 61 73 65 2e 0a 2a 2a 20 3c   this case..** <
13ea0 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
13eb0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
13ec0 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f  NGLETHREAD  1  /
13ed0 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
13ee0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
13ef0 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20  ULTITHREAD   2  
13f00 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
13f10 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
13f20 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20  SERIALIZED    3 
13f30 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
13f40 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
13f50 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34  _MALLOC        4
13f60 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d    /* sqlite3_mem
13f70 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
13f80 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
13f90 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20  IG_GETMALLOC    
13fa0 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   5  /* sqlite3_m
13fb0 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  em_methods* */.#
13fc0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
13fd0 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20  NFIG_SCRATCH    
13fe0 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     6  /* void*, 
13ff0 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f  int sz, int N */
14000 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
14010 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
14020 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a       7  /* void*
14030 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20  , int sz, int N 
14040 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
14050 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20  E_CONFIG_HEAP   
14060 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69         8  /* voi
14070 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69  d*, int nByte, i
14080 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e  nt min */.#defin
14090 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
140a0 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 20  MEMSTATUS     9 
140b0 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23   /* boolean */.#
140c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
140d0 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20  NFIG_MUTEX      
140e0 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33    10  /* sqlite3
140f0 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20  _mutex_methods* 
14100 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
14110 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
14120 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c  X     11  /* sql
14130 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
14140 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f  ds* */./* previo
14150 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46  usly SQLITE_CONF
14160 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32  IG_CHUNKALLOC 12
14170 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e   which is now un
14180 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e  used. */ .#defin
14190 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
141a0 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20  LOOKASIDE    13 
141b0 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23   /* int int */.#
141c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
141d0 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20 20  NFIG_PCACHE     
141e0 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a    14  /* no-op *
141f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
14200 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
14210 45 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f  E    15  /* no-o
14220 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  p */.#define SQL
14230 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20  ITE_CONFIG_LOG  
14240 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20 78          16  /* x
14250 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23  Func, void* */.#
14260 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
14270 4e 46 49 47 5f 55 52 49 20 20 20 20 20 20 20 20  NFIG_URI        
14280 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a    17  /* int */.
14290 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
142a0 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 20 20  ONFIG_PCACHE2   
142b0 20 20 20 31 38 20 20 2f 2a 20 73 71 6c 69 74 65     18  /* sqlite
142c0 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
142d0 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  2* */.#define SQ
142e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
142f0 43 41 43 48 45 32 20 20 20 31 39 20 20 2f 2a 20  CACHE2   19  /* 
14300 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
14310 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66  ethods2* */.#def
14320 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
14330 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  G_COVERING_INDEX
14340 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20 69 6e 74  _SCAN 20  /* int
14350 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
14360 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47  TE_CONFIG_SQLLOG
14370 20 20 20 20 20 20 20 32 31 20 20 2f 2a 20 78 53         21  /* xS
14380 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f 0a  qllog, void* */.
14390 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
143a0 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
143b0 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69  tion Configurati
143c0 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a  on Options.**.**
143d0 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
143e0 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62   are the availab
143f0 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69  le integer confi
14400 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
14410 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20   that.** can be 
14420 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65  passed as the se
14430 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
14440 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62   the [sqlite3_db
14450 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
14460 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  face..**.** New 
14470 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
14480 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
14490 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
144a0 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
144b0 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e  .** Existing con
144c0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
144d0 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63  ns might be disc
144e0 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69  ontinued.  Appli
144f0 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
14500 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  d check the retu
14510 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71  rn code from [sq
14520 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
14530 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  )] to make sure 
14540 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  that.** the call
14550 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b   worked.  ^The [
14560 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
14570 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77  g()] interface w
14580 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  ill return a.** 
14590 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
145a0 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f  code] if a disco
145b0 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70  ntinued or unsup
145c0 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61  ported configura
145d0 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69  tion option.** i
145e0 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a  s invoked..**.**
145f0 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c   <dl>.** <dt>SQL
14600 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
14610 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  KASIDE</dt>.** <
14620 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
14630 20 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64   takes three add
14640 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
14650 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  s that determine
14660 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73   the .** [lookas
14670 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ide memory alloc
14680 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74  ator] configurat
14690 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74  ion for the [dat
146a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
146b0 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  ]..** ^The first
146c0 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74   argument (the t
146d0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
146e0 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  o [sqlite3_db_co
146f0 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20  nfig()] is a.** 
14700 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d  pointer to a mem
14710 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 73  ory buffer to us
14720 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20  e for lookaside 
14730 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20  memory..** ^The 
14740 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61  first argument a
14750 66 74 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f  fter the SQLITE_
14760 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
14770 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62  DE verb.** may b
14780 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20  e NULL in which 
14790 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c  case SQLite will
147a0 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a   allocate the.**
147b0 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
147c0 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b  r itself using [
147d0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
147e0 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ]. ^The second a
147f0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a  rgument is the.*
14800 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c  * size of each l
14810 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
14820 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72  slot.  ^The thir
14830 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
14840 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73  e number of.** s
14850 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20  lots.  The size 
14860 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69 6e  of the buffer in
14870 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
14880 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 61  ent must be grea
14890 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65  ter than.** or e
148a0 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64  qual to the prod
148b0 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e  uct of the secon
148c0 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 75  d and third argu
148d0 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66  ments.  The buff
148e0 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c  er.** must be al
148f0 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79  igned to an 8-by
14900 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49  te boundary.  ^I
14910 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  f the second arg
14920 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49  ument to.** SQLI
14930 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
14940 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d  ASIDE is not a m
14950 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74  ultiple of 8, it
14960 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a   is internally.*
14970 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74  * rounded down t
14980 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c  o the next small
14990 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38  er multiple of 8
149a0 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69  .  ^(The lookasi
149b0 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e  de memory.** con
149c0 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61  figuration for a
149d0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
149e0 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65  tion can only be
149f0 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68   changed when th
14a00 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  at.** connection
14a10 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c   is not currentl
14a20 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64  y using lookasid
14a30 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20  e memory, or in 
14a40 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77  other words.** w
14a50 68 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74  hen the "current
14a60 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64   value" returned
14a70 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
14a80 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51  db_status](D,[SQ
14a90 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
14aa0 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a  ASIDE],...) is z
14ab0 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65  ero..** Any atte
14ac0 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68  mpt to change th
14ad0 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  e lookaside memo
14ae0 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ry configuration
14af0 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a   when lookaside.
14b00 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20  ** memory is in 
14b10 75 73 65 20 6c 65 61 76 65 73 20 74 68 65 20 63  use leaves the c
14b20 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63  onfiguration unc
14b30 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72  hanged and retur
14b40 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42  ns .** [SQLITE_B
14b50 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a  USY].)^</dd>.**.
14b60 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
14b70 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b  CONFIG_ENABLE_FK
14b80 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  EY</dt>.** <dd> 
14b90 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  ^This option is 
14ba0 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f  used to enable o
14bb0 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e  r disable the en
14bc0 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20  forcement of.** 
14bd0 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e  [foreign key con
14be0 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72  straints].  Ther
14bf0 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20  e should be two 
14c00 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
14c10 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72  ents..** The fir
14c20 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
14c30 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
14c40 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
14c50 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a  FK enforcement,.
14c60 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65  ** positive to e
14c70 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65  nable FK enforce
14c80 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65  ment or negative
14c90 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66   to leave FK enf
14ca0 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68  orcement.** unch
14cb0 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f  anged.  The seco
14cc0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
14cd0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
14ce0 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69  integer into whi
14cf0 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e  ch.** is written
14d00 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63   0 or 1 to indic
14d10 61 74 65 20 77 68 65 74 68 65 72 20 46 4b 20 65  ate whether FK e
14d20 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66  nforcement is of
14d30 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f  f or on.** follo
14d40 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20  wing this call. 
14d50 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
14d60 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e  meter may be a N
14d70 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a  ULL pointer, in.
14d80 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68  ** which case th
14d90 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
14da0 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20   setting is not 
14db0 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c  reported back. <
14dc0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
14dd0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
14de0 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64  NABLE_TRIGGER</d
14df0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
14e00 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
14e10 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73  to enable or dis
14e20 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52 49  able [CREATE TRI
14e30 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d  GGER | triggers]
14e40 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c  ..** There shoul
14e50 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f  d be two additio
14e60 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a  nal arguments..*
14e70 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
14e80 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67  ment is an integ
14e90 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f  er which is 0 to
14ea0 20 64 69 73 61 62 6c 65 20 74 72 69 67 67 65 72   disable trigger
14eb0 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74  s,.** positive t
14ec0 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65 72  o enable trigger
14ed0 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f  s or negative to
14ee0 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69   leave the setti
14ef0 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a  ng unchanged..**
14f00 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
14f10 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74  meter is a point
14f20 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
14f30 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69   into which.** i
14f40 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31  s written 0 or 1
14f50 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65   to indicate whe
14f60 74 68 65 72 20 74 72 69 67 67 65 72 73 20 61 72  ther triggers ar
14f70 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e  e disabled or en
14f80 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  abled.** followi
14f90 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54  ng this call.  T
14fa0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
14fb0 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c  ter may be a NUL
14fc0 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a  L pointer, in.**
14fd0 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
14fe0 74 72 69 67 67 65 72 20 73 65 74 74 69 6e 67 20  trigger setting 
14ff0 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20  is not reported 
15000 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  back. </dd>.**.*
15010 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
15020 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
15030 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20  IG_LOOKASIDE    
15040 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64     1001  /* void
15050 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65  * int int */.#de
15060 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
15070 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59  NFIG_ENABLE_FKEY
15080 20 20 20 20 20 31 30 30 32 20 20 2f 2a 20 69 6e       1002  /* in
15090 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e  t int* */.#defin
150a0 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
150b0 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52  G_ENABLE_TRIGGER
150c0 20 20 31 30 30 33 20 20 2f 2a 20 69 6e 74 20 69    1003  /* int i
150d0 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43  nt* */.../*.** C
150e0 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20  API3REF: Enable 
150f0 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e  Or Disable Exten
15100 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73  ded Result Codes
15110 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
15120 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
15130 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74  ult_codes() rout
15140 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  ine enables or d
15150 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b  isables the.** [
15160 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
15170 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f  codes] feature o
15180 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65  f SQLite. ^The e
15190 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a  xtended result.*
151a0 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 61  * codes are disa
151b0 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20  bled by default 
151c0 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63  for historical c
151d0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f  ompatibility..*/
151e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74  .int sqlite3_ext
151f0 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
15200 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  es(sqlite3*, int
15210 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20   onoff);../*.** 
15220 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49  CAPI3REF: Last I
15230 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a  nsert Rowid.**.*
15240 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e  * ^Each entry in
15250 20 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c 65   an SQLite table
15260 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34   has a unique 64
15270 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69  -bit signed.** i
15280 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65  nteger key calle
15290 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22  d the [ROWID | "
152a0 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f  rowid"]. ^The ro
152b0 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76  wid is always av
152c0 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e  ailable.** as an
152d0 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75   undeclared colu
152e0 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20  mn named ROWID, 
152f0 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20  OID, or _ROWID_ 
15300 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65  as long as those
15310 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f  .** names are no
15320 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65  t also used by e
15330 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72  xplicitly declar
15340 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a  ed columns. ^If.
15350 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73  ** the table has
15360 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70   a column of typ
15370 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41  e [INTEGER PRIMA
15380 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61  RY KEY] then tha
15390 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61  t column.** is a
153a0 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72  nother alias for
153b0 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a   the rowid..**.*
153c0 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
153d0 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77  returns the [row
153e0 69 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74 20  id] of the most 
153f0 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73  recent.** succes
15400 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e  sful [INSERT] in
15410 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
15420 66 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62 61  from the [databa
15430 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a  se connection].*
15440 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  * in the first a
15450 72 67 75 6d 65 6e 74 2e 20 20 5e 41 73 20 6f 66  rgument.  ^As of
15460 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
15470 33 2e 37 2e 37 2c 20 74 68 69 73 20 72 6f 75 74  3.7.7, this rout
15480 69 6e 65 73 0a 2a 2a 20 72 65 63 6f 72 64 73 20  ines.** records 
15490 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20  the last insert 
154a0 72 6f 77 69 64 20 6f 66 20 62 6f 74 68 20 6f 72  rowid of both or
154b0 64 69 6e 61 72 79 20 74 61 62 6c 65 73 20 61 6e  dinary tables an
154c0 64 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  d [virtual table
154d0 73 5d 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73 75  s]..** ^If no su
154e0 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
154f0 5d 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20  ]s.** have ever 
15500 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68 61 74  occurred on that
15510 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
15520 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65  tion, zero is re
15530 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  turned..**.** ^(
15540 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f  If an [INSERT] o
15550 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74  ccurs within a t
15560 72 69 67 67 65 72 20 6f 72 20 77 69 74 68 69 6e  rigger or within
15570 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c   a [virtual tabl
15580 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68  e].** method, th
15590 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  en this routine 
155a0 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20  will return the 
155b0 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69  [rowid] of the i
155c0 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61  nserted.** row a
155d0 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72  s long as the tr
155e0 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c  igger or virtual
155f0 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 69 73   table method is
15600 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74   running..** But
15610 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65   once the trigge
15620 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62  r or virtual tab
15630 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20  le method ends, 
15640 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
15650 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72  ed .** by this r
15660 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73 20 74  outine reverts t
15670 6f 20 77 68 61 74 20 69 74 20 77 61 73 20 62 65  o what it was be
15680 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72  fore the trigger
15690 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74   or virtual.** t
156a0 61 62 6c 65 20 6d 65 74 68 6f 64 20 62 65 67 61  able method bega
156b0 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b  n.)^.**.** ^An [
156c0 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61 69  INSERT] that fai
156d0 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73  ls due to a cons
156e0 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
156f0 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63   is not a.** suc
15700 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
15710 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68   and does not ch
15720 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72  ange the value r
15730 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a  eturned by this.
15740 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68  ** routine.  ^Th
15750 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49  us INSERT OR FAI
15760 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e  L, INSERT OR IGN
15770 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52  ORE, INSERT OR R
15780 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20  OLLBACK,.** and 
15790 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20  INSERT OR ABORT 
157a0 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20  make no changes 
157b0 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  to the return va
157c0 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72  lue of this.** r
157d0 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69  outine when thei
157e0 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c  r insertion fail
157f0 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52  s.  ^(When INSER
15800 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20  T OR REPLACE.** 
15810 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e  encounters a con
15820 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
15830 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66  n, it does not f
15840 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53  ail.  The.** INS
15850 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f  ERT continues to
15860 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65   completion afte
15870 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20  r deleting rows 
15880 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74  that caused.** t
15890 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72  he constraint pr
158a0 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20  oblem so INSERT 
158b0 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20  OR REPLACE will 
158c0 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a  always change.**
158d0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
158e0 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66  e of this interf
158f0 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f  ace.)^.**.** ^Fo
15900 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f  r the purposes o
15910 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  f this routine, 
15920 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63  an [INSERT] is c
15930 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20  onsidered to.** 
15940 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 65 76  be successful ev
15950 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 62 73  en if it is subs
15960 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20  equently rolled 
15970 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  back..**.** This
15980 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63   function is acc
15990 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73  essible to SQL s
159a0 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68  tatements via th
159b0 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72  e.** [last_inser
159c0 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75  t_rowid() SQL fu
159d0 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
159e0 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
159f0 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e  ead performs a n
15a00 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74  ew [INSERT] on t
15a10 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62  he same.** datab
15a20 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77  ase connection w
15a30 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65  hile the [sqlite
15a40 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
15a50 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69  wid()].** functi
15a60 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e  on is running an
15a70 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74  d thus changes t
15a80 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b  he last insert [
15a90 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20  rowid],.** then 
15aa0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
15ab0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  ed by [sqlite3_l
15ac0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
15ad0 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64  ()] is.** unpred
15ae0 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68  ictable and migh
15af0 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68  t not equal eith
15b00 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68  er the old or th
15b10 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e  e new.** last in
15b20 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f  sert [rowid]..*/
15b30 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
15b40 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
15b50 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33  rt_rowid(sqlite3
15b60 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
15b70 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e  REF: Count The N
15b80 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
15b90 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68  dified.**.** ^Th
15ba0 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
15bb0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
15bc0 66 20 64 61 74 61 62 61 73 65 20 72 6f 77 73 20  f database rows 
15bd0 74 68 61 74 20 77 65 72 65 20 63 68 61 6e 67 65  that were change
15be0 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65 64  d.** or inserted
15bf0 20 6f 72 20 64 65 6c 65 74 65 64 20 62 79 20 74   or deleted by t
15c00 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79  he most recently
15c10 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20 73   completed SQL s
15c20 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74  tatement.** on t
15c30 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
15c40 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69  nection] specifi
15c50 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
15c60 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28  parameter..** ^(
15c70 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61  Only changes tha
15c80 74 20 61 72 65 20 64 69 72 65 63 74 6c 79 20 73  t are directly s
15c90 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
15ca0 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54  [INSERT], [UPDAT
15cb0 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54  E],.** or [DELET
15cc0 45 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65  E] statement are
15cd0 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c   counted.  Auxil
15ce0 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75  iary changes cau
15cf0 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65  sed by.** trigge
15d00 72 73 20 6f 72 20 5b 66 6f 72 65 69 67 6e 20 6b  rs or [foreign k
15d10 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20  ey actions] are 
15d20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 29 5e 20 55  not counted.)^ U
15d30 73 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  se the.** [sqlit
15d40 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
15d50 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ()] function to 
15d60 66 69 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e  find the total n
15d70 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73  umber of changes
15d80 0a 2a 2a 20 69 6e 63 6c 75 64 69 6e 67 20 63 68  .** including ch
15d90 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
15da0 74 72 69 67 67 65 72 73 20 61 6e 64 20 66 6f 72  triggers and for
15db0 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73  eign key actions
15dc0 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68 61 6e 67 65 73  ..**.** ^Changes
15dd0 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20   to a view that 
15de0 61 72 65 20 73 69 6d 75 6c 61 74 65 64 20 62 79  are simulated by
15df0 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20   an [INSTEAD OF 
15e00 74 72 69 67 67 65 72 5d 0a 2a 2a 20 61 72 65 20  trigger].** are 
15e10 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 20 4f 6e  not counted.  On
15e20 6c 79 20 72 65 61 6c 20 74 61 62 6c 65 20 63 68  ly real table ch
15e30 61 6e 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65  anges are counte
15e40 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f  d..**.** ^(A "ro
15e50 77 20 63 68 61 6e 67 65 22 20 69 73 20 61 20 63  w change" is a c
15e60 68 61 6e 67 65 20 74 6f 20 61 20 73 69 6e 67 6c  hange to a singl
15e70 65 20 72 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c  e row of a singl
15e80 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65  e table.** cause
15e90 64 20 62 79 20 61 6e 20 49 4e 53 45 52 54 2c 20  d by an INSERT, 
15ea0 44 45 4c 45 54 45 2c 20 6f 72 20 55 50 44 41 54  DELETE, or UPDAT
15eb0 45 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f  E statement.  Ro
15ec0 77 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63  ws that.** are c
15ed0 68 61 6e 67 65 64 20 61 73 20 73 69 64 65 20 65  hanged as side e
15ee0 66 66 65 63 74 73 20 6f 66 20 5b 52 45 50 4c 41  ffects of [REPLA
15ef0 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72  CE] constraint r
15f00 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f  esolution,.** ro
15f10 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54 20 70 72  llback, ABORT pr
15f20 6f 63 65 73 73 69 6e 67 2c 20 5b 44 52 4f 50 20  ocessing, [DROP 
15f30 54 41 42 4c 45 5d 2c 20 6f 72 20 62 79 20 61 6e  TABLE], or by an
15f40 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61  y other.** mecha
15f50 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75  nisms do not cou
15f60 6e 74 20 61 73 20 64 69 72 65 63 74 20 72 6f 77  nt as direct row
15f70 20 63 68 61 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a   changes.)^.**.*
15f80 2a 20 41 20 22 74 72 69 67 67 65 72 20 63 6f 6e  * A "trigger con
15f90 74 65 78 74 22 20 69 73 20 61 20 73 63 6f 70 65  text" is a scope
15fa0 20 6f 66 20 65 78 65 63 75 74 69 6f 6e 20 74 68   of execution th
15fb0 61 74 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a  at begins and.**
15fc0 20 65 6e 64 73 20 77 69 74 68 20 74 68 65 20 73   ends with the s
15fd0 63 72 69 70 74 20 6f 66 20 61 20 5b 43 52 45 41  cript of a [CREA
15fe0 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69  TE TRIGGER | tri
15ff0 67 67 65 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20  gger]. .** Most 
16000 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
16010 72 65 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20  re.** evaluated 
16020 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 79 20 74  outside of any t
16030 72 69 67 67 65 72 2e 20 20 54 68 69 73 20 69 73  rigger.  This is
16040 20 74 68 65 20 22 74 6f 70 20 6c 65 76 65 6c 22   the "top level"
16050 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74  .** trigger cont
16060 65 78 74 2e 20 20 49 66 20 61 20 74 72 69 67 67  ext.  If a trigg
16070 65 72 20 66 69 72 65 73 20 66 72 6f 6d 20 74 68  er fires from th
16080 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a  e top level, a.*
16090 2a 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f  * new trigger co
160a0 6e 74 65 78 74 20 69 73 20 65 6e 74 65 72 65 64  ntext is entered
160b0 20 66 6f 72 20 74 68 65 20 64 75 72 61 74 69 6f   for the duratio
160c0 6e 20 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a  n of that one.**
160d0 20 74 72 69 67 67 65 72 2e 20 20 53 75 62 74 72   trigger.  Subtr
160e0 69 67 67 65 72 73 20 63 72 65 61 74 65 20 73 75  iggers create su
160f0 62 63 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 68  bcontexts for th
16100 65 69 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a  eir duration..**
16110 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 5b 73 71  .** ^Calling [sq
16120 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6f 72  lite3_exec()] or
16130 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
16140 5d 20 72 65 63 75 72 73 69 76 65 6c 79 20 64 6f  ] recursively do
16150 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65  es.** not create
16160 20 61 20 6e 65 77 20 74 72 69 67 67 65 72 20 63   a new trigger c
16170 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ontext..**.** ^T
16180 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
16190 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
161a0 6f 66 20 64 69 72 65 63 74 20 72 6f 77 20 63 68  of direct row ch
161b0 61 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20  anges in the.** 
161c0 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45  most recent INSE
161d0 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
161e0 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
161f0 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 0a  within the same.
16200 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ** trigger conte
16210 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c  xt..**.** ^Thus,
16220 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f   when called fro
16230 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c  m the top level,
16240 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72   this function r
16250 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75  eturns the.** nu
16260 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20  mber of changes 
16270 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  in the most rece
16280 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  nt INSERT, UPDAT
16290 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
162a0 74 68 61 74 20 61 6c 73 6f 20 6f 63 63 75 72 72  that also occurr
162b0 65 64 20 61 74 20 74 68 65 20 74 6f 70 20 6c 65  ed at the top le
162c0 76 65 6c 2e 20 20 5e 28 57 69 74 68 69 6e 20 74  vel.  ^(Within t
162d0 68 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69  he body of a tri
162e0 67 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c  gger,.** the sql
162f0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69  ite3_changes() i
16300 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20  nterface can be 
16310 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74  called to find t
16320 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
16330 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d  changes in the m
16340 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d  ost recently com
16350 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55  pleted INSERT, U
16360 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
16370 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69  .** statement wi
16380 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66  thin the body of
16390 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65   the same trigge
163a0 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74  r..** However, t
163b0 68 65 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e  he number return
163c0 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  ed does not incl
163d0 75 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63  ude changes.** c
163e0 61 75 73 65 64 20 62 79 20 73 75 62 74 72 69 67  aused by subtrig
163f0 67 65 72 73 20 73 69 6e 63 65 20 74 68 6f 73 65  gers since those
16400 20 68 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20   have their own 
16410 63 6f 6e 74 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a  context.)^.**.**
16420 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
16430 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
16440 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  nges()] interfac
16450 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74  e, the.** [count
16460 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d  _changes pragma]
16470 2c 20 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67  , and the [chang
16480 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  es() SQL functio
16490 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73  n]..**.** If a s
164a0 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d  eparate thread m
164b0 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20  akes changes on 
164c0 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
164d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
164e0 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63  while [sqlite3_c
164f0 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e  hanges()] is run
16500 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61  ning then the va
16510 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  lue returned.** 
16520 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  is unpredictable
16530 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67   and not meaning
16540 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ful..*/.int sqli
16550 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69  te3_changes(sqli
16560 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
16570 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75  PI3REF: Total Nu
16580 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64  mber Of Rows Mod
16590 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  ified.**.** ^Thi
165a0 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
165b0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
165c0 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75   row changes cau
165d0 73 65 64 20 62 79 20 5b 49 4e 53 45 52 54 5d 2c  sed by [INSERT],
165e0 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 20 6f 72 20  .** [UPDATE] or 
165f0 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65  [DELETE] stateme
16600 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20 5b 64  nts since the [d
16610 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
16620 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a  on] was opened..
16630 2a 2a 20 5e 28 54 68 65 20 63 6f 75 6e 74 20 72  ** ^(The count r
16640 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
16650 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
16660 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20  () includes all 
16670 63 68 61 6e 67 65 73 0a 2a 2a 20 66 72 6f 6d 20  changes.** from 
16680 61 6c 6c 20 5b 43 52 45 41 54 45 20 54 52 49 47  all [CREATE TRIG
16690 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d 20 63  GER | trigger] c
166a0 6f 6e 74 65 78 74 73 20 61 6e 64 20 63 68 61 6e  ontexts and chan
166b0 67 65 73 20 6d 61 64 65 20 62 79 0a 2a 2a 20 5b  ges made by.** [
166c0 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69  foreign key acti
166d0 6f 6e 73 5d 2e 20 48 6f 77 65 76 65 72 2c 0a 2a  ons]. However,.*
166e0 2a 20 74 68 65 20 63 6f 75 6e 74 20 64 6f 65 73  * the count does
166f0 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61   not include cha
16700 6e 67 65 73 20 75 73 65 64 20 74 6f 20 69 6d 70  nges used to imp
16710 6c 65 6d 65 6e 74 20 5b 52 45 50 4c 41 43 45 5d  lement [REPLACE]
16720 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a   constraints,.**
16730 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72   do rollbacks or
16740 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e   ABORT processin
16750 67 2c 20 6f 72 20 5b 44 52 4f 50 20 54 41 42 4c  g, or [DROP TABL
16760 45 5d 20 70 72 6f 63 65 73 73 69 6e 67 2e 20 20  E] processing.  
16770 54 68 65 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f 65  The.** count doe
16780 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 72 6f  s not include ro
16790 77 73 20 6f 66 20 76 69 65 77 73 20 74 68 61 74  ws of views that
167a0 20 66 69 72 65 20 61 6e 20 5b 49 4e 53 54 45 41   fire an [INSTEA
167b0 44 20 4f 46 20 74 72 69 67 67 65 72 5d 2c 0a 2a  D OF trigger],.*
167c0 2a 20 74 68 6f 75 67 68 20 69 66 20 74 68 65 20  * though if the 
167d0 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
167e0 65 72 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  er makes changes
167f0 20 6f 66 20 69 74 73 20 6f 77 6e 2c 20 74 68 6f   of its own, tho
16800 73 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20 61  se changes .** a
16810 72 65 20 63 6f 75 6e 74 65 64 2e 29 5e 0a 2a 2a  re counted.)^.**
16820 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 6f   ^The sqlite3_to
16830 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 66 75  tal_changes() fu
16840 6e 63 74 69 6f 6e 20 63 6f 75 6e 74 73 20 74 68  nction counts th
16850 65 20 63 68 61 6e 67 65 73 20 61 73 20 73 6f 6f  e changes as soo
16860 6e 20 61 73 0a 2a 2a 20 74 68 65 20 73 74 61 74  n as.** the stat
16870 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 73  ement that makes
16880 20 74 68 65 6d 20 69 73 20 63 6f 6d 70 6c 65 74   them is complet
16890 65 64 20 28 77 68 65 6e 20 74 68 65 20 73 74 61  ed (when the sta
168a0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 0a 2a 2a  tement handle.**
168b0 20 69 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73   is passed to [s
168c0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
168d0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
168e0 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20  lize()])..**.** 
168f0 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71  See also the [sq
16900 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d  lite3_changes()]
16910 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a   interface, the.
16920 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65  ** [count_change
16930 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74  s pragma], and t
16940 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65  he [total_change
16950 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  s() SQL function
16960 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65  ]..**.** If a se
16970 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61  parate thread ma
16980 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74  kes changes on t
16990 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
169a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77   connection.** w
169b0 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f  hile [sqlite3_to
169c0 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  tal_changes()] i
169d0 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74  s running then t
169e0 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75  he value.** retu
169f0 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 63  rned is unpredic
16a00 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65  table and not me
16a10 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74  aningful..*/.int
16a20 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63   sqlite3_total_c
16a30 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29  hanges(sqlite3*)
16a40 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
16a50 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c  F: Interrupt A L
16a60 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72  ong-Running Quer
16a70 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  y.**.** ^This fu
16a80 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e  nction causes an
16a90 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61  y pending databa
16aa0 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20  se operation to 
16ab0 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74  abort and.** ret
16ac0 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69  urn at its earli
16ad0 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e  est opportunity.
16ae0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   This routine is
16af0 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61   typically.** ca
16b00 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65  lled in response
16b10 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f   to a user actio
16b20 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 73 69  n such as pressi
16b30 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f  ng "Cancel".** o
16b40 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74  r Ctrl-C where t
16b50 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 61 20  he user wants a 
16b60 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61  long query opera
16b70 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20  tion to halt.** 
16b80 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a  immediately..**.
16b90 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65 20 74  ** ^It is safe t
16ba0 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74  o call this rout
16bb0 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61  ine from a threa
16bc0 64 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d  d different from
16bd0 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74   the.** thread t
16be0 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79  hat is currently
16bf0 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74   running the dat
16c00 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e  abase operation.
16c10 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e    But it.** is n
16c20 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20  ot safe to call 
16c30 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74  this routine wit
16c40 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  h a [database co
16c50 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a  nnection] that.*
16c60 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d  * is closed or m
16c70 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72  ight close befor
16c80 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
16c90 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a  upt() returns..*
16ca0 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20  *.** ^If an SQL 
16cb0 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72  operation is ver
16cc0 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65  y nearly finishe
16cd0 64 20 61 74 20 74 68 65 20 74 69 6d 65 20 77 68  d at the time wh
16ce0 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e  en.** sqlite3_in
16cf0 74 65 72 72 75 70 74 28 29 20 69 73 20 63 61 6c  terrupt() is cal
16d00 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67  led, then it mig
16d10 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f  ht not have an o
16d20 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f  pportunity.** to
16d30 20 62 65 20 69 6e 74 65 72 72 75 70 74 65 64 20   be interrupted 
16d40 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e  and might contin
16d50 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  ue to completion
16d60 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20  ..**.** ^An SQL 
16d70 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69  operation that i
16d80 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 77 69  s interrupted wi
16d90 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
16da0 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a  E_INTERRUPT]..**
16db0 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72 72 75   ^If the interru
16dc0 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69  pted SQL operati
16dd0 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c  on is an INSERT,
16de0 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
16df0 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e  TE.** that is in
16e00 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74  side an explicit
16e10 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68   transaction, th
16e20 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74 72  en the entire tr
16e30 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c  ansaction.** wil
16e40 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b  l be rolled back
16e50 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a   automatically..
16e60 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
16e70 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20  e3_interrupt(D) 
16e80 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 63  call is in effec
16e90 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72  t until all curr
16ea0 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a  ently running.**
16eb0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
16ec0 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
16ed0 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c  nection] D compl
16ee0 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53  ete.  ^Any new S
16ef0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
16f00 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
16f10 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69  d after the sqli
16f20 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
16f30 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20  call and before 
16f40 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20  the .** running 
16f50 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68  statements reach
16f60 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65  es zero are inte
16f70 72 72 75 70 74 65 64 20 61 73 20 69 66 20 74 68  rrupted as if th
16f80 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72  ey had been.** r
16f90 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20  unning prior to 
16fa0 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
16fb0 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e  rrupt() call.  ^
16fc0 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  New SQL statemen
16fd0 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
16fe0 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65  tarted after the
16ff0 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65   running stateme
17000 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73  nt count reaches
17010 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74   zero are.** not
17020 20 65 66 66 65 63 74 65 64 20 62 79 20 74 68 65   effected by the
17030 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
17040 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c  pt()..** ^A call
17050 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65   to sqlite3_inte
17060 72 72 75 70 74 28 44 29 20 74 68 61 74 20 6f 63  rrupt(D) that oc
17070 63 75 72 73 20 77 68 65 6e 20 74 68 65 72 65 20  curs when there 
17080 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a  are no running.*
17090 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
170a0 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20   is a no-op and 
170b0 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e  has no effect on
170c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
170d0 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
170e0 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71  ted after the sq
170f0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
17100 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a  ) call returns..
17110 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74  **.** If the dat
17120 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
17130 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b 73   closes while [s
17140 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
17150 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e  ()].** is runnin
17160 67 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e 67  g then bad thing
17170 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61  s will likely ha
17180 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  ppen..*/.void sq
17190 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
171a0 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
171b0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65  * CAPI3REF: Dete
171c0 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20  rmine If An SQL 
171d0 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d  Statement Is Com
171e0 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73  plete.**.** Thes
171f0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75  e routines are u
17200 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d  seful during com
17210 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20  mand-line input 
17220 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20  to determine if 
17230 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79  the.** currently
17240 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73 65   entered text se
17250 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f  ems to form a co
17260 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65  mplete SQL state
17270 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64  ment or.** if ad
17280 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69  ditional input i
17290 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20  s needed before 
172a0 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74  sending the text
172b0 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20   into.** SQLite 
172c0 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 5e 54  for parsing.  ^T
172d0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
172e0 74 75 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e  turn 1 if the in
172f0 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70  put string.** ap
17300 70 65 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f  pears to be a co
17310 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65  mplete SQL state
17320 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 6d  ment.  ^A statem
17330 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f  ent is judged to
17340 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20   be.** complete 
17350 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 68 20  if it ends with 
17360 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65  a semicolon toke
17370 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70  n and is not a p
17380 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65  refix of a.** we
17390 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45  ll-formed CREATE
173a0 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d 65   TRIGGER stateme
173b0 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73  nt.  ^Semicolons
173c0 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 64 64   that are embedd
173d0 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72  ed within.** str
173e0 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20  ing literals or 
173f0 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65  quoted identifie
17400 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65  r names or comme
17410 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69  nts are not.** i
17420 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e  ndependent token
17430 73 20 28 74 68 65 79 20 61 72 65 20 70 61 72 74  s (they are part
17440 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e   of the token in
17450 20 77 68 69 63 68 20 74 68 65 79 20 61 72 65 0a   which they are.
17460 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64  ** embedded) and
17470 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75   thus do not cou
17480 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e  nt as a statemen
17490 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e  t terminator.  ^
174a0 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e  Whitespace.** an
174b0 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20  d comments that 
174c0 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c  follow the final
174d0 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69   semicolon are i
174e0 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gnored..**.** ^T
174f0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
17500 74 75 72 6e 20 30 20 69 66 20 74 68 65 20 73 74  turn 0 if the st
17510 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d  atement is incom
17520 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a  plete.  ^If a.**
17530 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
17540 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53  on fails, then S
17550 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72  QLITE_NOMEM is r
17560 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
17570 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64  These routines d
17580 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20  o not parse the 
17590 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74  SQL statements t
175a0 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20  hus.** will not 
175b0 64 65 74 65 63 74 20 73 79 6e 74 61 63 74 69 63  detect syntactic
175c0 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53  ally incorrect S
175d0 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53  QL..**.** ^(If S
175e0 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65  QLite has not be
175f0 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75  en initialized u
17600 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e  sing [sqlite3_in
17610 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f  itialize()] prio
17620 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e  r .** to invokin
17630 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  g sqlite3_comple
17640 74 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69  te16() then sqli
17650 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
17660 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61   is invoked.** a
17670 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20  utomatically by 
17680 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
17690 31 36 28 29 2e 20 20 49 66 20 74 68 61 74 20 69  16().  If that i
176a0 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61  nitialization fa
176b0 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ils,.** then the
176c0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
176d0 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  om sqlite3_compl
176e0 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20  ete16() will be 
176f0 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61  non-zero.** rega
17700 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
17710 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70  r or not the inp
17720 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65  ut SQL is comple
17730 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  te.)^.**.** The 
17740 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
17750 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75  3_complete()] mu
17760 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72  st be a zero-ter
17770 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38  minated.** UTF-8
17780 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54   string..**.** T
17790 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  he input to [sql
177a0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
177b0 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72  )] must be a zer
177c0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
177d0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e  UTF-16 string in
177e0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
177f0 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  er..*/.int sqlit
17800 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73  e3_complete(cons
17810 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e  t char *sql);.in
17820 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  t sqlite3_comple
17830 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20  te16(const void 
17840 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  *sql);../*.** CA
17850 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72  PI3REF: Register
17860 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48   A Callback To H
17870 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53  andle SQLITE_BUS
17880 59 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e  Y Errors.**.** ^
17890 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74  This routine set
178a0 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
178b0 63 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 68 74  ction that might
178c0 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
178d0 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d  ever.** an attem
178e0 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70  pt is made to op
178f0 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61  en a database ta
17900 62 6c 65 20 74 68 61 74 20 61 6e 6f 74 68 65 72  ble that another
17910 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72   thread.** or pr
17920 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 6b 65 64  ocess has locked
17930 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
17940 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  busy callback is
17950 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c   NULL, then [SQL
17960 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51  ITE_BUSY] or [SQ
17970 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
17980 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  ED].** is return
17990 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75  ed immediately u
179a0 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67  pon encountering
179b0 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20   the lock.  ^If 
179c0 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  the busy callbac
179d0 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  k.** is not NULL
179e0 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  , then the callb
179f0 61 63 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76  ack might be inv
17a00 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 72  oked with two ar
17a10 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  guments..**.** ^
17a20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
17a30 6e 74 20 74 6f 20 74 68 65 20 62 75 73 79 20 68  nt to the busy h
17a40 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79  andler is a copy
17a50 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f   of the void* po
17a60 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69  inter which.** i
17a70 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75  s the third argu
17a80 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
17a90 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20  busy_handler(). 
17aa0 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67   ^The second arg
17ab0 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20  ument to.** the 
17ac0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c  busy handler cal
17ad0 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d  lback is the num
17ae0 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61  ber of times tha
17af0 74 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  t the busy handl
17b00 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69  er has.** been i
17b10 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 69 73 20  nvoked for this 
17b20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20  locking event.  
17b30 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20  ^If the.** busy 
17b40 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
17b50 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69   0, then no addi
17b60 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20  tional attempts 
17b70 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61  are made to.** a
17b80 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61  ccess the databa
17b90 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42  se and [SQLITE_B
17ba0 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  USY] or [SQLITE_
17bb0 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69  IOERR_BLOCKED] i
17bc0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e  s returned..** ^
17bd0 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
17be0 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
17bf0 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61  , then another a
17c00 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64  ttempt.** is mad
17c10 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61  e to open the da
17c20 74 61 62 61 73 65 20 66 6f 72 20 72 65 61 64 69  tabase for readi
17c30 6e 67 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65  ng and the cycle
17c40 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20   repeats..**.** 
17c50 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20  The presence of 
17c60 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  a busy handler d
17c70 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65  oes not guarante
17c80 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62  e that it will b
17c90 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65  e invoked.** whe
17ca0 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20  n there is lock 
17cb0 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20  contention. ^If 
17cc0 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65  SQLite determine
17cd0 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20  s that invoking 
17ce0 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64  the busy.** hand
17cf0 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74  ler could result
17d00 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20   in a deadlock, 
17d10 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64  it will go ahead
17d20 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c   and return [SQL
17d30 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20  ITE_BUSY].** or 
17d40 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
17d50 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61 64 20 6f  OCKED] instead o
17d60 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62  f invoking the b
17d70 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20  usy handler..** 
17d80 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61  Consider a scena
17d90 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72  rio where one pr
17da0 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67  ocess is holding
17db0 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61   a read lock tha
17dc0 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e  t.** it is tryin
17dd0 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20  g to promote to 
17de0 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20  a reserved lock 
17df0 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20  and.** a second 
17e00 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69  process is holdi
17e10 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f  ng a reserved lo
17e20 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 72  ck that it is tr
17e30 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f  ying.** to promo
17e40 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69  te to an exclusi
17e50 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69  ve lock.  The fi
17e60 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e  rst process cann
17e70 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65  ot proceed.** be
17e80 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63  cause it is bloc
17e90 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e  ked by the secon
17ea0 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  d and the second
17eb0 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a   process cannot.
17ec0 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 75  ** proceed becau
17ed0 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64  se it is blocked
17ee0 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 20   by the first.  
17ef0 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65  If both processe
17f00 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20  s.** invoke the 
17f10 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e  busy handlers, n
17f20 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65  either will make
17f30 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20   any progress.  
17f40 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51  Therefore,.** SQ
17f50 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51  Lite returns [SQ
17f60 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74  LITE_BUSY] for t
17f70 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
17f80 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68  , hoping that th
17f90 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63  is.** will induc
17fa0 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63  e the first proc
17fb0 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69  ess to release i
17fc0 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64  ts read lock and
17fd0 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65   allow.** the se
17fe0 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20  cond process to 
17ff0 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  proceed..**.** ^
18000 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79  The default busy
18010 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c   callback is NUL
18020 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53  L..**.** ^The [S
18030 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 72 6f  QLITE_BUSY] erro
18040 72 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 74  r is converted t
18050 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  o [SQLITE_IOERR_
18060 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e  BLOCKED].** when
18070 20 53 51 4c 69 74 65 20 69 73 20 69 6e 20 74 68   SQLite is in th
18080 65 20 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c 61  e middle of a la
18090 72 67 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  rge transaction 
180a0 77 68 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a  where all the.**
180b0 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f   changes will no
180c0 74 20 66 69 74 20 69 6e 74 6f 20 74 68 65 20 69  t fit into the i
180d0 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e 20  n-memory cache. 
180e0 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20   SQLite will.** 
180f0 61 6c 72 65 61 64 79 20 68 6f 6c 64 20 61 20 52  already hold a R
18100 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20  ESERVED lock on 
18110 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
18120 65 2c 20 62 75 74 20 69 74 20 6e 65 65 64 73 0a  e, but it needs.
18130 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68  ** to promote th
18140 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55  is lock to EXCLU
18150 53 49 56 45 20 73 6f 20 74 68 61 74 20 69 74 20  SIVE so that it 
18160 63 61 6e 20 73 70 69 6c 6c 20 63 61 63 68 65 0a  can spill cache.
18170 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f 20 74 68  ** pages into th
18180 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
18190 77 69 74 68 6f 75 74 20 68 61 72 6d 20 74 6f 20  without harm to 
181a0 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65  concurrent.** re
181b0 61 64 65 72 73 2e 20 20 5e 49 66 20 69 74 20 69  aders.  ^If it i
181c0 73 20 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d  s unable to prom
181d0 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68  ote the lock, th
181e0 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79  en the in-memory
181f0 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c 20 62  .** cache will b
18200 65 20 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e 63  e left in an inc
18210 6f 6e 73 69 73 74 65 6e 74 20 73 74 61 74 65 20  onsistent state 
18220 61 6e 64 20 73 6f 20 74 68 65 20 65 72 72 6f 72  and so the error
18230 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70 72 6f 6d  .** code is prom
18240 6f 74 65 64 20 66 72 6f 6d 20 74 68 65 20 72 65  oted from the re
18250 6c 61 74 69 76 65 6c 79 20 62 65 6e 69 67 6e 20  latively benign 
18260 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f  [SQLITE_BUSY] to
18270 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 65 76  .** the more sev
18280 65 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  ere [SQLITE_IOER
18290 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54 68  R_BLOCKED].  ^Th
182a0 69 73 20 65 72 72 6f 72 20 63 6f 64 65 20 70 72  is error code pr
182b0 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65  omotion.** force
182c0 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 72  s an automatic r
182d0 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 63  ollback of the c
182e0 68 61 6e 67 65 73 2e 20 20 53 65 65 20 74 68 65  hanges.  See the
182f0 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f 63 76  .** <a href="/cv
18300 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72  strac/wiki?p=Cor
18310 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67  ruptionFollowing
18320 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43  BusyError">.** C
18330 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69  orruptionFollowi
18340 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20  ngBusyError</a> 
18350 77 69 6b 69 20 70 61 67 65 20 66 6f 72 20 61 20  wiki page for a 
18360 64 69 73 63 75 73 73 69 6f 6e 20 6f 66 20 77 68  discussion of wh
18370 79 0a 2a 2a 20 74 68 69 73 20 69 73 20 69 6d 70  y.** this is imp
18380 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ortant..**.** ^(
18390 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62  There can only b
183a0 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20  e a single busy 
183b0 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20  handler defined 
183c0 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74  for each.** [dat
183d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
183e0 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65  ].  Setting a ne
183f0 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63  w busy handler c
18400 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65  lears any.** pre
18410 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64  viously set hand
18420 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68  ler.)^  ^Note th
18430 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  at calling [sqli
18440 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
18450 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f  ()].** will also
18460 20 73 65 74 20 6f 72 20 63 6c 65 61 72 20 74 68   set or clear th
18470 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
18480 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63  **.** The busy c
18490 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e  allback should n
184a0 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69  ot take any acti
184b0 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79  ons which modify
184c0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
184d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
184e0 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73   invoked the bus
184f0 79 20 68 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20  y handler.  Any 
18500 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20  such actions.** 
18510 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69  result in undefi
18520 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ned behavior..**
18530 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64   .** A busy hand
18540 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f  ler must not clo
18550 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
18560 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72  connection.** or
18570 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
18580 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b  ment] that invok
18590 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ed the busy hand
185a0 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ler..*/.int sqli
185b0 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
185c0 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a  (sqlite3*, int(*
185d0 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f  )(void*,int), vo
185e0 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
185f0 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73  I3REF: Set A Bus
18600 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20  y Timeout.**.** 
18610 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65  ^This routine se
18620 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75  ts a [sqlite3_bu
18630 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73  sy_handler | bus
18640 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20  y handler] that 
18650 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20  sleeps.** for a 
18660 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74  specified amount
18670 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20   of time when a 
18680 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e  table is locked.
18690 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a    ^The handler.*
186a0 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c  * will sleep mul
186b0 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69  tiple times unti
186c0 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20  l at least "ms" 
186d0 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
186e0 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65  sleeping.** have
186f0 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e   accumulated.  ^
18700 41 66 74 65 72 20 61 74 20 6c 65 61 73 74 20 22  After at least "
18710 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73  ms" milliseconds
18720 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a   of sleeping,.**
18730 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74   the handler ret
18740 75 72 6e 73 20 30 20 77 68 69 63 68 20 63 61 75  urns 0 which cau
18750 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ses [sqlite3_ste
18760 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a  p()] to return.*
18770 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  * [SQLITE_BUSY] 
18780 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
18790 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a  _BLOCKED]..**.**
187a0 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72   ^Calling this r
187b0 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61  outine with an a
187c0 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61  rgument less tha
187d0 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65  n or equal to ze
187e0 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20  ro.** turns off 
187f0 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72  all busy handler
18800 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65  s..**.** ^(There
18810 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73   can only be a s
18820 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c  ingle busy handl
18830 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  er for a particu
18840 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  lar.** [database
18850 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79   connection] any
18860 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e   any given momen
18870 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62  t.  If another b
18880 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77  usy handler.** w
18890 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 69  as defined  (usi
188a0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ng [sqlite3_busy
188b0 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69  _handler()]) pri
188c0 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a  or to calling.**
188d0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74   this routine, t
188e0 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68  hat other busy h
188f0 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65  andler is cleare
18900 64 2e 29 5e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  d.)^.*/.int sqli
18910 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
18920 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d  (sqlite3*, int m
18930 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  s);../*.** CAPI3
18940 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65  REF: Convenience
18950 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75   Routines For Ru
18960 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a  nning Queries.**
18970 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 6c 65  .** This is a le
18980 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 20 74  gacy interface t
18990 68 61 74 20 69 73 20 70 72 65 73 65 72 76 65 64  hat is preserved
189a0 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
189b0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
189c0 20 55 73 65 20 6f 66 20 74 68 69 73 20 69 6e 74   Use of this int
189d0 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65  erface is not re
189e0 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a  commended..**.**
189f0 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c   Definition: A <
18a00 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f  b>result table</
18a10 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74  b> is memory dat
18a20 61 20 73 74 72 75 63 74 75 72 65 20 63 72 65 61  a structure crea
18a30 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73  ted by the.** [s
18a40 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
18a50 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ()] interface.  
18a60 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72  A result table r
18a70 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f  ecords the.** co
18a80 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 65 73  mplete query res
18a90 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72  ults from one or
18aa0 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a   more queries..*
18ab0 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63  *.** The table c
18ac0 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20  onceptually has 
18ad0 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  a number of rows
18ae0 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42   and columns.  B
18af0 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62  ut.** these numb
18b00 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74  ers are not part
18b10 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74   of the result t
18b20 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68  able itself.  Th
18b30 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61  ese.** numbers a
18b40 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61  re obtained sepa
18b50 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62  rately.  Let N b
18b60 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  e the number of 
18b70 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65  rows.** and M be
18b80 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
18b90 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20  olumns..**.** A 
18ba0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20  result table is 
18bb0 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
18bc0 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72  ters to zero-ter
18bd0 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
18be0 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20  rings..** There 
18bf0 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d  are (N+1)*M elem
18c00 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72 61  ents in the arra
18c10 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d 20  y.  The first M 
18c20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a  pointers point.*
18c30 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  * to zero-termin
18c40 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61  ated strings tha
18c50 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e  t  contain the n
18c60 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75  ames of the colu
18c70 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61  mns..** The rema
18c80 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c  ining entries al
18c90 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79  l point to query
18ca0 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20   results.  NULL 
18cb0 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a  values result.**
18cc0 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   in NULL pointer
18cd0 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61  s.  All other va
18ce0 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 65 69  lues are in thei
18cf0 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72  r UTF-8 zero-ter
18d00 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e  minated.** strin
18d10 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  g representation
18d20 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20   as returned by 
18d30 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
18d40 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41  text()]..**.** A
18d50 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69   result table mi
18d60 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f  ght consist of o
18d70 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72  ne or more memor
18d80 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a  y allocations..*
18d90 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65  * It is not safe
18da0 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c   to pass a resul
18db0 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79  t table directly
18dc0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
18dd0 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c  e()]..** A resul
18de0 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62  t table should b
18df0 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73  e deallocated us
18e00 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  ing [sqlite3_fre
18e10 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a  e_table()]..**.*
18e20 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d 70 6c  * ^(As an exampl
18e30 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  e of the result 
18e40 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75  table format, su
18e50 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 72 65  ppose a query re
18e60 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f  sult.** is as fo
18e70 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
18e80 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
18e90 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20  *        Name   
18ea0 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20       | Age.**   
18eb0 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d       -----------
18ec0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20  ------------.** 
18ed0 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20 20         Alice    
18ee0 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20     | 43.**      
18ef0 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20    Bob         | 
18f00 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e  28.**        Cin
18f10 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a  dy       | 21.**
18f20 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
18f30 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65  ote>.**.** There
18f40 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20   are two column 
18f50 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65  (M==2) and three
18f60 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54   rows (N==3).  T
18f70 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c  hus the.** resul
18f80 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e  t table has 8 en
18f90 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20  tries.  Suppose 
18fa0 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
18fb0 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e   is stored.** in
18fc0 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20   an array names 
18fd0 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20  azResult.  Then 
18fe0 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74  azResult holds t
18ff0 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a  his content:.**.
19000 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
19010 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61  pre>.**        a
19020 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d  zResult&#91;0] =
19030 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20   "Name";.**     
19040 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
19050 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20  1] = "Age";.**  
19060 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
19070 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b  91;2] = "Alice";
19080 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
19090 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33  ult&#91;3] = "43
190a0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
190b0 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22  esult&#91;4] = "
190c0 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  Bob";.**        
190d0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20  azResult&#91;5] 
190e0 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20  = "28";.**      
190f0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36    azResult&#91;6
19100 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20  ] = "Cindy";.** 
19110 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
19120 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a  #91;7] = "21";.*
19130 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
19140 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  uote>)^.**.** ^T
19150 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
19160 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  able() function 
19170 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72  evaluates one or
19180 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c   more.** semicol
19190 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c  on-separated SQL
191a0 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74   statements in t
191b0 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  he zero-terminat
191c0 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69  ed UTF-8.** stri
191d0 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61  ng of its 2nd pa
191e0 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75  rameter and retu
191f0 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61 62  rns a result tab
19200 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69  le to the.** poi
19210 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74  nter given in it
19220 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e  s 3rd parameter.
19230 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65  .**.** After the
19240 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61 73   application has
19250 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 74   finished with t
19260 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 73  he result from s
19270 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
19280 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70  (),.** it must p
19290 61 73 73 20 74 68 65 20 72 65 73 75 6c 74 20 74  ass the result t
192a0 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f 20  able pointer to 
192b0 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
192c0 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f  le() in order to
192d0 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20  .** release the 
192e0 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20  memory that was 
192f0 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75  malloced.  Becau
19300 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 68  se of the way th
19310 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61  e.** [sqlite3_ma
19320 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20  lloc()] happens 
19330 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67  within sqlite3_g
19340 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20  et_table(), the 
19350 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74  calling.** funct
19360 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79  ion must not try
19370 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65   to call [sqlite
19380 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63 74  3_free()] direct
19390 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71  ly.  Only.** [sq
193a0 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
193b0 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72  ()] is able to r
193c0 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72  elease the memor
193d0 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73  y properly and s
193e0 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  afely..**.** The
193f0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
19400 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  le() interface i
19410 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73  s implemented as
19420 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e   a wrapper aroun
19430 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  d.** [sqlite3_ex
19440 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69  ec()].  The sqli
19450 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
19460 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74  routine does not
19470 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20   have access.** 
19480 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20  to any internal 
19490 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20  data structures 
194a0 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75  of SQLite.  It u
194b0 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62  ses only the pub
194c0 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  lic.** interface
194d0 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20   defined here.  
194e0 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65  As a consequence
194f0 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63  , errors that oc
19500 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72  cur in the.** wr
19510 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73  apper layer outs
19520 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72  ide of the inter
19530 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  nal [sqlite3_exe
19540 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f  c()] call are no
19550 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69  t.** reflected i
19560 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  n subsequent cal
19570 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ls to [sqlite3_e
19580 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20  rrcode()] or.** 
19590 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
195a0 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
195b0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20  e3_get_table(.  
195c0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
195d0 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e        /* An open
195e0 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63   database */.  c
195f0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
19600 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62       /* SQL to b
19610 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20  e evaluated */. 
19620 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75   char ***pazResu
19630 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74  lt,    /* Result
19640 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a  s of the query *
19650 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20  /.  int *pnRow, 
19660 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d            /* Num
19670 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f  ber of result ro
19680 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  ws written here 
19690 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75  */.  int *pnColu
196a0 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75  mn,        /* Nu
196b0 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63  mber of result c
196c0 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68  olumns written h
196d0 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ere */.  char **
196e0 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f  pzErrmsg       /
196f0 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
19700 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76  ten here */.);.v
19710 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65  oid sqlite3_free
19720 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65  _table(char **re
19730 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  sult);../*.** CA
19740 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65  PI3REF: Formatte
19750 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e  d String Printin
19760 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  g Functions.**.*
19770 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
19780 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73   are work-alikes
19790 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28   of the "printf(
197a0 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e  )" family of fun
197b0 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74  ctions.** from t
197c0 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
197d0 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  brary..**.** ^Th
197e0 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  e sqlite3_mprint
197f0 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  f() and sqlite3_
19800 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  vmprintf() routi
19810 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a  nes write their.
19820 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20  ** results into 
19830 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
19840 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
19850 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  lloc()]..** The 
19860 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  strings returned
19870 20 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f   by these two ro
19880 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65  utines should be
19890 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20  .** released by 
198a0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
198b0 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65  .  ^Both routine
198c0 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55  s return a.** NU
198d0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73  LL pointer if [s
198e0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
198f0 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
19900 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a  locate enough.**
19910 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20   memory to hold 
19920 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74  the resulting st
19930 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ring..**.** ^(Th
19940 65 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  e sqlite3_snprin
19950 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  tf() routine is 
19960 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72  similar to "snpr
19970 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20  intf()" from.** 
19980 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
19990 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73  ibrary.  The res
199a0 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69  ult is written i
199b0 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65  nto the.** buffe
199c0 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68  r supplied as th
199d0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
199e0 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73  er whose size is
199f0 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65   given by.** the
19a00 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
19a10 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  . Note that the 
19a20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20  order of the.** 
19a30 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65  first two parame
19a40 74 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64  ters is reversed
19a50 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29   from snprintf()
19a60 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a  .)^  This is an.
19a70 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63  ** historical ac
19a80 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e  cident that cann
19a90 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68  ot be fixed with
19aa0 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20  out breaking.** 
19ab0 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
19ac0 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65  ibility.  ^(Note
19ad0 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74   also that sqlit
19ae0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
19af0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
19b00 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72  er to its buffer
19b10 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20   instead of the 
19b20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61  number of.** cha
19b30 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79  racters actually
19b40 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68   written into th
19b50 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20  e buffer.)^  We 
19b60 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68  admit that.** th
19b70 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
19b80 61 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77  acters written w
19b90 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75  ould be a more u
19ba0 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20  seful return.** 
19bb0 76 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e  value but we can
19bc0 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69  not change the i
19bd0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
19be0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
19bf0 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f  f().** now witho
19c00 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70  ut breaking comp
19c10 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a  atibility..**.**
19c20 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65   ^As long as the
19c30 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 20   buffer size is 
19c40 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72  greater than zer
19c50 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  o, sqlite3_snpri
19c60 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74  ntf().** guarant
19c70 65 65 73 20 74 68 61 74 20 74 68 65 20 62 75 66  ees that the buf
19c80 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65  fer is always ze
19c90 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ro-terminated.  
19ca0 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61  ^The first.** pa
19cb0 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74  rameter "n" is t
19cc0 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66  he total size of
19cd0 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63   the buffer, inc
19ce0 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72  luding space for
19cf0 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72  .** the zero ter
19d00 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65  minator.  So the
19d10 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20   longest string 
19d20 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70  that can be comp
19d30 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65  letely.** writte
19d40 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68  n will be n-1 ch
19d50 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
19d60 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 73 6e  ^The sqlite3_vsn
19d70 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65  printf() routine
19d80 20 69 73 20 61 20 76 61 72 61 72 67 73 20 76 65   is a varargs ve
19d90 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  rsion of sqlite3
19da0 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a  _snprintf()..**.
19db0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
19dc0 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20  s all implement 
19dd0 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20  some additional 
19de0 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70  formatting.** op
19df0 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75  tions that are u
19e00 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72  seful for constr
19e10 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65  ucting SQL state
19e20 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66  ments..** All of
19e30 20 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74   the usual print
19e40 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  f() formatting o
19e50 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49  ptions apply.  I
19e60 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72  n addition, ther
19e70 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22  e.** is are "%q"
19e80 2c 20 22 25 51 22 2c 20 61 6e 64 20 22 25 7a 22  , "%Q", and "%z"
19e90 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20   options..**.** 
19ea0 5e 28 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20  ^(The %q option 
19eb0 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e  works like %s in
19ec0 20 74 68 61 74 20 69 74 20 73 75 62 73 74 69 74   that it substit
19ed0 75 74 65 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69  utes a nul-termi
19ee0 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20  nated.** string 
19ef0 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e  from the argumen
19f00 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20  t list.  But %q 
19f10 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65  also doubles eve
19f20 72 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65  ry '\'' characte
19f30 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69  r..** %q is desi
19f40 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73  gned for use ins
19f50 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74  ide a string lit
19f60 65 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62  eral.)^  By doub
19f70 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a  ling each '\''.*
19f80 2a 20 63 68 61 72 61 63 74 65 72 20 69 74 20 65  * character it e
19f90 73 63 61 70 65 73 20 74 68 61 74 20 63 68 61 72  scapes that char
19fa0 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73  acter and allows
19fb0 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74   it to be insert
19fc0 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73  ed into.** the s
19fd0 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72  tring..**.** For
19fe0 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65   example, assume
19ff0 20 74 68 65 20 73 74 72 69 6e 67 20 76 61 72 69   the string vari
1a000 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61  able zText conta
1a010 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c  ins text as foll
1a020 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
1a030 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1a040 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22   char *zText = "
1a050 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79  It's a happy day
1a060 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  !";.** </pre></b
1a070 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1a080 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69   One can use thi
1a090 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c  s text in an SQL
1a0a0 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f   statement as fo
1a0b0 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
1a0c0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1a0d0 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20  *  char *zSQL = 
1a0e0 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
1a0f0 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62  "INSERT INTO tab
1a100 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27 29 22  le VALUES('%q')"
1a110 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71  , zText);.**  sq
1a120 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a  lite3_exec(db, z
1a130 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a  SQL, 0, 0, 0);.*
1a140 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  *  sqlite3_free(
1a150 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  zSQL);.** </pre>
1a160 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1a170 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 20  .** Because the 
1a180 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67  %q format string
1a190 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c   is used, the '\
1a1a0 27 27 20 63 68 61 72 61 63 74 65 72 20 69 6e 20  '' character in 
1a1b0 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61  zText.** is esca
1a1c0 70 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20  ped and the SQL 
1a1d0 67 65 6e 65 72 61 74 65 64 20 69 73 20 61 73 20  generated is as 
1a1e0 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
1a1f0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1a200 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f  .**  INSERT INTO
1a210 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27   table1 VALUES('
1a220 49 74 27 27 73 20 61 20 68 61 70 70 79 20 64 61  It''s a happy da
1a230 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  y!').** </pre></
1a240 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1a250 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72 65 63  * This is correc
1a260 74 2e 20 20 48 61 64 20 77 65 20 75 73 65 64 20  t.  Had we used 
1a270 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71  %s instead of %q
1a280 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 20  , the generated 
1a290 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76  SQL.** would hav
1a2a0 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68  e looked like th
1a2b0 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  is:.**.** <block
1a2c0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1a2d0 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
1a2e0 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 20  e1 VALUES('It's 
1a2f0 61 20 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a  a happy day!');.
1a300 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1a310 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  quote>.**.** Thi
1a320 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65  s second example
1a330 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61   is an SQL synta
1a340 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67  x error.  As a g
1a350 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20  eneral rule you 
1a360 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73  should.** always
1a370 20 75 73 65 20 25 71 20 69 6e 73 74 65 61 64 20   use %q instead 
1a380 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72  of %s when inser
1a390 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61  ting text into a
1a3a0 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e   string literal.
1a3b0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20  .**.** ^(The %Q 
1a3c0 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
1a3d0 65 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61  e %q except it a
1a3e0 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20  lso adds single 
1a3f0 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a  quotes around.**
1a400 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20   the outside of 
1a410 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67  the total string
1a420 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c  .  Additionally,
1a430 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
1a440 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75  r in the.** argu
1a450 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e  ment list is a N
1a460 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20  ULL pointer, %Q 
1a470 73 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20  substitutes the 
1a480 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74  text "NULL" (wit
1a490 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71  hout.** single q
1a4a0 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66  uotes).)^  So, f
1a4b0 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20  or example, one 
1a4c0 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a  could say:.**.**
1a4d0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1a4e0 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51  e>.**  char *zSQ
1a4f0 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  L = sqlite3_mpri
1a500 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f  ntf("INSERT INTO
1a510 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51   table VALUES(%Q
1a520 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20  )", zText);.**  
1a530 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c  sqlite3_exec(db,
1a540 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b   zSQL, 0, 0, 0);
1a550 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65  .**  sqlite3_fre
1a560 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72  e(zSQL);.** </pr
1a570 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1a580 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61  **.** The code a
1a590 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72  bove will render
1a5a0 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73   a correct SQL s
1a5b0 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20  tatement in the 
1a5c0 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65  zSQL.** variable
1a5d0 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65   even if the zTe
1a5e0 78 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 61  xt variable is a
1a5f0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
1a600 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22 20  *.** ^(The "%z" 
1a610 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
1a620 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73  n works like "%s
1a630 22 20 62 75 74 20 77 69 74 68 20 74 68 65 0a 2a  " but with the.*
1a640 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20  * addition that 
1a650 61 66 74 65 72 20 74 68 65 20 73 74 72 69 6e 67  after the string
1a660 20 68 61 73 20 62 65 65 6e 20 72 65 61 64 20 61   has been read a
1a670 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a  nd copied into.*
1a680 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73  * the result, [s
1a690 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69  qlite3_free()] i
1a6a0 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20  s called on the 
1a6b0 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a  input string.)^.
1a6c0 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  */.char *sqlite3
1a6d0 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63  _mprintf(const c
1a6e0 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20  har*,...);.char 
1a6f0 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74  *sqlite3_vmprint
1a700 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76  f(const char*, v
1a710 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73  a_list);.char *s
1a720 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1a730 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20  int,char*,const 
1a740 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 63 68 61  char*, ...);.cha
1a750 72 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70 72  r *sqlite3_vsnpr
1a760 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63  intf(int,char*,c
1a770 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c  onst char*, va_l
1a780 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ist);../*.** CAP
1a790 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
1a7a0 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74  location Subsyst
1a7b0 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  em.**.** The SQL
1a7c0 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 68  ite core uses th
1a7d0 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e  ese three routin
1a7e0 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  es for all of it
1a7f0 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61  s own.** interna
1a800 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
1a810 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65  ion needs. "Core
1a820 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75  " in the previou
1a830 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f  s sentence.** do
1a840 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f  es not include o
1a850 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20  perating-system 
1a860 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70  specific VFS imp
1a870 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68  lementation.  Th
1a880 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53  e.** Windows VFS
1a890 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c   uses native mal
1a8a0 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
1a8b0 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74   for some operat
1a8c0 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ions..**.** ^The
1a8d0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1a8e0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
1a8f0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
1a900 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d   block.** of mem
1a910 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62  ory at least N b
1a920 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20  ytes in length, 
1a930 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70  where N is the p
1a940 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66  arameter..** ^If
1a950 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1a960 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f  ) is unable to o
1a970 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74  btain sufficient
1a980 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c   free.** memory,
1a990 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55   it returns a NU
1a9a0 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66  LL pointer.  ^If
1a9b0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e   the parameter N
1a9c0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d   to.** sqlite3_m
1a9d0 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20  alloc() is zero 
1a9e0 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  or negative then
1a9f0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1aa00 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e  ) returns.** a N
1aa10 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
1aa20 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69  ** ^Calling sqli
1aa30 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20  te3_free() with 
1aa40 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f  a pointer previo
1aa50 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a  usly returned.**
1aa60 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   by sqlite3_mall
1aa70 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  oc() or sqlite3_
1aa80 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73  realloc() releas
1aa90 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73  es that memory s
1aaa0 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67  o.** that it mig
1aab0 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e  ht be reused.  ^
1aac0 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65  The sqlite3_free
1aad0 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a  () routine is.**
1aae0 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63   a no-op if is c
1aaf0 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c  alled with a NUL
1ab00 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73  L pointer.  Pass
1ab10 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ing a NULL point
1ab20 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  er.** to sqlite3
1ab30 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c  _free() is harml
1ab40 65 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e  ess.  After bein
1ab50 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a  g freed, memory.
1ab60 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65  ** should neithe
1ab70 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72  r be read nor wr
1ab80 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61  itten.  Even rea
1ab90 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20  ding previously 
1aba0 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20  freed.** memory 
1abb0 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20  might result in 
1abc0 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66  a segmentation f
1abd0 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65  ault or other se
1abe0 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d  vere error..** M
1abf0 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e  emory corruption
1ac00 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e  , a segmentation
1ac10 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72   fault, or other
1ac20 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a   severe error.**
1ac30 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66   might result if
1ac40 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
1ac50 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  is called with a
1ac60 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
1ac70 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f  r that.** was no
1ac80 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  t obtained from 
1ac90 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1aca0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   or sqlite3_real
1acb0 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  loc()..**.** ^(T
1acc0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  he sqlite3_reall
1acd0 6f 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 61  oc() interface a
1ace0 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a  ttempts to resiz
1acf0 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d  e a.** prior mem
1ad00 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
1ad10 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20  o be at least N 
1ad20 62 79 74 65 73 2c 20 77 68 65 72 65 20 4e 20 69  bytes, where N i
1ad30 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20  s the.** second 
1ad40 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20  parameter.  The 
1ad50 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1ad60 6e 20 74 6f 20 62 65 20 72 65 73 69 7a 65 64 20  n to be resized 
1ad70 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20  is the first.** 
1ad80 70 61 72 61 6d 65 74 65 72 2e 29 5e 20 5e 20 49  parameter.)^ ^ I
1ad90 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  f the first para
1ada0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
1adb0 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73  _realloc().** is
1adc0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
1add0 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f  then its behavio
1ade0 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74  r is identical t
1adf0 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c  o calling.** sql
1ae00 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77  ite3_malloc(N) w
1ae10 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65  here N is the se
1ae20 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
1ae30 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
1ae40 63 28 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  c()..** ^If the 
1ae50 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1ae60 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
1ae70 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72  loc() is zero or
1ae80 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65  .** negative the
1ae90 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
1aea0 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61  s exactly the sa
1aeb0 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a  me as calling.**
1aec0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29   sqlite3_free(P)
1aed0 20 77 68 65 72 65 20 50 20 69 73 20 74 68 65 20   where P is the 
1aee0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
1aef0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
1af00 6f 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65  oc()..** ^sqlite
1af10 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75  3_realloc() retu
1af20 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
1af30 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
1af40 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65  tion.** of at le
1af50 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73  ast N bytes in s
1af60 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73  ize or NULL if s
1af70 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79  ufficient memory
1af80 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e   is unavailable.
1af90 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65  .** ^If M is the
1afa0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69   size of the pri
1afb0 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74  or allocation, t
1afc0 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74  hen min(N,M) byt
1afd0 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69  es.** of the pri
1afe0 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72  or allocation ar
1aff0 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68  e copied into th
1b000 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62  e beginning of b
1b010 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a  uffer returned.*
1b020 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61  * by sqlite3_rea
1b030 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20 70  lloc() and the p
1b040 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
1b050 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66  is freed..** ^If
1b060 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1b070 28 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c  () returns NULL,
1b080 20 74 68 65 6e 20 74 68 65 20 70 72 69 6f 72 20   then the prior 
1b090 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73  allocation.** is
1b0a0 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a   not freed..**.*
1b0b0 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65  * ^The memory re
1b0c0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
1b0d0 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73  3_malloc() and s
1b0e0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1b0f0 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c  .** is always al
1b100 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73  igned to at leas
1b110 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e  t an 8 byte boun
1b120 64 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a  dary, or to a.**
1b130 20 34 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79   4 byte boundary
1b140 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   if the [SQLITE_
1b150 34 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d  4_BYTE_ALIGNED_M
1b160 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74  ALLOC] compile-t
1b170 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73  ime.** option is
1b180 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20   used..**.** In 
1b190 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
1b1a0 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20  .5.0 and 3.5.1, 
1b1b0 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20  it was possible 
1b1c0 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65  to define.** the
1b1d0 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d   SQLITE_OMIT_MEM
1b1e0 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77  ORY_ALLOCATION w
1b1f0 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65  hich would cause
1b200 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a   the built-in.**
1b210 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
1b220 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
1b230 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e  s to be omitted.
1b240 20 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74    That capabilit
1b250 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  y.** is no longe
1b260 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c  r provided.  Onl
1b270 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72  y built-in memor
1b280 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e  y allocators can
1b290 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   be used..**.** 
1b2a0 50 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20  Prior to SQLite 
1b2b0 76 65 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20  version 3.7.10, 
1b2c0 74 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69  the Windows OS i
1b2d0 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63  nterface layer c
1b2e0 61 6c 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73  alled.** the sys
1b2f0 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64  tem malloc() and
1b300 20 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79   free() directly
1b310 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67   when converting
1b320 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65  .** filenames be
1b330 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20  tween the UTF-8 
1b340 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79  encoding used by
1b350 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77   SQLite.** and w
1b360 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65  hatever filename
1b370 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65   encoding is use
1b380 64 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75  d by the particu
1b390 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69  lar Windows.** i
1b3a0 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65  nstallation.  Me
1b3b0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1b3c0 65 72 72 6f 72 73 20 77 65 72 65 20 64 65 74 65  errors were dete
1b3d0 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65  cted, but.** the
1b3e0 79 20 77 65 72 65 20 72 65 70 6f 72 74 65 64 20  y were reported 
1b3f0 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f  back as [SQLITE_
1b400 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20  CANTOPEN] or.** 
1b410 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72  [SQLITE_IOERR] r
1b420 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  ather than [SQLI
1b430 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a  TE_NOMEM]..**.**
1b440 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67   The pointer arg
1b450 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74  uments to [sqlit
1b460 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b  e3_free()] and [
1b470 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1b480 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69  )].** must be ei
1b490 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73  ther NULL or els
1b4a0 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69  e pointers obtai
1b4b0 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72  ned from a prior
1b4c0 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  .** invocation o
1b4d0 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  f [sqlite3_mallo
1b4e0 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  c()] or [sqlite3
1b4f0 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74  _realloc()] that
1b500 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74   have.** not yet
1b510 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a   been released..
1b520 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  **.** The applic
1b530 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72  ation must not r
1b540 65 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79  ead or write any
1b550 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c   part of.** a bl
1b560 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66  ock of memory af
1b570 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20  ter it has been 
1b580 72 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a  released using.*
1b590 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  * [sqlite3_free(
1b5a0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
1b5b0 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f  ealloc()]..*/.vo
1b5c0 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  id *sqlite3_mall
1b5d0 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73  oc(int);.void *s
1b5e0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76  qlite3_realloc(v
1b5f0 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  oid*, int);.void
1b600 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f   sqlite3_free(vo
1b610 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
1b620 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
1b630 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74 69  locator Statisti
1b640 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  cs.**.** SQLite 
1b650 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 74  provides these t
1b660 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f  wo interfaces fo
1b670 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74  r reporting on t
1b680 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20  he status.** of 
1b690 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  the [sqlite3_mal
1b6a0 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  loc()], [sqlite3
1b6b0 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73  _free()], and [s
1b6c0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1b6d0 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77  ].** routines, w
1b6e0 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75  hich form the bu
1b6f0 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
1b700 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74  location subsyst
1b710 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  em..**.** ^The [
1b720 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
1b730 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72  sed()] routine r
1b740 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
1b750 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66  r of bytes.** of
1b760 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c   memory currentl
1b770 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d  y outstanding (m
1b780 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20  alloced but not 
1b790 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20  freed)..** ^The 
1b7a0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1b7b0 68 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75  highwater()] rou
1b7c0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
1b7d0 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75   maximum.** valu
1b7e0 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65  e of [sqlite3_me
1b7f0 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69 6e  mory_used()] sin
1b800 63 65 20 74 68 65 20 68 69 67 68 2d 77 61 74 65  ce the high-wate
1b810 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61  r mark.** was la
1b820 73 74 20 72 65 73 65 74 2e 20 20 5e 54 68 65 20  st reset.  ^The 
1b830 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
1b840 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  by [sqlite3_memo
1b850 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a  ry_used()] and.*
1b860 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  * [sqlite3_memor
1b870 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69  y_highwater()] i
1b880 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68  nclude any overh
1b890 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 79 20  ead.** added by 
1b8a0 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d  SQLite in its im
1b8b0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
1b8c0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1b8d0 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f  )],.** but not o
1b8e0 76 65 72 68 65 61 64 20 61 64 64 65 64 20 62 79  verhead added by
1b8f0 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79   the any underly
1b900 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61  ing system libra
1b910 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74  ry.** routines t
1b920 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  hat [sqlite3_mal
1b930 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e  loc()] may call.
1b940 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f  .**.** ^The memo
1b950 72 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  ry high-water ma
1b960 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20 74  rk is reset to t
1b970 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65  he current value
1b980 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   of.** [sqlite3_
1b990 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69  memory_used()] i
1b9a0 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68  f and only if th
1b9b0 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  e parameter to.*
1b9c0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  * [sqlite3_memor
1b9d0 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69  y_highwater()] i
1b9e0 73 20 74 72 75 65 2e 20 20 5e 54 68 65 20 76 61  s true.  ^The va
1b9f0 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  lue returned.** 
1ba00 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  by [sqlite3_memo
1ba10 72 79 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d  ry_highwater(1)]
1ba20 20 69 73 20 74 68 65 20 68 69 67 68 2d 77 61 74   is the high-wat
1ba30 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72  er mark.** prior
1ba40 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a   to the reset..*
1ba50 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  /.sqlite3_int64 
1ba60 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
1ba70 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74  sed(void);.sqlit
1ba80 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
1ba90 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
1baa0 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29  r(int resetFlag)
1bab0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1bac0 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d  F: Pseudo-Random
1bad0 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f   Number Generato
1bae0 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63  r.**.** SQLite c
1baf0 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71  ontains a high-q
1bb00 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61  uality pseudo-ra
1bb10 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65  ndom number gene
1bb20 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65  rator (PRNG) use
1bb30 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72  d to.** select r
1bb40 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52  andom [ROWID | R
1bb50 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73 65  OWIDs] when inse
1bb60 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64  rting new record
1bb70 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74  s into a table t
1bb80 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75  hat.** already u
1bb90 73 65 73 20 74 68 65 20 6c 61 72 67 65 73 74 20  ses the largest 
1bba0 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d  possible [ROWID]
1bbb0 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73 20 61  .  The PRNG is a
1bbc0 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20  lso used for.** 
1bbd0 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e  the build-in ran
1bbe0 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d  dom() and random
1bbf0 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74  blob() SQL funct
1bc00 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65  ions.  This inte
1bc10 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20  rface allows.** 
1bc20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20  applications to 
1bc30 61 63 63 65 73 73 20 74 68 65 20 73 61 6d 65 20  access the same 
1bc40 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70  PRNG for other p
1bc50 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  urposes..**.** ^
1bc60 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72  A call to this r
1bc70 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20  outine stores N 
1bc80 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e  bytes of randomn
1bc90 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20  ess into buffer 
1bca0 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  P..**.** ^The fi
1bcb0 72 73 74 20 74 69 6d 65 20 74 68 69 73 20 72 6f  rst time this ro
1bcc0 75 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64  utine is invoked
1bcd0 20 28 65 69 74 68 65 72 20 69 6e 74 65 72 6e 61   (either interna
1bce0 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65  lly or by.** the
1bcf0 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 20 74 68   application) th
1bd00 65 20 50 52 4e 47 20 69 73 20 73 65 65 64 65 64  e PRNG is seeded
1bd10 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73   using randomnes
1bd20 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  s obtained.** fr
1bd30 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65  om the xRandomne
1bd40 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  ss method of the
1bd50 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
1bd60 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a  3_vfs] object..*
1bd70 2a 20 5e 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71  * ^On all subseq
1bd80 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73  uent invocations
1bd90 2c 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e  , the pseudo-ran
1bda0 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72  domness is gener
1bdb0 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c  ated.** internal
1bdc0 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72  ly and without r
1bdd0 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b  ecourse to the [
1bde0 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61  sqlite3_vfs] xRa
1bdf0 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68  ndomness.** meth
1be00 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  od..*/.void sqli
1be10 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69  te3_randomness(i
1be20 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a  nt N, void *P);.
1be30 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1be40 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75   Compile-Time Au
1be50 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c  thorization Call
1be60 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  backs.**.** ^Thi
1be70 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74  s routine regist
1be80 65 72 73 20 61 6e 20 61 75 74 68 6f 72 69 7a 65  ers an authorize
1be90 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20  r callback with 
1bea0 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
1beb0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1bec0 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20  tion], supplied 
1bed0 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
1bee0 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61  ument..** ^The a
1bef0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1bf00 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73  ck is invoked as
1bf10 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
1bf20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c  are being compil
1bf30 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65  ed.** by [sqlite
1bf40 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
1bf50 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71  its variants [sq
1bf60 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1bf70 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
1bf80 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e  _prepare16()] an
1bf90 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
1bfa0 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74  re16_v2()].  ^At
1bfb0 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e   various.** poin
1bfc0 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f  ts during the co
1bfd0 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73  mpilation proces
1bfe0 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62  s, as logic is b
1bff0 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20  eing created.** 
1c000 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
1c010 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20  us actions, the 
1c020 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1c030 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74  ack is invoked t
1c040 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73  o.** see if thos
1c050 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c  e actions are al
1c060 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74  lowed.  ^The aut
1c070 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1c080 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
1c090 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f  n [SQLITE_OK] to
1c0a0 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f   allow the actio
1c0b0 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  n, [SQLITE_IGNOR
1c0c0 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74  E] to disallow t
1c0d0 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61  he.** specific a
1c0e0 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20  ction but allow 
1c0f0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
1c100 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f  t to continue to
1c110 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c   be.** compiled,
1c120 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   or [SQLITE_DENY
1c130 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65  ] to cause the e
1c140 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d  ntire SQL statem
1c150 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a  ent to be.** rej
1c160 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72  ected with an er
1c170 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75  ror.  ^If the au
1c180 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1c190 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79  k returns.** any
1c1a0 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61   value other tha
1c1b0 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  n [SQLITE_IGNORE
1c1c0 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ], [SQLITE_OK], 
1c1d0 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  or [SQLITE_DENY]
1c1e0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71  .** then the [sq
1c1f0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1c200 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e  ()] or equivalen
1c210 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  t call that trig
1c220 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74  gered.** the aut
1c230 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69  horizer will fai
1c240 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  l with an error 
1c250 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57  message..**.** W
1c260 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
1c270 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
1c280 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73  _OK], that means
1c290 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a   the operation.*
1c2a0 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f  * requested is o
1c2b0 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61  k.  ^When the ca
1c2c0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
1c2d0 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68  SQLITE_DENY], th
1c2e0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  e.** [sqlite3_pr
1c2f0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65  epare_v2()] or e
1c300 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74  quivalent call t
1c310 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68  hat triggered th
1c320 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20  e.** authorizer 
1c330 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61  will fail with a
1c340 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  n error message 
1c350 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a  explaining that.
1c360 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 6e  ** access is den
1c370 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ied. .**.** ^The
1c380 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
1c390 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
1c3a0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  er callback is a
1c3b0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69   copy of the thi
1c3c0 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  rd.** parameter 
1c3d0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  to the sqlite3_s
1c3e0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20  et_authorizer() 
1c3f0 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20  interface. ^The 
1c400 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1c410 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  .** to the callb
1c420 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
1c430 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c  r [SQLITE_COPY |
1c440 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68   action code] th
1c450 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  at specifies.** 
1c460 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61  the particular a
1c470 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
1c480 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69  orized. ^The thi
1c490 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68  rd through sixth
1c4a0 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74   parameters.** t
1c4b0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61  o the callback a
1c4c0 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  re zero-terminat
1c4d0 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20  ed strings that 
1c4e0 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e  contain addition
1c4f0 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62  al.** details ab
1c500 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74  out the action t
1c510 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e  o be authorized.
1c520 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61  .**.** ^If the a
1c530 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53  ction code is [S
1c540 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61  QLITE_READ].** a
1c550 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  nd the callback 
1c560 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
1c570 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65  IGNORE] then the
1c580 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
1c590 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65  atement] stateme
1c5a0 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65  nt is constructe
1c5b0 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a  d to substitute.
1c5c0 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20  ** a NULL value 
1c5d0 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20  in place of the 
1c5e0 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61  table column tha
1c5f0 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20  t would have.** 
1c600 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51  been read if [SQ
1c610 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65  LITE_OK] had bee
1c620 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  n returned.  The
1c630 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
1c640 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62  .** return can b
1c650 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61  e used to deny a
1c660 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 72  n untrusted user
1c670 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76   access to indiv
1c680 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73  idual.** columns
1c690 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20   of a table..** 
1c6a0 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63  ^If the action c
1c6b0 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44  ode is [SQLITE_D
1c6c0 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63  ELETE] and the c
1c6d0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a  allback returns.
1c6e0 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ** [SQLITE_IGNOR
1c6f0 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c  E] then the [DEL
1c700 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70  ETE] operation p
1c710 72 6f 63 65 65 64 73 20 62 75 74 20 74 68 65 0a  roceeds but the.
1c720 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74  ** [truncate opt
1c730 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69  imization] is di
1c740 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72  sabled and all r
1c750 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20  ows are deleted 
1c760 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a  individually..**
1c770 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65  .** An authorize
1c780 72 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b  r is used when [
1c790 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20  sqlite3_prepare 
1c7a0 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20  | preparing].** 
1c7b0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66  SQL statements f
1c7c0 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64  rom an untrusted
1c7d0 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75   source, to ensu
1c7e0 72 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 20  re that the SQL 
1c7f0 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f  statements.** do
1c800 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65   not try to acce
1c810 73 73 20 64 61 74 61 20 74 68 65 79 20 61 72 65  ss data they are
1c820 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20   not allowed to 
1c830 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65  see, or that the
1c840 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20  y do not.** try 
1c850 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63  to execute malic
1c860 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20  ious statements 
1c870 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20  that damage the 
1c880 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a  database.  For.*
1c890 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70  * example, an ap
1c8a0 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c  plication may al
1c8b0 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e  low a user to en
1c8c0 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a  ter arbitrary.**
1c8d0 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72   SQL queries for
1c8e0 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61   evaluation by a
1c8f0 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20   database.  But 
1c900 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
1c910 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74  does.** not want
1c920 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20   the user to be 
1c930 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62  able to make arb
1c940 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74  itrary changes t
1c950 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  o the.** databas
1c960 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65  e.  An authorize
1c970 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20  r could then be 
1c980 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69  put in place whi
1c990 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65  le the.** user-e
1c9a0 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65  ntered SQL is be
1c9b0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
1c9c0 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d  pare | prepared]
1c9d0 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f   that.** disallo
1c9e0 77 73 20 65 76 65 72 79 74 68 69 6e 67 20 65 78  ws everything ex
1c9f0 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74  cept [SELECT] st
1ca00 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
1ca10 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
1ca20 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73  t need to proces
1ca30 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75  s SQL from untru
1ca40 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20  sted sources.** 
1ca50 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69  might also consi
1ca60 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73  der lowering res
1ca70 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69  ource limits usi
1ca80 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  ng [sqlite3_limi
1ca90 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69  t()].** and limi
1caa0 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 73 69  ting database si
1cab0 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61  ze using the [ma
1cac0 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50  x_page_count] [P
1cad0 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64  RAGMA].** in add
1cae0 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61  ition to using a
1caf0 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a  n authorizer..**
1cb00 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e  .** ^(Only a sin
1cb10 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  gle authorizer c
1cb20 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f  an be in place o
1cb30 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  n a database con
1cb40 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20  nection.** at a 
1cb50 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c  time.  Each call
1cb60 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f   to sqlite3_set_
1cb70 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72  authorizer overr
1cb80 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76  ides the.** prev
1cb90 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44  ious call.)^  ^D
1cba0 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f  isable the autho
1cbb0 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c  rizer by install
1cbc0 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62  ing a NULL callb
1cbd0 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68  ack..** The auth
1cbe0 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c  orizer is disabl
1cbf0 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ed by default..*
1cc00 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69  *.** The authori
1cc10 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73  zer callback mus
1cc20 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
1cc30 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
1cc40 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
1cc50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
1cc60 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61  at invoked the a
1cc70 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1cc80 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  ck..** Note that
1cc90 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1cca0 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
1ccb0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74  ite3_step()] bot
1ccc0 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a  h modify their.*
1ccd0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
1cce0 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d  ctions for the m
1ccf0 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66  eaning of "modif
1cd00 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67  y" in this parag
1cd10 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65  raph..**.** ^Whe
1cd20 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
1cd30 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64  re_v2()] is used
1cd40 20 74 6f 20 70 72 65 70 61 72 65 20 61 20 73 74   to prepare a st
1cd50 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20  atement, the.** 
1cd60 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20  statement might 
1cd70 62 65 20 72 65 2d 70 72 65 70 61 72 65 64 20 64  be re-prepared d
1cd80 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  uring [sqlite3_s
1cd90 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20  tep()] due to a 
1cda0 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67  .** schema chang
1cdb0 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61  e.  Hence, the a
1cdc0 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
1cdd0 64 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  d ensure that th
1cde0 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74  e.** correct aut
1cdf0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1ce00 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63   remains in plac
1ce10 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71  e during the [sq
1ce20 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
1ce30 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20  *.** ^Note that 
1ce40 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1ce50 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
1ce60 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a  ed only during.*
1ce70 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
1ce80 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  re()] or its var
1ce90 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a  iants.  Authoriz
1cea0 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20  ation is not.** 
1ceb0 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67  performed during
1cec0 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75   statement evalu
1ced0 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65  ation in [sqlite
1cee0 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73  3_step()], unles
1cef0 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69  s.** as stated i
1cf00 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70  n the previous p
1cf10 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65  aragraph, sqlite
1cf20 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73  3_step() invokes
1cf30 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70  .** sqlite3_prep
1cf40 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72  are_v2() to repr
1cf50 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e  epare a statemen
1cf60 74 20 61 66 74 65 72 20 61 20 73 63 68 65 6d 61  t after a schema
1cf70 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20   change..*/.int 
1cf80 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1cf90 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65  orizer(.  sqlite
1cfa0 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74  3*,.  int (*xAut
1cfb0 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  h)(void*,int,con
1cfc0 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
1cfd0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
1cfe0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20  ,const char*),. 
1cff0 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61   void *pUserData
1d000 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
1d010 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20  REF: Authorizer 
1d020 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a  Return Codes.**.
1d030 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
1d040 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
1d050 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1d060 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d  back function] m
1d070 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69  ust.** return ei
1d080 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  ther [SQLITE_OK]
1d090 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65   or one of these
1d0a0 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69   two constants i
1d0b0 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69  n order.** to si
1d0c0 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74  gnal SQLite whet
1d0d0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61  her or not the a
1d0e0 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74  ction is permitt
1d0f0 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20  ed.  See the.** 
1d100 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
1d110 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
1d120 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69  izer documentati
1d130 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  on] for addition
1d140 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
1d150 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  n..**.** Note th
1d160 61 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  at SQLITE_IGNORE
1d170 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73   is also used as
1d180 20 61 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42   a [SQLITE_ROLLB
1d190 41 43 4b 20 7c 20 72 65 74 75 72 6e 20 63 6f 64  ACK | return cod
1d1a0 65 5d 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 5b  e].** from the [
1d1b0 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f  sqlite3_vtab_on_
1d1c0 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74 65  conflict()] inte
1d1d0 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  rface..*/.#defin
1d1e0 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20  e SQLITE_DENY   
1d1f0 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65  1   /* Abort the
1d200 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77   SQL statement w
1d210 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a  ith an error */.
1d220 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
1d230 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e  GNORE 2   /* Don
1d240 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c  't allow access,
1d250 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72   but don't gener
1d260 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a  ate an error */.
1d270 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1d280 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69   Authorizer Acti
1d290 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54  on Codes.**.** T
1d2a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
1d2b0 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e  authorizer()] in
1d2c0 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
1d2d0 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
1d2e0 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73  ction.** that is
1d2f0 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68   invoked to auth
1d300 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53 51  orize certain SQ
1d310 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69  L statement acti
1d320 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63  ons.  The.** sec
1d330 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
1d340 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
1d350 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65   an integer code
1d360 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a   that specifies.
1d370 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69  ** what action i
1d380 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a  s being authoriz
1d390 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 20 74  ed.  These are t
1d3a0 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f  he integer actio
1d3b0 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20  n codes that.** 
1d3c0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1d3d0 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70  allback may be p
1d3e0 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  assed..**.** The
1d3f0 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76  se action code v
1d400 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77 68  alues signify wh
1d410 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61  at kind of opera
1d420 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a  tion is to be.**
1d430 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68   authorized.  Th
1d440 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70 61  e 3rd and 4th pa
1d450 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20  rameters to the 
1d460 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a  authorization.**
1d470 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1d480 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d  on will be param
1d490 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65  eters or NULL de
1d4a0 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68  pending on which
1d4b0 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64   of these.** cod
1d4c0 65 73 20 69 73 20 75 73 65 64 20 61 73 20 74 68  es is used as th
1d4d0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
1d4e0 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68 20 70  er.  ^(The 5th p
1d4f0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a  arameter to the.
1d500 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  ** authorizer ca
1d510 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61  llback is the na
1d520 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
1d530 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d  se ("main", "tem
1d540 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20  p",.** etc.) if 
1d550 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e  applicable.)^  ^
1d560 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 74 65  The 6th paramete
1d570 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  r to the authori
1d580 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  zer callback.** 
1d590 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
1d5a0 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72  he inner-most tr
1d5b0 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 74 68  igger or view th
1d5c0 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  at is responsibl
1d5d0 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63  e for.** the acc
1d5e0 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e  ess attempt or N
1d5f0 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 65  ULL if this acce
1d600 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 69  ss attempt is di
1d610 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74  rectly from.** t
1d620 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64  op-level SQL cod
1d630 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a  e..*/./*********
1d640 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1d650 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1d660 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  ** 3rd *********
1d670 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a  *** 4th ********
1d680 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ***/.#define SQL
1d690 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58  ITE_CREATE_INDEX
1d6a0 20 20 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a            1   /*
1d6b0 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
1d6c0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1d6d0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1d6e0 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20  TE_CREATE_TABLE 
1d6f0 20 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20           2   /* 
1d700 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1d710 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1d720 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1d730 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e  E_CREATE_TEMP_IN
1d740 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49  DEX     3   /* I
1d750 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
1d760 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1d770 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1d780 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42  _CREATE_TEMP_TAB
1d790 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61  LE     4   /* Ta
1d7a0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
1d7b0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1d7c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1d7d0 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47  CREATE_TEMP_TRIG
1d7e0 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69  GER   5   /* Tri
1d7f0 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
1d800 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1d810 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1d820 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20  REATE_TEMP_VIEW 
1d830 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77       6   /* View
1d840 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
1d850 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1d860 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1d870 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 20 20  EATE_TRIGGER    
1d880 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67      7   /* Trigg
1d890 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
1d8a0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1d8b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1d8c0 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 20 20  ATE_VIEW        
1d8d0 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e     8   /* View N
1d8e0 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
1d8f0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1d900 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45  fine SQLITE_DELE
1d910 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
1d920 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    9   /* Table N
1d930 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1d940 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1d950 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1d960 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20  INDEX           
1d970 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  10   /* Index Na
1d980 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
1d990 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1d9a0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
1d9b0 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 31  ABLE           1
1d9c0 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  1   /* Table Nam
1d9d0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1d9e0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1d9f0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
1da00 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32  MP_INDEX      12
1da10 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
1da20 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
1da30 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1da40 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
1da50 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33 20  P_TABLE      13 
1da60 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1da70 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1da80 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1da90 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
1daa0 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 20 20  _TRIGGER    14  
1dab0 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
1dac0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1dad0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1dae0 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
1daf0 56 49 45 57 20 20 20 20 20 20 20 31 35 20 20 20  VIEW       15   
1db00 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
1db10 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1db20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1db30 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45  LITE_DROP_TRIGGE
1db40 52 20 20 20 20 20 20 20 20 20 31 36 20 20 20 2f  R         16   /
1db50 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
1db60 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1db70 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1db80 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20  ITE_DROP_VIEW   
1db90 20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a           17   /*
1dba0 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
1dbb0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1dbc0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1dbd0 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20  TE_INSERT       
1dbe0 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20          18   /* 
1dbf0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1dc00 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1dc10 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1dc20 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20  E_PRAGMA        
1dc30 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50         19   /* P
1dc40 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31  ragma Name     1
1dc50 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a  st arg or NULL *
1dc60 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1dc70 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20  _READ           
1dc80 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61        20   /* Ta
1dc90 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f  ble Name      Co
1dca0 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f  lumn Name     */
1dcb0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1dcc0 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20  SELECT          
1dcd0 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c       21   /* NUL
1dce0 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c  L            NUL
1dcf0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1dd00 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
1dd10 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20  RANSACTION      
1dd20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 72      22   /* Oper
1dd30 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c  ation       NULL
1dd40 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1dd50 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50  define SQLITE_UP
1dd60 44 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20  DATE            
1dd70 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65     23   /* Table
1dd80 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d   Name      Colum
1dd90 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  n Name     */.#d
1dda0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54  efine SQLITE_ATT
1ddb0 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20  ACH             
1ddc0 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61    24   /* Filena
1ddd0 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  me        NULL  
1dde0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1ddf0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41  fine SQLITE_DETA
1de00 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CH              
1de10 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73   25   /* Databas
1de20 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20  e Name   NULL   
1de30 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1de40 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52  ine SQLITE_ALTER
1de50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
1de60 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  26   /* Database
1de70 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61   Name   Table Na
1de80 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1de90 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45  ne SQLITE_REINDE
1dea0 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  X              2
1deb0 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  7   /* Index Nam
1dec0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1ded0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1dee0 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45  e SQLITE_ANALYZE
1def0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 38                28
1df00 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1df10 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1df20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1df30 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56   SQLITE_CREATE_V
1df40 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 39 20  TABLE        29 
1df50 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1df60 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65       Module Name
1df70 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1df80 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42  SQLITE_DROP_VTAB
1df90 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 20 20  LE          30  
1dfa0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1dfb0 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20      Module Name 
1dfc0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1dfd0 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20  QLITE_FUNCTION  
1dfe0 20 20 20 20 20 20 20 20 20 20 20 33 31 20 20 20             31   
1dff0 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
1e000 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65     Function Name
1e010 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1e020 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 20  LITE_SAVEPOINT  
1e030 20 20 20 20 20 20 20 20 20 20 33 32 20 20 20 2f            32   /
1e040 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20  * Operation     
1e050 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65    Savepoint Name
1e060 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1e070 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20  ITE_COPY        
1e080 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a            0   /*
1e090 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20   No longer used 
1e0a0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
1e0b0 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20  EF: Tracing And 
1e0c0 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69  Profiling Functi
1e0d0 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
1e0e0 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65  routines registe
1e0f0 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  r callback funct
1e100 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65  ions that can be
1e110 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61   used for.** tra
1e120 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69  cing and profili
1e130 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e  ng the execution
1e140 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   of SQL statemen
1e150 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63  ts..**.** ^The c
1e160 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1e170 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73   registered by s
1e180 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 69  qlite3_trace() i
1e190 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20  s invoked at.** 
1e1a0 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68  various times wh
1e1b0 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  en an SQL statem
1e1c0 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e  ent is being run
1e1d0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   by [sqlite3_ste
1e1e0 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  p()]..** ^The sq
1e1f0 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61  lite3_trace() ca
1e200 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
1e210 64 20 77 69 74 68 20 61 20 55 54 46 2d 38 20 72  d with a UTF-8 r
1e220 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a  endering of the.
1e230 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
1e240 20 74 65 78 74 20 61 73 20 74 68 65 20 73 74 61   text as the sta
1e250 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67  tement first beg
1e260 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a  ins executing..*
1e270 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73  * ^(Additional s
1e280 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63  qlite3_trace() c
1e290 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f  allbacks might o
1e2a0 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20  ccur.** as each 
1e2b0 74 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f  triggered subpro
1e2c0 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e  gram is entered.
1e2d0 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20    The callbacks 
1e2e0 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20  for triggers.** 
1e2f0 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20  contain a UTF-8 
1e300 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74  SQL comment that
1e310 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20   identifies the 
1e320 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a  trigger.)^.**.**
1e330 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66   ^The callback f
1e340 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
1e350 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72  ed by sqlite3_pr
1e360 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b  ofile() is invok
1e370 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51  ed.** as each SQ
1e380 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69  L statement fini
1e390 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66  shes.  ^The prof
1e3a0 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e  ile callback con
1e3b0 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69  tains.** the ori
1e3c0 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20  ginal statement 
1e3d0 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69  text and an esti
1e3e0 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f  mate of wall-clo
1e3f0 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f  ck time.** of ho
1e400 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74  w long that stat
1e410 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75  ement took to ru
1e420 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65  n.  ^The profile
1e430 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d   callback.** tim
1e440 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66  e is in units of
1e450 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f   nanoseconds, ho
1e460 77 65 76 65 72 20 74 68 65 20 63 75 72 72 65 6e  wever the curren
1e470 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  t implementation
1e480 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61  .** is only capa
1e490 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ble of milliseco
1e4a0 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f  nd resolution so
1e4b0 20 74 68 65 20 73 69 78 20 6c 65 61 73 74 20 73   the six least s
1e4c0 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69  ignificant.** di
1e4d0 67 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65  gits in the time
1e4e0 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73   are meaningless
1e4f0 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
1e500 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  ns of SQLite.** 
1e510 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20 67 72  might provide gr
1e520 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e  eater resolution
1e530 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72   on the profiler
1e540 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a   callback.  The.
1e550 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  ** sqlite3_profi
1e560 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  le() function is
1e570 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65   considered expe
1e580 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a  rimental and is.
1e590 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  ** subject to ch
1e5a0 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 76  ange in future v
1e5b0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
1e5c0 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  e..*/.void *sqli
1e5d0 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65  te3_trace(sqlite
1e5e0 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65  3*, void(*xTrace
1e5f0 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
1e600 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51  ar*), void*);.SQ
1e610 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41  LITE_EXPERIMENTA
1e620 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  L void *sqlite3_
1e630 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a  profile(sqlite3*
1e640 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66  ,.   void(*xProf
1e650 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74  ile)(void*,const
1e660 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75   char*,sqlite3_u
1e670 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a  int64), void*);.
1e680 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1e690 20 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20   Query Progress 
1e6a0 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20  Callbacks.**.** 
1e6b0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f  ^The sqlite3_pro
1e6c0 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c  gress_handler(D,
1e6d0 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65  N,X,P) interface
1e6e0 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c   causes the call
1e6f0 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  back.** function
1e700 20 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64   X to be invoked
1e710 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75   periodically du
1e720 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e  ring long runnin
1e730 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73  g calls to.** [s
1e740 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20  qlite3_exec()], 
1e750 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1e760 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65   and [sqlite3_ge
1e770 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a  t_table()] for.*
1e780 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
1e790 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61  ction D.  An exa
1e7a0 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69  mple use for thi
1e7b0 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  s.** interface i
1e7c0 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20  s to keep a GUI 
1e7d0 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61  updated during a
1e7e0 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a   large query..**
1e7f0 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74  .** ^The paramet
1e800 65 72 20 50 20 69 73 20 70 61 73 73 65 64 20 74  er P is passed t
1e810 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e  hrough as the on
1e820 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ly parameter to 
1e830 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  the .** callback
1e840 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54   function X.  ^T
1e850 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69  he parameter N i
1e860 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
1e870 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 63  .** [virtual mac
1e880 68 69 6e 65 20 69 6e 73 74 72 75 63 74 69 6f 6e  hine instruction
1e890 73 5d 20 74 68 61 74 20 61 72 65 20 65 76 61 6c  s] that are eval
1e8a0 75 61 74 65 64 20 62 65 74 77 65 65 6e 20 73 75  uated between su
1e8b0 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f  ccessive.** invo
1e8c0 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 63  cations of the c
1e8d0 61 6c 6c 62 61 63 6b 20 58 2e 0a 2a 2a 0a 2a 2a  allback X..**.**
1e8e0 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20   ^Only a single 
1e8f0 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
1e900 20 6d 61 79 20 62 65 20 64 65 66 69 6e 65 64 20   may be defined 
1e910 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a  at one time per.
1e920 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
1e930 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e  nection]; settin
1e940 67 20 61 20 6e 65 77 20 70 72 6f 67 72 65 73 73  g a new progress
1e950 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73   handler cancels
1e960 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e   the.** old one.
1e970 20 20 5e 53 65 74 74 69 6e 67 20 70 61 72 61 6d    ^Setting param
1e980 65 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64  eter X to NULL d
1e990 69 73 61 62 6c 65 73 20 74 68 65 20 70 72 6f 67  isables the prog
1e9a0 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  ress handler..**
1e9b0 20 5e 54 68 65 20 70 72 6f 67 72 65 73 73 20 68   ^The progress h
1e9c0 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 64  andler is also d
1e9d0 69 73 61 62 6c 65 64 20 62 79 20 73 65 74 74 69  isabled by setti
1e9e0 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 20  ng N to a value 
1e9f0 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a  less.** than 1..
1ea00 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72  **.** ^If the pr
1ea10 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20  ogress callback 
1ea20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
1ea30 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20  , the operation 
1ea40 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65  is.** interrupte
1ea50 64 2e 20 20 54 68 69 73 20 66 65 61 74 75 72 65  d.  This feature
1ea60 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
1ea70 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22  implement a.** "
1ea80 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f  Cancel" button o
1ea90 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65 73 73  n a GUI progress
1eaa0 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a   dialog box..**.
1eab0 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73 20  ** The progress 
1eac0 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
1ead0 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
1eae0 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
1eaf0 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
1eb00 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1eb10 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
1eb20 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
1eb30 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ler..** Note tha
1eb40 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  t [sqlite3_prepa
1eb50 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
1eb60 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f  lite3_step()] bo
1eb70 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a  th modify their.
1eb80 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
1eb90 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20  ections for the 
1eba0 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69  meaning of "modi
1ebb0 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61  fy" in this para
1ebc0 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69  graph..**.*/.voi
1ebd0 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65  d sqlite3_progre
1ebe0 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74  ss_handler(sqlit
1ebf0 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29  e3*, int, int(*)
1ec00 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b  (void*), void*);
1ec10 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1ec20 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20  : Opening A New 
1ec30 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
1ec40 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ion.**.** ^These
1ec50 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61   routines open a
1ec60 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73  n SQLite databas
1ec70 65 20 66 69 6c 65 20 61 73 20 73 70 65 63 69 66  e file as specif
1ec80 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66  ied by the .** f
1ec90 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
1eca0 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20  . ^The filename 
1ecb0 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65  argument is inte
1ecc0 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38  rpreted as UTF-8
1ecd0 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
1ece0 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
1ecf0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64  e3_open_v2() and
1ed00 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68   as UTF-16 in th
1ed10 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a  e native byte.**
1ed20 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74   order for sqlit
1ed30 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41  e3_open16(). ^(A
1ed40 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1ed50 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73  ction] handle is
1ed60 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75   usually.** retu
1ed70 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65  rned in *ppDb, e
1ed80 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20  ven if an error 
1ed90 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c  occurs.  The onl
1eda0 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74  y exception is t
1edb0 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65  hat.** if SQLite
1edc0 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
1edd0 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f  locate memory to
1ede0 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74   hold the [sqlit
1edf0 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61  e3] object,.** a
1ee00 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72   NULL will be wr
1ee10 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62  itten into *ppDb
1ee20 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f   instead of a po
1ee30 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  inter to the [sq
1ee40 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74  lite3].** object
1ee50 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74  .)^ ^(If the dat
1ee60 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
1ee70 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29  (and/or created)
1ee80 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74   successfully, t
1ee90 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  hen.** [SQLITE_O
1eea0 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  K] is returned. 
1eeb0 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65   Otherwise an [e
1eec0 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
1eed0 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a  turned.)^ ^The.*
1eee0 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  * [sqlite3_errms
1eef0 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  g()] or [sqlite3
1ef00 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75  _errmsg16()] rou
1ef10 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65  tines can be use
1ef20 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61  d to obtain.** a
1ef30 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61  n English langua
1ef40 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f  ge description o
1ef50 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c  f the error foll
1ef60 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20  owing a failure 
1ef70 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65  of any.** of the
1ef80 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
1ef90 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
1efa0 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63  ^The default enc
1efb0 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64 61  oding for the da
1efc0 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 55  tabase will be U
1efd0 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74  TF-8 if.** sqlit
1efe0 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
1eff0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
1f000 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20  s called and.** 
1f010 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61  UTF-16 in the na
1f020 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
1f030 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  if sqlite3_open1
1f040 36 28 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  6() is used..**.
1f050 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f  ** Whether or no
1f060 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  t an error occur
1f070 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65  s when it is ope
1f080 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a  ned, resources.*
1f090 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
1f0a0 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
1f0b0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
1f0c0 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c  le should be rel
1f0d0 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73  eased by.** pass
1f0e0 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74  ing it to [sqlit
1f0f0 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e  e3_close()] when
1f100 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72   it is no longer
1f110 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
1f120 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65   The sqlite3_ope
1f130 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  n_v2() interface
1f140 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69   works like sqli
1f150 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78  te3_open().** ex
1f160 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63  cept that it acc
1f170 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f  epts two additio
1f180 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66  nal parameters f
1f190 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f  or additional co
1f1a0 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68  ntrol.** over th
1f1b0 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  e new database c
1f1c0 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68  onnection.  ^(Th
1f1d0 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  e flags paramete
1f1e0 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  r to.** sqlite3_
1f1f0 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61  open_v2() can ta
1f200 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65  ke one of.** the
1f210 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65   following three
1f220 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61   values, optiona
1f230 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74  lly combined wit
1f240 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54  h the .** [SQLIT
1f250 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c  E_OPEN_NOMUTEX],
1f260 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55   [SQLITE_OPEN_FU
1f270 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54  LLMUTEX], [SQLIT
1f280 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
1f290 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  HE],.** [SQLITE_
1f2a0 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
1f2b0 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49  E], and/or [SQLI
1f2c0 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61  TE_OPEN_URI] fla
1f2d0 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  gs:)^.**.** <dl>
1f2e0 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54  .** ^(<dt>[SQLIT
1f2f0 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
1f300 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1f310 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
1f320 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79  ned in read-only
1f330 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64   mode.  If the d
1f340 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74  atabase does not
1f350 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73  .** already exis
1f360 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72  t, an error is r
1f370 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a  eturned.</dd>)^.
1f380 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  **.** ^(<dt>[SQL
1f390 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
1f3a0 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TE]</dt>.** <dd>
1f3b0 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
1f3c0 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69  opened for readi
1f3d0 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69  ng and writing i
1f3e0 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72  f possible, or r
1f3f0 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69  eading.** only i
1f400 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72  f the file is wr
1f410 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79  ite protected by
1f420 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
1f430 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65  ystem.  In eithe
1f440 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61  r.** case the da
1f450 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65  tabase must alre
1f460 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72  ady exist, other
1f470 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73  wise an error is
1f480 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29   returned.</dd>)
1f490 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  ^.**.** ^(<dt>[S
1f4a0 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
1f4b0 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f  RITE] | [SQLITE_
1f4c0 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74  OPEN_CREATE]</dt
1f4d0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
1f4e0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
1f4f0 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
1f500 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20  writing, and is 
1f510 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74  created if.** it
1f520 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64   does not alread
1f530 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73  y exist. This is
1f540 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68   the behavior th
1f550 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65  at is always use
1f560 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  d for.** sqlite3
1f570 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
1f580 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64  te3_open16().</d
1f590 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a  d>)^.** </dl>.**
1f5a0 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70  .** If the 3rd p
1f5b0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1f5c0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
1f5d0 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a   not one of the.
1f5e0 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20  ** combinations 
1f5f0 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69  shown above opti
1f600 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20  onally combined 
1f610 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53  with other.** [S
1f620 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
1f630 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45  NLY | SQLITE_OPE
1f640 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65  N_* bits].** the
1f650 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
1f660 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
1f670 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49  ** ^If the [SQLI
1f680 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d  TE_OPEN_NOMUTEX]
1f690 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68   flag is set, th
1f6a0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
1f6b0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70  connection.** op
1f6c0 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69  ens in the multi
1f6d0 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69  -thread [threadi
1f6e0 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67  ng mode] as long
1f6f0 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74   as the single-t
1f700 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61  hread.** mode ha
1f710 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61  s not been set a
1f720 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  t compile-time o
1f730 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e  r start-time.  ^
1f740 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  If the.** [SQLIT
1f750 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
1f760 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 68  ] flag is set th
1f770 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
1f780 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73  connection opens
1f790 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61  .** in the seria
1f7a0 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
1f7b0 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69   mode] unless si
1f7c0 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a  ngle-thread was.
1f7d0 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65  ** previously se
1f7e0 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c  lected at compil
1f7f0 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d  e-time or start-
1f800 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53  time..** ^The [S
1f810 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
1f820 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75  DCACHE] flag cau
1f830 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ses the database
1f840 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62   connection to b
1f850 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f  e.** eligible to
1f860 20 75 73 65 20 5b 73 68 61 72 65 64 20 63 61 63   use [shared cac
1f870 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64  he mode], regard
1f880 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
1f890 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a  or not shared.**
1f8a0 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65   cache is enable
1f8b0 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
1f8c0 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63  _enable_shared_c
1f8d0 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a  ache()].  ^The.*
1f8e0 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  * [SQLITE_OPEN_P
1f8f0 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61  RIVATECACHE] fla
1f900 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74  g causes the dat
1f910 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1f920 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69   to not.** parti
1f930 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65  cipate in [share
1f940 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76  d cache mode] ev
1f950 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61 62  en if it is enab
1f960 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  led..**.** ^The 
1f970 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
1f980 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
1f990 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d  _v2() is the nam
1f9a0 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  e of the.** [sql
1f9b0 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
1f9c0 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68   that defines th
1f9d0 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
1f9e0 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  em interface tha
1f9f0 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74  t.** the new dat
1fa00 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1fa10 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49   should use.  ^I
1fa20 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
1fa30 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e  ameter is.** a N
1fa40 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
1fa50 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
1fa60 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
1fa70 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  t is used..**.**
1fa80 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d   ^If the filenam
1fa90 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c  e is ":memory:",
1faa0 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c   then a private,
1fab0 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65   temporary in-me
1fac0 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a  mory database.**
1fad0 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20   is created for 
1fae0 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  the connection. 
1faf0 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79   ^This in-memory
1fb00 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76   database will v
1fb10 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68  anish when.** th
1fb20 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1fb30 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e  ction is closed.
1fb40 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
1fb50 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68  s of SQLite migh
1fb60 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66  t.** make use of
1fb70 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63   additional spec
1fb80 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68  ial filenames th
1fb90 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68  at begin with th
1fba0 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e  e ":" character.
1fbb0 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d  .** It is recomm
1fbc0 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e 20  ended that when 
1fbd0 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e  a database filen
1fbe0 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65  ame actually doe
1fbf0 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20  s begin with.** 
1fc00 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 20  a ":" character 
1fc10 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69  you should prefi
1fc20 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77  x the filename w
1fc30 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73  ith a pathname s
1fc40 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74  uch as.** "./" t
1fc50 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74  o avoid ambiguit
1fc60 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  y..**.** ^If the
1fc70 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20   filename is an 
1fc80 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68  empty string, th
1fc90 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65  en a private, te
1fca0 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69  mporary.** on-di
1fcb0 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  sk database will
1fcc0 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54   be created.  ^T
1fcd0 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61  his private data
1fce0 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20  base will be.** 
1fcf0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65  automatically de
1fd00 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73  leted as soon as
1fd10 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1fd20 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
1fd30 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20  ed..**.** [[URI 
1fd40 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c  filenames in sql
1fd50 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68  ite3_open()]] <h
1fd60 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c  3>URI Filenames<
1fd70 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b  /h3>.**.** ^If [
1fd80 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e  URI filename] in
1fd90 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20  terpretation is 
1fda0 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65  enabled, and the
1fdb0 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
1fdc0 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74  nt.** begins wit
1fdd0 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20  h "file:", then 
1fde0 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
1fdf0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
1fe00 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69   URI. ^URI.** fi
1fe10 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74  lename interpret
1fe20 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ation is enabled
1fe30 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   if the [SQLITE_
1fe40 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69  OPEN_URI] flag i
1fe50 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20  s.** set in the 
1fe60 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20  fourth argument 
1fe70 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
1fe80 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68  v2(), or if it h
1fe90 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c  as.** been enabl
1fea0 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e  ed globally usin
1feb0 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f  g the [SQLITE_CO
1fec0 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e  NFIG_URI] option
1fed0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71   with the.** [sq
1fee0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
1fef0 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65  method or by the
1ff00 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49   [SQLITE_USE_URI
1ff10 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
1ff20 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20  ption..** As of 
1ff30 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
1ff40 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e 61  .7.7, URI filena
1ff50 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  me interpretatio
1ff60 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66 0a  n is turned off.
1ff70 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20 62  ** by default, b
1ff80 75 74 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  ut future releas
1ff90 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  es of SQLite mig
1ffa0 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66 69  ht enable URI fi
1ffb0 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70  lename.** interp
1ffc0 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66 61  retation by defa
1ffd0 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49 20  ult.  See "[URI 
1ffe0 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20  filenames]" for 
1fff0 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e  additional.** in
20000 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
20010 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 61   URI filenames a
20020 72 65 20 70 61 72 73 65 64 20 61 63 63 6f 72 64  re parsed accord
20030 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36 2e  ing to RFC 3986.
20040 20 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f 6e   ^If the URI con
20050 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68  tains an.** auth
20060 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20 6d  ority, then it m
20070 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 6e  ust be either an
20080 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72   empty string or
20090 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20   the string .** 
200a0 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66  "localhost". ^If
200b0 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 69   the authority i
200c0 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20 73  s not an empty s
200d0 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68  tring or "localh
200e0 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72  ost", an .** err
200f0 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 74  or is returned t
20100 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54  o the caller. ^T
20110 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70  he fragment comp
20120 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c 20  onent of a URI, 
20130 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20  if .** present, 
20140 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a  is ignored..**.*
20150 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74  * ^SQLite uses t
20160 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e  he path componen
20170 74 20 6f 66 20 74 68 65 20 55 52 49 20 61 73 20  t of the URI as 
20180 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
20190 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69  disk file.** whi
201a0 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20  ch contains the 
201b0 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74 68  database. ^If th
201c0 65 20 70 61 74 68 20 62 65 67 69 6e 73 20 77 69  e path begins wi
201d0 74 68 20 61 20 27 2f 27 20 63 68 61 72 61 63 74  th a '/' charact
201e0 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20  er, .** then it 
201f0 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
20200 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61  s an absolute pa
20210 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68  th. ^If the path
20220 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e 20   does not begin 
20230 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20 28  .** with a '/' (
20240 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68 65  meaning that the
20250 20 61 75 74 68 6f 72 69 74 79 20 73 65 63 74 69   authority secti
20260 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  on is omitted fr
20270 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20 74  om the URI).** t
20280 68 65 6e 20 74 68 65 20 70 61 74 68 20 69 73 20  hen the path is 
20290 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
202a0 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e 20   relative path. 
202b0 0a 2a 2a 20 5e 4f 6e 20 77 69 6e 64 6f 77 73 2c  .** ^On windows,
202c0 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70 6f   the first compo
202d0 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c  nent of an absol
202e0 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 20  ute path .** is 
202f0 61 20 64 72 69 76 65 20 73 70 65 63 69 66 69 63  a drive specific
20300 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22  ation (e.g. "C:"
20310 29 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20  )..**.** [[core 
20320 55 52 49 20 71 75 65 72 79 20 70 61 72 61 6d 65  URI query parame
20330 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75  ters]].** The qu
20340 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ery component of
20350 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 61   a URI may conta
20360 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 68  in parameters th
20370 61 74 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  at are interpret
20380 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 20  ed.** either by 
20390 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 6f  SQLite itself, o
203a0 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20 63 75  r by a [VFS | cu
203b0 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65  stom VFS impleme
203c0 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c  ntation]..** SQL
203d0 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20 74  ite interprets t
203e0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72  he following thr
203f0 65 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  ee query paramet
20400 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ers:.**.** <ul>.
20410 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73  **   <li> <b>vfs
20420 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66 73 22  </b>: ^The "vfs"
20430 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
20440 65 20 75 73 65 64 20 74 6f 20 73 70 65 63 69 66  e used to specif
20450 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a  y the name of.**
20460 20 20 20 20 20 61 20 56 46 53 20 6f 62 6a 65 63       a VFS objec
20470 74 20 74 68 61 74 20 70 72 6f 76 69 64 65 73 20  t that provides 
20480 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
20490 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74  stem interface t
204a0 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20  hat should.**   
204b0 20 20 62 65 20 75 73 65 64 20 74 6f 20 61 63 63    be used to acc
204c0 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ess the database
204d0 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e   file on disk. ^
204e0 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69  If this option i
204f0 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20  s set to.**     
20500 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20  an empty string 
20510 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20  the default VFS 
20520 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 20  object is used. 
20530 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75  ^Specifying an u
20540 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46  nknown.**     VF
20550 53 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e  S is an error. ^
20560 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  If sqlite3_open_
20570 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64  v2() is used and
20580 20 74 68 65 20 76 66 73 20 6f 70 74 69 6f 6e 20   the vfs option 
20590 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 73 65 6e  is.**     presen
205a0 74 2c 20 74 68 65 6e 20 74 68 65 20 56 46 53 20  t, then the VFS 
205b0 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
205c0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 70 72   option takes pr
205d0 65 63 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a  ecedence over.**
205e0 20 20 20 20 20 74 68 65 20 76 61 6c 75 65 20 70       the value p
205f0 61 73 73 65 64 20 61 73 20 74 68 65 20 66 6f 75  assed as the fou
20600 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
20610 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
20620 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e  ()..**.**   <li>
20630 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28   <b>mode</b>: ^(
20640 54 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74  The mode paramet
20650 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f  er may be set to
20660 20 65 69 74 68 65 72 20 22 72 6f 22 2c 20 22 72   either "ro", "r
20670 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63 22  w",.**     "rwc"
20680 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20 41  , or "memory". A
20690 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65 74  ttempting to set
206a0 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 65 72   it to any other
206b0 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20 20   value is.**    
206c0 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a   an error)^. .**
206d0 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20 69 73       ^If "ro" is
206e0 20 73 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e   specified, then
206f0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
20700 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
20710 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63  -only .**     ac
20720 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20 69 66  cess, just as if
20730 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
20740 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67  N_READONLY] flag
20750 20 68 61 64 20 62 65 65 6e 20 73 65 74 20 69 6e   had been set in
20760 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74 68 69   the .**     thi
20770 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  rd argument to s
20780 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
20790 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f  . ^If the mode o
207a0 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 20  ption is set to 
207b0 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74 68  .**     "rw", th
207c0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
207d0 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
207e0 61 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e 6f  ad-write (but no
207f0 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20 20  t create) .**   
20800 20 20 61 63 63 65 73 73 2c 20 61 73 20 69 66 20    access, as if 
20810 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
20820 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20 53  WRITE (but not S
20830 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
20840 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20 62  E) had .**     b
20850 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65 20  een set. ^Value 
20860 22 72 77 63 22 20 69 73 20 65 71 75 69 76 61 6c  "rwc" is equival
20870 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 62  ent to setting b
20880 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49  oth .**     SQLI
20890 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
208a0 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45  E and SQLITE_OPE
208b0 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 66 20 74  N_CREATE.  ^If t
208c0 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69  he mode option i
208d0 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 74 6f 20  s.**     set to 
208e0 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20 61 20  "memory" then a 
208f0 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20  pure [in-memory 
20900 64 61 74 61 62 61 73 65 5d 20 74 68 61 74 20 6e  database] that n
20910 65 76 65 72 20 72 65 61 64 73 0a 2a 2a 20 20 20  ever reads.**   
20920 20 20 6f 72 20 77 72 69 74 65 73 20 66 72 6f 6d    or writes from
20930 20 64 69 73 6b 20 69 73 20 75 73 65 64 2e 20 5e   disk is used. ^
20940 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 74  It is an error t
20950 6f 20 73 70 65 63 69 66 79 20 61 20 76 61 6c 75  o specify a valu
20960 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68 65  e for.**     the
20970 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20   mode parameter 
20980 74 68 61 74 20 69 73 20 6c 65 73 73 20 72 65 73  that is less res
20990 74 72 69 63 74 69 76 65 20 74 68 61 6e 20 74 68  trictive than th
209a0 61 74 20 73 70 65 63 69 66 69 65 64 20 62 79 0a  at specified by.
209b0 2a 2a 20 20 20 20 20 74 68 65 20 66 6c 61 67 73  **     the flags
209c0 20 70 61 73 73 65 64 20 69 6e 20 74 68 65 20 74   passed in the t
209d0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
209e0 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
209f0 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69  2()..**.**   <li
20a00 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20  > <b>cache</b>: 
20a10 5e 54 68 65 20 63 61 63 68 65 20 70 61 72 61 6d  ^The cache param
20a20 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20  eter may be set 
20a30 74 6f 20 65 69 74 68 65 72 20 22 73 68 61 72 65  to either "share
20a40 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72  d" or.**     "pr
20a50 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69 6e 67  ivate". ^Setting
20a60 20 69 74 20 74 6f 20 22 73 68 61 72 65 64 22 20   it to "shared" 
20a70 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f  is equivalent to
20a80 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20   setting the.** 
20a90 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f      SQLITE_OPEN_
20aa0 53 48 41 52 45 44 43 41 43 48 45 20 62 69 74 20  SHAREDCACHE bit 
20ab0 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61 72 67  in the flags arg
20ac0 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f 0a  ument passed to.
20ad0 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33 5f 6f  **     sqlite3_o
20ae0 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74 69  pen_v2(). ^Setti
20af0 6e 67 20 74 68 65 20 63 61 63 68 65 20 70 61 72  ng the cache par
20b00 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69 76 61  ameter to "priva
20b10 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 20 65  te" is .**     e
20b20 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74  quivalent to set
20b30 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f  ting the SQLITE_
20b40 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
20b50 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49  E bit..**     ^I
20b60 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  f sqlite3_open_v
20b70 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20  2() is used and 
20b80 74 68 65 20 22 63 61 63 68 65 22 20 70 61 72 61  the "cache" para
20b90 6d 65 74 65 72 20 69 73 20 70 72 65 73 65 6e 74  meter is present
20ba0 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52 49   in.**     a URI
20bb0 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76   filename, its v
20bc0 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73 20 61  alue overrides a
20bd0 6e 79 20 62 65 68 61 76 69 6f 75 72 20 72 65 71  ny behaviour req
20be0 75 65 73 74 65 64 20 62 79 20 73 65 74 74 69 6e  uested by settin
20bf0 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f  g.**     SQLITE_
20c00 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
20c10 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e  E or SQLITE_OPEN
20c20 5f 53 48 41 52 45 44 43 41 43 48 45 20 66 6c 61  _SHAREDCACHE fla
20c30 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  g..** </ul>.**.*
20c40 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e  * ^Specifying an
20c50 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74   unknown paramet
20c60 65 72 20 69 6e 20 74 68 65 20 71 75 65 72 79 20  er in the query 
20c70 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55  component of a U
20c80 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20  RI is not an.** 
20c90 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65 20 76  error.  Future v
20ca0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
20cb0 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73 74 61  e might understa
20cc0 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 71 75  nd additional qu
20cd0 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ery.** parameter
20ce0 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72 79 20  s.  See "[query 
20cf0 70 61 72 61 6d 65 74 65 72 73 20 77 69 74 68 20  parameters with 
20d00 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20  special meaning 
20d10 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a  to SQLite]" for.
20d20 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  ** additional in
20d30 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
20d40 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 20   [[URI filename 
20d50 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55  examples]] <h3>U
20d60 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d  RI filename exam
20d70 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20  ples</h3>.**.** 
20d80 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31  <table border="1
20d90 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63  " align=center c
20da0 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a  ellpadding=5>.**
20db0 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 66 69   <tr><th> URI fi
20dc0 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65 73  lenames <th> Res
20dd0 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ults.** <tr><td>
20de0 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74   file:data.db <t
20df0 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
20e00 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64  Open the file "d
20e10 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63  ata.db" in the c
20e20 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79  urrent directory
20e30 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
20e40 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  le:/home/fred/da
20e50 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20  ta.db<br>.**    
20e60 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f        file:///ho
20e70 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20  me/fred/data.db 
20e80 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <br> .**        
20e90 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f    file://localho
20ea0 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  st/home/fred/dat
20eb0 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a  a.db <br> <td> .
20ec0 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
20ed0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
20ee0 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  le "/home/fred/d
20ef0 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e  ata.db"..** <tr>
20f00 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b  <td> file://dark
20f10 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  star/home/fred/d
20f20 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20  ata.db <td> .** 
20f30 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f           An erro
20f40 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20 69 73  r. "darkstar" is
20f50 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a 65   not a recognize
20f60 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20  d authority..** 
20f70 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77  <tr><td style="w
20f80 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61  hite-space:nowra
20f90 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  p"> .**         
20fa0 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75   file:///C:/Docu
20fb0 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30 53 65  ments%20and%20Se
20fc0 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b  ttings/fred/Desk
20fd0 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20  top/data.db.**  
20fe0 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20     <td> Windows 
20ff0 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20 66  only: Open the f
21000 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 6f 6e  ile "data.db" on
21010 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f 70 20   fred's desktop 
21020 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 20 20  on drive.**     
21030 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68       C:. Note th
21040 61 74 20 74 68 65 20 25 32 30 20 65 73 63 61 70  at the %20 escap
21050 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78 61 6d  ing in this exam
21060 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 69 63  ple is not stric
21070 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  tly .**         
21080 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73 70 61   necessary - spa
21090 63 65 20 63 68 61 72 61 63 74 65 72 73 20 63 61  ce characters ca
210a0 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65 72 61  n be used litera
210b0 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  lly.**          
210c0 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73  in URI filenames
210d0 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
210e0 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d  le:data.db?mode=
210f0 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61 74 65  ro&cache=private
21100 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
21110 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 64 61     Open file "da
21120 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75  ta.db" in the cu
21130 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 20  rrent directory 
21140 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63  for read-only ac
21150 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20  cess..**        
21160 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20    Regardless of 
21170 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73  whether or not s
21180 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 65  hared-cache mode
21190 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a   is enabled by.*
211a0 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 61 75  *          defau
211b0 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76 61 74  lt, use a privat
211c0 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e  e cache..** <tr>
211d0 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f  <td> file:/home/
211e0 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 66 73  fred/data.db?vfs
211f0 3d 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 20 3c 74 64  =unix-nolock <td
21200 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70  >.**          Op
21210 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66  en file "/home/f
21220 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55 73  red/data.db". Us
21230 65 20 74 68 65 20 73 70 65 63 69 61 6c 20 56 46  e the special VF
21240 53 20 22 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 22 2e  S "unix-nolock".
21250 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
21260 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72  e:data.db?mode=r
21270 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a  eadonly <td> .**
21280 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72            An err
21290 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20 69  or. "readonly" i
212a0 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f 70  s not a valid op
212b0 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f  tion for the "mo
212c0 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  de" parameter..*
212d0 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a  * </table>.**.**
212e0 20 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d 61   ^URI hexadecima
212f0 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63  l escape sequenc
21300 65 73 20 28 25 48 48 29 20 61 72 65 20 73 75 70  es (%HH) are sup
21310 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74 68  ported within th
21320 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75  e path and.** qu
21330 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f  ery components o
21340 66 20 61 20 55 52 49 2e 20 41 20 68 65 78 61 64  f a URI. A hexad
21350 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
21360 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73 20  quence consists 
21370 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20  of a.** percent 
21380 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c  sign - "%" - fol
21390 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c 79  lowed by exactly
213a0 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61 6c   two hexadecimal
213b0 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65 63   digits .** spec
213c0 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74 20  ifying an octet 
213d0 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20 74  value. ^Before t
213e0 68 65 20 70 61 74 68 20 6f 72 20 71 75 65 72 79  he path or query
213f0 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61   components of a
21400 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  .** URI filename
21410 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
21420 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f 64  , they are encod
21430 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20 61  ed using UTF-8 a
21440 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64  nd all .** hexad
21450 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
21460 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65 64  quences replaced
21470 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79 74   by a single byt
21480 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  e containing the
21490 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  .** correspondin
214a0 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69 73  g octet. If this
214b0 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61 74   process generat
214c0 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55 54  es an invalid UT
214d0 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a  F-8 encoding,.**
214e0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
214f0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
21500 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e  * <b>Note to Win
21510 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20  dows users:</b> 
21520 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73   The encoding us
21530 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e  ed for the filen
21540 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ame argument.** 
21550 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  of sqlite3_open(
21560 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
21570 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20  en_v2() must be 
21580 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65  UTF-8, not whate
21590 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20  ver.** codepage 
215a0 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  is currently def
215b0 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73  ined.  Filenames
215c0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65   containing inte
215d0 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61  rnational.** cha
215e0 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20  racters must be 
215f0 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46  converted to UTF
21600 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73  -8 prior to pass
21610 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a  ing them into.**
21620 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
21630 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
21640 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e  v2()..**.** <b>N
21650 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52  ote to Windows R
21660 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62  untime users:</b
21670 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79  >  The temporary
21680 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20   directory must 
21690 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20  be set.** prior 
216a0 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74  to calling sqlit
216b0 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
216c0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20  ite3_open_v2(). 
216d0 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72 69   Otherwise, vari
216e0 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20  ous.** features 
216f0 74 68 61 74 20 72 65 71 75 69 72 65 20 74 68 65  that require the
21700 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72   use of temporar
21710 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c  y files may fail
21720 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
21730 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f  : [sqlite3_temp_
21740 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 69 6e  directory].*/.in
21750 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a  t sqlite3_open(.
21760 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69    const char *fi
21770 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
21780 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
21790 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69  UTF-8) */.  sqli
217a0 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20  te3 **ppDb      
217b0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
217c0 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
217d0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
217e0 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76  pen16(.  const v
217f0 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  oid *filename,  
21800 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
21810 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a  ename (UTF-16) *
21820 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
21830 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db          /* O
21840 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
21850 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  ndle */.);.int s
21860 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a  qlite3_open_v2(.
21870 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69    const char *fi
21880 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
21890 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
218a0 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69  UTF-8) */.  sqli
218b0 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20  te3 **ppDb,     
218c0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
218d0 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
218e0 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20    int flags,    
218f0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61            /* Fla
21900 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  gs */.  const ch
21910 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20  ar *zVfs        
21920 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d  /* Name of VFS m
21930 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a  odule to use */.
21940 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
21950 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75 65  EF: Obtain Value
21960 73 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d 65  s For URI Parame
21970 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ters.**.** These
21980 20 61 72 65 20 75 74 69 6c 69 74 79 20 72 6f 75   are utility rou
21990 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20 74 6f  tines, useful to
219a0 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
219b0 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63 6b  ions, that check
219c0 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61 20  .** to see if a 
219d0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61  database file wa
219e0 73 20 61 20 55 52 49 20 74 68 61 74 20 63 6f 6e  s a URI that con
219f0 74 61 69 6e 65 64 20 61 20 73 70 65 63 69 66 69  tained a specifi
21a00 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72 61  c query .** para
21a10 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73 6f  meter, and if so
21a20 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61 6c   obtains the val
21a30 75 65 20 6f 66 20 74 68 61 74 20 71 75 65 72 79  ue of that query
21a40 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
21a50 2a 20 49 66 20 46 20 69 73 20 74 68 65 20 64 61  * If F is the da
21a60 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
21a70 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 69  pointer passed i
21a80 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 20  nto the xOpen() 
21a90 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20  method of .** a 
21aa0 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
21ab0 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c 61 67  on when the flag
21ac0 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78  s parameter to x
21ad0 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f  Open() has one o
21ae0 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68  r .** more of th
21af0 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  e [SQLITE_OPEN_U
21b00 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f  RI] or [SQLITE_O
21b10 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74  PEN_MAIN_DB] bit
21b20 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69  s set and.** P i
21b30 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
21b40 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  e query paramete
21b50 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  r, then.** sqlit
21b60 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72  e3_uri_parameter
21b70 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 74 68  (F,P) returns th
21b80 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 50  e value of the P
21b90 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66  .** parameter if
21ba0 20 69 74 20 65 78 69 73 74 73 20 6f 72 20 61 20   it exists or a 
21bb0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20  NULL pointer if 
21bc0 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61  P does not appea
21bd0 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65 72 79  r as a .** query
21be0 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e   parameter on F.
21bf0 20 20 49 66 20 50 20 69 73 20 61 20 71 75 65 72    If P is a quer
21c00 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 46  y parameter of F
21c10 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c 69  .** has no expli
21c20 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20  cit value, then 
21c30 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
21c40 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72  meter(F,P) retur
21c50 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  ns.** a pointer 
21c60 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  to an empty stri
21c70 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ng..**.** The sq
21c80 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
21c90 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65  n(F,P,B) routine
21ca0 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 50 20   assumes that P 
21cb0 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20  is a boolean.** 
21cc0 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65  parameter and re
21cd0 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 6f  turns true (1) o
21ce0 72 20 66 61 6c 73 65 20 28 30 29 20 61 63 63 6f  r false (0) acco
21cf0 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76 61 6c  rding to the val
21d00 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65  ue.** of P.  The
21d10 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
21d20 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74  lean(F,P,B) rout
21d30 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72 75 65  ine returns true
21d40 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a 20 76   (1) if the.** v
21d50 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20 70 61  alue of query pa
21d60 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65  rameter P is one
21d70 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72 75 65   of "yes", "true
21d80 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e  ", or "on" in an
21d90 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69 66 20  y.** case or if 
21da0 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73  the value begins
21db0 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f   with a non-zero
21dc0 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a   number.  The .*
21dd0 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  * sqlite3_uri_bo
21de0 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75  olean(F,P,B) rou
21df0 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20 66 61  tines returns fa
21e00 6c 73 65 20 28 30 29 20 69 66 20 74 68 65 20 76  lse (0) if the v
21e10 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79  alue of.** query
21e20 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20   parameter P is 
21e30 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61  one of "no", "fa
21e40 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22 20 69  lse", or "off" i
21e50 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a  n any case or.**
21e60 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65   if the value be
21e70 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75 6d 65  gins with a nume
21e80 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20 50 20  ric zero.  If P 
21e90 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a  is not a query.*
21ea0 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46  * parameter on F
21eb0 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65   or if the value
21ec0 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20 6e 6f   of P is does no
21ed0 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66 20 74  t match any of t
21ee0 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65  he.** above, the
21ef0 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  n sqlite3_uri_bo
21f00 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74  olean(F,P,B) ret
21f10 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a  urns (B!=0)..**.
21f20 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  ** The sqlite3_u
21f30 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29 20  ri_int64(F,P,D) 
21f40 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72 74 73  routine converts
21f50 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20   the value of P 
21f60 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74  into a.** 64-bit
21f70 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20   signed integer 
21f80 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68 61 74  and returns that
21f90 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44 20 69   integer, or D i
21fa0 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  f P does not.** 
21fb0 65 78 69 73 74 2e 20 20 49 66 20 74 68 65 20 76  exist.  If the v
21fc0 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73 6f 6d  alue of P is som
21fd0 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61  ething other tha
21fe0 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68  n an integer, th
21ff0 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65  en.** zero is re
22000 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49  turned..** .** I
22010 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  f F is a NULL po
22020 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71 6c 69  inter, then sqli
22030 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
22040 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 4e  r(F,P) returns N
22050 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74  ULL and.** sqlit
22060 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
22070 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 42 2e  ,P,B) returns B.
22080 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20 61 20    If F is not a 
22090 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64  NULL pointer and
220a0 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64 61 74  .** is not a dat
220b0 61 62 61 73 65 20 66 69 6c 65 20 70 61 74 68 6e  abase file pathn
220c0 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ame pointer that
220d0 20 53 51 4c 69 74 65 20 70 61 73 73 65 64 20 69   SQLite passed i
220e0 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a  nto the xOpen.**
220f0 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68 65   VFS method, the
22100 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  n the behavior o
22110 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  f this routine i
22120 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20  s undefined and 
22130 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65  probably.** unde
22140 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73  sirable..*/.cons
22150 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
22160 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f  uri_parameter(co
22170 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e  nst char *zFilen
22180 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  ame, const char 
22190 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e 74 20 73 71  *zParam);.int sq
221a0 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
221b0 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  n(const char *zF
221c0 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  ile, const char 
221d0 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65  *zParam, int bDe
221e0 66 61 75 6c 74 29 3b 0a 73 71 6c 69 74 65 33 5f  fault);.sqlite3_
221f0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 72  int64 sqlite3_ur
22200 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20 63 68  i_int64(const ch
22210 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  ar*, const char*
22220 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
22230 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ;.../*.** CAPI3R
22240 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20  EF: Error Codes 
22250 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a  And Messages.**.
22260 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
22270 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66  errcode() interf
22280 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
22290 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20  numeric [result 
222a0 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  code] or.** [ext
222b0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
222c0 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20  e] for the most 
222d0 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71  recent failed sq
222e0 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c  lite3_* API call
222f0 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
22300 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20  ith a [database 
22310 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20  connection]. If 
22320 61 20 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c  a prior API call
22330 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74   failed.** but t
22340 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41  he most recent A
22350 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65  PI call succeede
22360 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  d, the return va
22370 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69  lue from.** sqli
22380 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73  te3_errcode() is
22390 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 5e 54 68   undefined.  ^Th
223a0 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  e sqlite3_extend
223b0 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20  ed_errcode().** 
223c0 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 65  interface is the
223d0 20 73 61 6d 65 20 65 78 63 65 70 74 20 74 68 61   same except tha
223e0 74 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75  t it always retu
223f0 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74  rns the .** [ext
22400 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
22410 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74  e] even when ext
22420 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
22430 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c  es are.** disabl
22440 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
22450 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20  qlite3_errmsg() 
22460 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  and sqlite3_errm
22470 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e  sg16() return En
22480 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a  glish-language.*
22490 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63  * text that desc
224a0 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c  ribes the error,
224b0 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38   as either UTF-8
224c0 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65   or UTF-16 respe
224d0 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65  ctively..** ^(Me
224e0 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
224f0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
22500 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64  tring is managed
22510 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20   internally..** 
22520 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
22530 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
22540 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65   worry about fre
22550 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e  eing the result.
22560 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65  .** However, the
22570 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69   error string mi
22580 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74  ght be overwritt
22590 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65  en or deallocate
225a0 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65  d by.** subseque
225b0 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65  nt calls to othe
225c0 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
225d0 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a  ce functions.)^.
225e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
225f0 65 33 5f 65 72 72 73 74 72 28 29 20 69 6e 74 65  e3_errstr() inte
22600 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
22610 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61  e English-langua
22620 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 61 74 20  ge text.** that 
22630 64 65 73 63 72 69 62 65 73 20 74 68 65 20 5b 72  describes the [r
22640 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73 20  esult code], as 
22650 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f  UTF-8..** ^(Memo
22660 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65  ry to hold the e
22670 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
22680 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69  ing is managed i
22690 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64  nternally.** and
226a0 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 66 72 65   must not be fre
226b0 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ed by the applic
226c0 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57  ation)^..**.** W
226d0 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a  hen the serializ
226e0 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
226f0 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69  de] is in use, i
22700 74 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a  t might be the.*
22710 2a 20 63 61 73 65 20 74 68 61 74 20 61 20 73 65  * case that a se
22720 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72  cond error occur
22730 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20  s on a separate 
22740 74 68 72 65 61 64 20 69 6e 20 62 65 74 77 65 65  thread in betwee
22750 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66  n.** the time of
22760 20 74 68 65 20 66 69 72 73 74 20 65 72 72 6f 72   the first error
22770 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f   and the call to
22780 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
22790 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20  s..** When that 
227a0 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63  happens, the sec
227b0 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62  ond error will b
227c0 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65  e reported since
227d0 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66   these.** interf
227e0 61 63 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f  aces always repo
227f0 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  rt the most rece
22800 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61  nt result.  To a
22810 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61  void.** this, ea
22820 63 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62  ch thread can ob
22830 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75  tain exclusive u
22840 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62  se of the [datab
22850 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
22860 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67  D.** by invoking
22870 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
22880 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f  enter]([sqlite3_
22890 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65  db_mutex](D)) be
228a0 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a  fore beginning.*
228b0 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69  * to use D and i
228c0 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33  nvoking [sqlite3
228d0 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73  _mutex_leave]([s
228e0 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d  qlite3_db_mutex]
228f0 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c  (D)) after.** al
22900 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69  l calls to the i
22910 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74 65 64  nterfaces listed
22920 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65   here are comple
22930 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  ted..**.** If an
22940 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73   interface fails
22950 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53   with SQLITE_MIS
22960 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  USE, that means 
22970 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  the interface.**
22980 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63   was invoked inc
22990 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68 65 20  orrectly by the 
229a0 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e  application.  In
229b0 20 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a   that case, the.
229c0 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e  ** error code an
229d0 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72  d message may or
229e0 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e   may not be set.
229f0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
22a00 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20  errcode(sqlite3 
22a10 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *db);.int sqlite
22a20 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
22a30 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b  de(sqlite3 *db);
22a40 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
22a50 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69  ite3_errmsg(sqli
22a60 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  te3*);.const voi
22a70 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  d *sqlite3_errms
22a80 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63  g16(sqlite3*);.c
22a90 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
22aa0 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29 3b 0a  e3_errstr(int);.
22ab0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
22ac0 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f   SQL Statement O
22ad0 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44  bject.** KEYWORD
22ae0 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 61  S: {prepared sta
22af0 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65  tement} {prepare
22b00 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a  d statements}.**
22b10 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
22b20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72  of this object r
22b30 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67  epresents a sing
22b40 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  le SQL statement
22b50 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
22b60 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e   is variously kn
22b70 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70 61 72  own as a "prepar
22b80 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72  ed statement" or
22b90 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20   a.** "compiled 
22ba0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f  SQL statement" o
22bb0 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73  r simply as a "s
22bc0 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a  tatement"..**.**
22bd0 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73   The life of a s
22be0 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20  tatement object 
22bf0 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c  goes something l
22c00 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20  ike this:.**.** 
22c10 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65  <ol>.** <li> Cre
22c20 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75  ate the object u
22c30 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
22c40 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61  epare_v2()] or a
22c50 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20   related.**     
22c60 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c   function..** <l
22c70 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74  i> Bind values t
22c80 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  o [host paramete
22c90 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71  rs] using the sq
22ca0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a  lite3_bind_*().*
22cb0 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65  *      interface
22cc0 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74  s..** <li> Run t
22cd0 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e  he SQL by callin
22ce0 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
22cf0 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74  )] one or more t
22d00 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65  imes..** <li> Re
22d10 73 65 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e  set the statemen
22d20 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
22d30 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67  _reset()] then g
22d40 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74  o back.**      t
22d50 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68  o step 2.  Do th
22d60 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20  is zero or more 
22d70 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44  times..** <li> D
22d80 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63  estroy the objec
22d90 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
22da0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a  _finalize()]..**
22db0 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66   </ol>.**.** Ref
22dc0 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74  er to documentat
22dd0 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61  ion on individua
22de0 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  l methods above 
22df0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
22e00 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
22e10 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
22e20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71   sqlite3_stmt sq
22e30 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a  lite3_stmt;../*.
22e40 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
22e50 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a  -time Limits.**.
22e60 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66  ** ^(This interf
22e70 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73  ace allows the s
22e80 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63  ize of various c
22e90 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
22ea0 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20  limited.** on a 
22eb0 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f  connection by co
22ec0 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20  nnection basis. 
22ed0 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
22ee0 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b  eter is the.** [
22ef0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
22f00 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74  ion] whose limit
22f10 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72   is to be set or
22f20 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a   queried.  The.*
22f30 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
22f40 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65  er is one of the
22f50 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69   [limit categori
22f60 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20  es] that define 
22f70 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f  a.** class of co
22f80 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73  nstructs to be s
22f90 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68  ize limited.  Th
22fa0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
22fb0 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20  r is the.** new 
22fc0 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63  limit for that c
22fd0 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a  onstruct.)^.**.*
22fe0 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69  * ^If the new li
22ff0 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76  mit is a negativ
23000 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69  e number, the li
23010 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64  mit is unchanged
23020 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20  ..** ^(For each 
23030 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53  limit category S
23040 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e  QLITE_LIMIT_<i>N
23050 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73  AME</i> there is
23060 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c   a .** [limits |
23070 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
23080 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d  d].** set at com
23090 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43  pile-time by a C
230a0 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
230b0 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c  cro called.** [l
230c0 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d  imits | SQLITE_M
230d0 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e  AX_<i>NAME</i>].
230e0 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54  .** (The "_LIMIT
230f0 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69  _" in the name i
23100 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d  s changed to "_M
23110 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74  AX_".))^.** ^Att
23120 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73  empts to increas
23130 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20  e a limit above 
23140 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62  its hard upper b
23150 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65  ound are.** sile
23160 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74  ntly truncated t
23170 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72  o the hard upper
23180 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52   bound..**.** ^R
23190 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
231a0 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
231b0 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65  limit was change
231c0 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69  d, the .** [sqli
231d0 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74  te3_limit()] int
231e0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
231f0 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f  he prior value o
23200 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20  f the limit..** 
23210 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20  ^Hence, to find 
23220 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75  the current valu
23230 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74  e of a limit wit
23240 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74  hout changing it
23250 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f  ,.** simply invo
23260 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  ke this interfac
23270 65 20 77 69 74 68 20 74 68 65 20 74 68 69 72 64  e with the third
23280 20 70 61 72 61 6d 65 74 65 72 20 73 65 74 20 74   parameter set t
23290 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d  o -1..**.** Run-
232a0 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20  time limits are 
232b0 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
232c0 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   in applications
232d0 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20   that manage.** 
232e0 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69  both their own i
232f0 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65  nternal database
23300 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61   and also databa
23310 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e  ses that are con
23320 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e  trolled.** by un
23330 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c  trusted external
23340 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78   sources.  An ex
23350 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f  ample applicatio
23360 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20  n might be a.** 
23370 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 74  web browser that
23380 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74   has its own dat
23390 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69  abases for stori
233a0 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a  ng history and.*
233b0 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62  * separate datab
233c0 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20  ases controlled 
233d0 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70  by JavaScript ap
233e0 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c  plications downl
233f0 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65  oaded.** off the
23400 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20   Internet.  The 
23410 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73  internal databas
23420 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20  es can be given 
23430 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65  the.** large, de
23440 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44  fault limits.  D
23450 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64  atabases managed
23460 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75   by external sou
23470 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67  rces can.** be g
23480 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65  iven much smalle
23490 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65  r limits designe
234a0 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64  d to prevent a d
234b0 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65  enial of service
234c0 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76  .** attack.  Dev
234d0 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c  elopers might al
234e0 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74  so want to use t
234f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
23500 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a  authorizer()].**
23510 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75   interface to fu
23520 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e  rther control un
23530 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68  trusted SQL.  Th
23540 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61  e size of the da
23550 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65  tabase.** create
23560 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65  d by an untruste
23570 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20  d script can be 
23580 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20  contained using 
23590 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65  the.** [max_page
235a0 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d  _count] [PRAGMA]
235b0 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d  ..**.** New run-
235c0 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67  time limit categ
235d0 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64  ories may be add
235e0 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
235f0 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71  eases..*/.int sq
23600 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69  lite3_limit(sqli
23610 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e  te3*, int id, in
23620 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a  t newVal);../*.*
23630 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d  * CAPI3REF: Run-
23640 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67  Time Limit Categ
23650 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  ories.** KEYWORD
23660 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f  S: {limit catego
23670 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65  ry} {*limit cate
23680 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68  gories}.**.** Th
23690 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65  ese constants de
236a0 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72  fine various per
236b0 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a  formance limits.
236c0 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c  ** that can be l
236d0 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69  owered at run-ti
236e0 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  me using [sqlite
236f0 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54  3_limit()]..** T
23700 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74  he synopsis of t
23710 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74  he meanings of t
23720 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74  he various limit
23730 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77  s is shown below
23740 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20  ..** Additional 
23750 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61  information is a
23760 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d  vailable at [lim
23770 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20  its | Limits in 
23780 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  SQLite]..**.** <
23790 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  dl>.** [[SQLITE_
237a0 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e  LIMIT_LENGTH]] ^
237b0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
237c0 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a  T_LENGTH</dt>.**
237d0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
237e0 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72   size of any str
237f0 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74  ing or BLOB or t
23800 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 74  able row, in byt
23810 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  es.<dd>)^.**.** 
23820 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  [[SQLITE_LIMIT_S
23830 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64  QL_LENGTH]] ^(<d
23840 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  t>SQLITE_LIMIT_S
23850 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  QL_LENGTH</dt>.*
23860 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
23870 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53  m length of an S
23880 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e  QL statement, in
23890 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a   bytes.</dd>)^.*
238a0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
238b0 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c  MIT_COLUMN]] ^(<
238c0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
238d0 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c  COLUMN</dt>.** <
238e0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
238f0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
23900 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69   in a table defi
23910 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65  nition or in the
23920 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f  .** result set o
23930 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20  f a [SELECT] or 
23940 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  the maximum numb
23950 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
23960 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20   an index.** or 
23970 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f  in an ORDER BY o
23980 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73  r GROUP BY claus
23990 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  e.</dd>)^.**.** 
239a0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  [[SQLITE_LIMIT_E
239b0 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64  XPR_DEPTH]] ^(<d
239c0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  t>SQLITE_LIMIT_E
239d0 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a  XPR_DEPTH</dt>.*
239e0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
239f0 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 70  m depth of the p
23a00 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79  arse tree on any
23a10 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64   expression.</dd
23a20 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
23a30 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
23a40 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74  D_SELECT]] ^(<dt
23a50 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  >SQLITE_LIMIT_CO
23a60 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64  MPOUND_SELECT</d
23a70 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
23a80 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
23a90 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f  terms in a compo
23aa0 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65  und SELECT state
23ab0 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ment.</dd>)^.**.
23ac0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
23ad0 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64  T_VDBE_OP]] ^(<d
23ae0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  t>SQLITE_LIMIT_V
23af0 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  DBE_OP</dt>.** <
23b00 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
23b10 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63  umber of instruc
23b20 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75  tions in a virtu
23b30 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72  al machine progr
23b40 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d  am.** used to im
23b50 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73  plement an SQL s
23b60 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 69 73 20  tatement.  This 
23b70 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 75 72  limit is not cur
23b80 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63  rently.** enforc
23b90 65 64 2c 20 74 68 6f 75 67 68 20 74 68 61 74 20  ed, though that 
23ba0 6d 69 67 68 74 20 62 65 20 61 64 64 65 64 20 69  might be added i
23bb0 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65  n some future re
23bc0 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69  lease of.** SQLi
23bd0 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  te.</dd>)^.**.**
23be0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
23bf0 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e  FUNCTION_ARG]] ^
23c00 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
23c10 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f  T_FUNCTION_ARG</
23c20 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
23c30 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
23c40 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20   arguments on a 
23c50 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e  function.</dd>)^
23c60 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
23c70 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 5d 5d  LIMIT_ATTACHED]]
23c80 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
23c90 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74  MIT_ATTACHED</dt
23ca0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
23cb0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b  imum number of [
23cc0 41 54 54 41 43 48 20 7c 20 61 74 74 61 63 68 65  ATTACH | attache
23cd0 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c  d databases].)^<
23ce0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
23cf0 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50  ITE_LIMIT_LIKE_P
23d00 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a  ATTERN_LENGTH]].
23d10 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
23d20 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
23d30 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  RN_LENGTH</dt>.*
23d40 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
23d50 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  m length of the 
23d60 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74  pattern argument
23d70 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f   to the [LIKE] o
23d80 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72  r.** [GLOB] oper
23d90 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ators.</dd>)^.**
23da0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
23db0 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
23dc0 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  ER]].** ^(<dt>SQ
23dd0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
23de0 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a  BLE_NUMBER</dt>.
23df0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
23e00 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20  um index number 
23e10 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65  of any [paramete
23e20 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61  r] in an SQL sta
23e30 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  tement.)^.**.** 
23e40 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54  [[SQLITE_LIMIT_T
23e50 52 49 47 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e  RIGGER_DEPTH]] ^
23e60 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
23e70 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c  T_TRIGGER_DEPTH<
23e80 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
23e90 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66  maximum depth of
23ea0 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74   recursion for t
23eb0 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a  riggers.</dd>)^.
23ec0 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
23ed0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
23ee0 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20  _LENGTH         
23ef0 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65             0.#de
23f00 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
23f10 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20  T_SQL_LENGTH    
23f20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64              1.#d
23f30 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
23f40 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20  IT_COLUMN       
23f50 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23               2.#
23f60 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
23f70 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20  MIT_EXPR_DEPTH  
23f80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a                3.
23f90 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
23fa0 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
23fb0 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 34  LECT           4
23fc0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
23fd0 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20  LIMIT_VDBE_OP   
23fe0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
23ff0 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  5.#define SQLITE
24000 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
24010 41 52 47 20 20 20 20 20 20 20 20 20 20 20 20 20  ARG             
24020 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   6.#define SQLIT
24030 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
24040 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
24050 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    7.#define SQLI
24060 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41  TE_LIMIT_LIKE_PA
24070 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20  TTERN_LENGTH    
24080 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c     8.#define SQL
24090 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
240a0 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20  LE_NUMBER       
240b0 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51      9.#define SQ
240c0 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
240d0 45 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20  ER_DEPTH        
240e0 20 20 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41      10../*.** CA
240f0 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e  PI3REF: Compilin
24100 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  g An SQL Stateme
24110 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  nt.** KEYWORDS: 
24120 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63  {SQL statement c
24130 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54  ompiler}.**.** T
24140 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c  o execute an SQL
24150 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20   query, it must 
24160 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65  first be compile
24170 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f  d into a byte-co
24180 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73  de.** program us
24190 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65  ing one of these
241a0 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
241b0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
241c0 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20  ent, "db", is a 
241d0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
241e0 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66  tion] obtained f
241f0 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73  rom a.** prior s
24200 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
24210 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
24220 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
24230 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  n_v2()] or.** [s
24240 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
24250 2e 20 20 54 68 65 20 64 61 74 61 62 61 73 65 20  .  The database 
24260 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20  connection must 
24270 6e 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c  not have been cl
24280 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  osed..**.** The 
24290 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c  second argument,
242a0 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20   "zSql", is the 
242b0 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20  statement to be 
242c0 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65  compiled, encode
242d0 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55  d.** as either U
242e0 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20  TF-8 or UTF-16. 
242f0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   The sqlite3_pre
24300 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74  pare() and sqlit
24310 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a  e3_prepare_v2().
24320 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73  ** interfaces us
24330 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c  e UTF-8, and sql
24340 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
24350 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
24360 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75  pare16_v2().** u
24370 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a  se UTF-16..**.**
24380 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20 61   ^If the nByte a
24390 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 20  rgument is less 
243a0 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20  than zero, then 
243b0 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 20  zSql is read up 
243c0 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  to the.** first 
243d0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
243e0 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 6e 6f   ^If nByte is no
243f0 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  n-negative, then
24400 20 69 74 20 69 73 20 74 68 65 20 6d 61 78 69 6d   it is the maxim
24410 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  um.** number of 
24420 20 62 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d   bytes read from
24430 20 7a 53 71 6c 2e 20 20 5e 57 68 65 6e 20 6e 42   zSql.  ^When nB
24440 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  yte is non-negat
24450 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c  ive, the.** zSql
24460 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74 20   string ends at 
24470 65 69 74 68 65 72 20 74 68 65 20 66 69 72 73 74  either the first
24480 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 30 30   '\000' or '\u00
24490 30 30 27 20 63 68 61 72 61 63 74 65 72 20 6f 72  00' character or
244a0 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d 74 68  .** the nByte-th
244b0 20 62 79 74 65 2c 20 77 68 69 63 68 65 76 65 72   byte, whichever
244c0 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 49 66   comes first. If
244d0 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77   the caller know
244e0 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73 75  s.** that the su
244f0 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73  pplied string is
24500 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c   nul-terminated,
24510 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 61   then there is a
24520 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72   small.** perfor
24530 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20  mance advantage 
24540 74 6f 20 62 65 20 67 61 69 6e 65 64 20 62 79 20  to be gained by 
24550 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65  passing an nByte
24560 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a   parameter that.
24570 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f 20 74  ** is equal to t
24580 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
24590 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20  es in the input 
245a0 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64  string <i>includ
245b0 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e  ing</i>.** the n
245c0 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62 79  ul-terminator by
245d0 74 65 73 20 61 73 20 74 68 69 73 20 73 61 76 65  tes as this save
245e0 73 20 53 51 4c 69 74 65 20 66 72 6f 6d 20 68 61  s SQLite from ha
245f0 76 69 6e 67 20 74 6f 0a 2a 2a 20 6d 61 6b 65 20  ving to.** make 
24600 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 69 6e  a copy of the in
24610 70 75 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  put string..**.*
24620 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 20  * ^If pzTail is 
24630 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70  not NULL then *p
24640 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f  zTail is made to
24650 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69   point to the fi
24660 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74  rst byte.** past
24670 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20   the end of the 
24680 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d  first SQL statem
24690 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68  ent in zSql.  Th
246a0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c  ese routines onl
246b0 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65  y.** compile the
246c0 20 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74   first statement
246d0 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a   in zSql, so *pz
246e0 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69  Tail is left poi
246f0 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74  nting to.** what
24700 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69   remains uncompi
24710 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53  led..**.** ^*ppS
24720 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e  tmt is left poin
24730 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c  ting to a compil
24740 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ed [prepared sta
24750 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e  tement] that can
24760 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20   be.** executed 
24770 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  using [sqlite3_s
24780 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65  tep()].  ^If the
24790 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20  re is an error, 
247a0 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a  *ppStmt is set.*
247b0 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20  * to NULL.  ^If 
247c0 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63  the input text c
247d0 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28  ontains no SQL (
247e0 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20  if the input is 
247f0 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69  an empty.** stri
24800 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29  ng or a comment)
24810 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73   then *ppStmt is
24820 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a   set to NULL..**
24830 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f   The calling pro
24840 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e  cedure is respon
24850 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69  sible for deleti
24860 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a  ng the compiled.
24870 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
24880 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
24890 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65  finalize()] afte
248a0 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65  r it has finishe
248b0 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70  d with it..** pp
248c0 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20  Stmt may not be 
248d0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20  NULL..**.** ^On 
248e0 73 75 63 63 65 73 73 2c 20 74 68 65 20 73 71 6c  success, the sql
248f0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 66  ite3_prepare() f
24900 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65  amily of routine
24910 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  s return [SQLITE
24920 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69  _OK];.** otherwi
24930 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  se an [error cod
24940 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  e] is returned..
24950 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
24960 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 61  3_prepare_v2() a
24970 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
24980 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66  re16_v2() interf
24990 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f  aces are.** reco
249a0 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20  mmended for all 
249b0 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68  new programs. Th
249c0 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65  e two older inte
249d0 72 66 61 63 65 73 20 61 72 65 20 72 65 74 61 69  rfaces are retai
249e0 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77  ned.** for backw
249f0 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
24a00 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73  ty, but their us
24a10 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64  e is discouraged
24a20 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 32  ..** ^In the "v2
24a30 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68  " interfaces, th
24a40 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
24a50 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20  ment.** that is 
24a60 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73  returned (the [s
24a70 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
24a80 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20  ect) contains a 
24a90 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f  copy of the.** o
24aa0 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74  riginal SQL text
24ab0 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68  . This causes th
24ac0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
24ad0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a  )] interface to.
24ae0 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66 65 72  ** behave differ
24af0 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77  ently in three w
24b00 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  ays:.**.** <ol>.
24b10 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74  ** <li>.** ^If t
24b20 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
24b30 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74  ma changes, inst
24b40 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67  ead of returning
24b50 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
24b60 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73   as it.** always
24b70 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71   used to do, [sq
24b80 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
24b90 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ll automatically
24ba0 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53   recompile the S
24bb0 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  QL.** statement 
24bc0 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69  and try to run i
24bd0 74 20 61 67 61 69 6e 2e 0a 2a 2a 20 3c 2f 6c 69  t again..** </li
24be0 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  >.**.** <li>.** 
24bf0 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f  ^When an error o
24c00 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f  ccurs, [sqlite3_
24c10 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74  step()] will ret
24c20 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64  urn one of the d
24c30 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f  etailed.** [erro
24c40 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74  r codes] or [ext
24c50 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
24c60 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79  s].  ^The legacy
24c70 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68   behavior was th
24c80 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  at.** [sqlite3_s
24c90 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c  tep()] would onl
24ca0 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72  y return a gener
24cb0 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ic [SQLITE_ERROR
24cc0 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a  ] result code.**
24cd0 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61   and the applica
24ce0 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20  tion would have 
24cf0 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64  to make a second
24d00 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
24d10 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e  3_reset()].** in
24d20 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74   order to find t
24d30 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61  he underlying ca
24d40 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c  use of the probl
24d50 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32  em. With the "v2
24d60 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74  " prepare.** int
24d70 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64  erfaces, the und
24d80 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66  erlying reason f
24d90 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20  or the error is 
24da0 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61  returned immedia
24db0 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  tely..** </li>.*
24dc0 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66  *.** <li>.** ^If
24dd0 20 74 68 65 20 73 70 65 63 69 66 69 63 20 76 61   the specific va
24de0 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61  lue bound to [pa
24df0 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70  rameter | host p
24e00 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65  arameter] in the
24e10 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73   .** WHERE claus
24e20 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63  e might influenc
24e30 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20  e the choice of 
24e40 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61  query plan for a
24e50 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74   statement,.** t
24e60 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hen the statemen
24e70 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61  t will be automa
24e80 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c  tically recompil
24e90 65 64 2c 20 61 73 20 69 66 20 74 68 65 72 65 20  ed, as if there 
24ea0 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73  had been .** a s
24eb0 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e  chema change, on
24ec0 20 74 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c   the first  [sql
24ed0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c  ite3_step()] cal
24ee0 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20  l following any 
24ef0 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65  change.** to the
24f00 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
24f10 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20  ext | bindings] 
24f20 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74  of that [paramet
24f30 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70  er]. .** ^The sp
24f40 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20  ecific value of 
24f50 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61  WHERE-clause [pa
24f60 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69  rameter] might i
24f70 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a  nfluence the .**
24f80 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79   choice of query
24f90 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72   plan if the par
24fa0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c 65  ameter is the le
24fb0 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20  ft-hand side of 
24fc0 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b  a [LIKE].** or [
24fd0 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f  GLOB] operator o
24fe0 72 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  r if the paramet
24ff0 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74  er is compared t
25000 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c  o an indexed col
25010 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b  umn.** and the [
25020 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54  SQLITE_ENABLE_ST
25030 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  AT3] compile-tim
25040 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62  e option is enab
25050 6c 65 64 2e 0a 2a 2a 20 74 68 65 20 0a 2a 2a 20  led..** the .** 
25060 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a  </li>.** </ol>.*
25070 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  /.int sqlite3_pr
25080 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33  epare(.  sqlite3
25090 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
250a0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
250b0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
250c0 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  har *zSql,      
250d0 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
250e0 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  t, UTF-8 encoded
250f0 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
25100 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
25110 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
25120 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
25130 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
25140 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
25150 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
25160 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
25170 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
25180 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
25190 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
251a0 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
251b0 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
251c0 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73  _prepare_v2(.  s
251d0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
251e0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
251f0 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
25200 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
25210 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
25220 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65  atement, UTF-8 e
25230 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
25240 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
25250 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
25260 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
25270 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
25280 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
25290 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
252a0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
252b0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a  .  const char **
252c0 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
252d0 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
252e0 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
252f0 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
25300 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
25310 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
25320 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
25330 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
25340 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
25350 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
25360 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
25370 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  F-16 encoded */.
25380 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
25390 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
253a0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
253b0 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
253c0 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
253d0 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
253e0 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
253f0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
25400 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  oid **pzTail    
25410 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
25420 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
25430 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
25440 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
25450 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c  pare16_v2(.  sql
25460 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
25470 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
25480 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
25490 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20  st void *zSql,  
254a0 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
254b0 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e  ement, UTF-16 en
254c0 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
254d0 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
254e0 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
254f0 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
25500 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
25510 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
25520 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
25530 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
25540 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70    const void **p
25550 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
25560 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
25570 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
25580 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  Sql */.);../*.**
25590 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72 69   CAPI3REF: Retri
255a0 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20  eving Statement 
255b0 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  SQL.**.** ^This 
255c0 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
255d0 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76   used to retriev
255e0 65 20 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f  e a saved copy o
255f0 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a  f the original.*
25600 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20  * SQL text used 
25610 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72 65  to create a [pre
25620 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
25630 20 69 66 20 74 68 61 74 20 73 74 61 74 65 6d 65   if that stateme
25640 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c  nt was.** compil
25650 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20  ed using either 
25660 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
25670 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
25680 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
25690 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  )]..*/.const cha
256a0 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73  r *sqlite3_sql(s
256b0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
256c0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
256d0 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20  3REF: Determine 
256e0 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  If An SQL Statem
256f0 65 6e 74 20 57 72 69 74 65 73 20 54 68 65 20 44  ent Writes The D
25700 61 74 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20 5e 54  atabase.**.** ^T
25710 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  he sqlite3_stmt_
25720 72 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65  readonly(X) inte
25730 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72  rface returns tr
25740 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66  ue (non-zero) if
25750 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20  .** and only if 
25760 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
25770 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73  atement] X makes
25780 20 6e 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67   no direct chang
25790 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e  es to.** the con
257a0 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61  tent of the data
257b0 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a  base file..**.**
257c0 20 4e 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c   Note that [appl
257d0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
257e0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f  SQL functions] o
257f0 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61  r.** [virtual ta
25800 62 6c 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e  bles] might chan
25810 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
25820 69 6e 64 69 72 65 63 74 6c 79 20 61 73 20 61 20  indirectly as a 
25830 73 69 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a  side effect.  .*
25840 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c  * ^(For example,
25850 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   if an applicati
25860 6f 6e 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e  on defines a fun
25870 63 74 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74  ction "eval()" t
25880 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73  hat .** calls [s
25890 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20  qlite3_exec()], 
258a0 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69  then the followi
258b0 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ng SQL statement
258c0 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65   would.** change
258d0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
258e0 6c 65 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d  le through side-
258f0 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c  effects:.**.** <
25900 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
25910 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76  .**    SELECT ev
25920 61 6c 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20  al('DELETE FROM 
25930 74 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a  t1') FROM t2;.**
25940 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
25950 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62  ote>.**.** But b
25960 65 63 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45  ecause the [SELE
25970 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f  CT] statement do
25980 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
25990 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a  e database file.
259a0 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c  ** directly, sql
259b0 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
259c0 6c 79 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c  ly() would still
259d0 20 72 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a   return true.)^.
259e0 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69  **.** ^Transacti
259f0 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65  on control state
25a00 6d 65 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42  ments such as [B
25a10 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c  EGIN], [COMMIT],
25a20 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20   [ROLLBACK],.** 
25a30 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64  [SAVEPOINT], and
25a40 20 5b 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65   [RELEASE] cause
25a50 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
25a60 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75  adonly() to retu
25a70 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63  rn true,.** sinc
25a80 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73  e the statements
25a90 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e   themselves do n
25aa0 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69  ot actually modi
25ab0 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20  fy the database 
25ac0 62 75 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68  but.** rather th
25ad0 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74  ey control the t
25ae0 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74  iming of when ot
25af0 68 65 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d  her statements m
25b00 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61  odify the .** da
25b10 74 61 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41  tabase.  ^The [A
25b20 54 54 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41  TTACH] and [DETA
25b30 43 48 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61  CH] statements a
25b40 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c  lso cause.** sql
25b50 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
25b60 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74  ly() to return t
25b70 72 75 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65  rue since, while
25b80 20 74 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74   those statement
25b90 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20  s.** change the 
25ba0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66  configuration of
25bb0 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
25bc0 65 63 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20  ection, they do 
25bd0 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61  not make .** cha
25be0 6e 67 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74  nges to the cont
25bf0 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62  ent of the datab
25c00 61 73 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73  ase files on dis
25c10 6b 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  k..*/.int sqlite
25c20 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
25c30 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
25c40 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
25c50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
25c60 20 49 66 20 41 20 50 72 65 70 61 72 65 64 20 53   If A Prepared S
25c70 74 61 74 65 6d 65 6e 74 20 48 61 73 20 42 65 65  tatement Has Bee
25c80 6e 20 52 65 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54  n Reset.**.** ^T
25c90 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  he sqlite3_stmt_
25ca0 62 75 73 79 28 53 29 20 69 6e 74 65 72 66 61 63  busy(S) interfac
25cb0 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28  e returns true (
25cc0 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 65  non-zero) if the
25cd0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
25ce0 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 73 20 62  atement] S has b
25cf0 65 65 6e 20 73 74 65 70 70 65 64 20 61 74 20 6c  een stepped at l
25d00 65 61 73 74 20 6f 6e 63 65 20 75 73 69 6e 67 20  east once using 
25d10 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
25d20 70 28 53 29 5d 20 62 75 74 20 68 61 73 20 6e 6f  p(S)] but has no
25d30 74 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74  t run to complet
25d40 69 6f 6e 20 61 6e 64 2f 6f 72 20 68 61 73 20 6e  ion and/or has n
25d50 6f 74 20 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65  ot .** been rese
25d60 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
25d70 5f 72 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68  _reset(S)].  ^Th
25d80 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62  e sqlite3_stmt_b
25d90 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66  usy(S).** interf
25da0 61 63 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73  ace returns fals
25db0 65 20 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c  e if S is a NULL
25dc0 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20   pointer.  If S 
25dd0 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c  is not a .** NUL
25de0 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73  L pointer and is
25df0 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74   not a pointer t
25e00 6f 20 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61  o a valid [prepa
25e10 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
25e20 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74  * object, then t
25e30 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
25e40 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f  ndefined and pro
25e50 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c  bably undesirabl
25e60 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  e..**.** This in
25e70 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
25e80 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69  sed in combinati
25e90 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74  on [sqlite3_next
25ea0 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c  _stmt()].** to l
25eb0 6f 63 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72  ocate all prepar
25ec0 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73  ed statements as
25ed0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
25ee0 64 61 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e  database .** con
25ef0 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65  nection that are
25f00 20 69 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e   in need of bein
25f10 67 20 72 65 73 65 74 2e 20 20 54 68 69 73 20 63  g reset.  This c
25f20 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66  an be used,.** f
25f30 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64  or example, in d
25f40 69 61 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e  iagnostic routin
25f50 65 73 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72  es to search for
25f60 20 70 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74   prepared .** st
25f70 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72  atements that ar
25f80 65 20 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e  e holding a tran
25f90 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f  saction open..*/
25fa0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  .int sqlite3_stm
25fb0 74 5f 62 75 73 79 28 73 71 6c 69 74 65 33 5f 73  t_busy(sqlite3_s
25fc0 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
25fd0 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61  PI3REF: Dynamica
25fe0 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65 20  lly Typed Value 
25ff0 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52  Object.** KEYWOR
26000 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73  DS: {protected s
26010 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75  qlite3_value} {u
26020 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
26030 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20  e3_value}.**.** 
26040 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20  SQLite uses the 
26050 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
26060 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e  ject to represen
26070 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20  t all values.** 
26080 74 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72  that can be stor
26090 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 73 65  ed in a database
260a0 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75   table. SQLite u
260b0 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69  ses dynamic typi
260c0 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61  ng.** for the va
260d0 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20  lues it stores. 
260e0 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20   ^Values stored 
260f0 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  in sqlite3_value
26100 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20   objects.** can 
26110 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f  be integers, flo
26120 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
26130 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f  es, strings, BLO
26140 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a  Bs, or NULL..**.
26150 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61  ** An sqlite3_va
26160 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62  lue object may b
26170 65 20 65 69 74 68 65 72 20 22 70 72 6f 74 65 63  e either "protec
26180 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65  ted" or "unprote
26190 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69  cted"..** Some i
261a0 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72  nterfaces requir
261b0 65 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71  e a protected sq
261c0 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74  lite3_value.  Ot
261d0 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  her interfaces.*
261e0 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69  * will accept ei
261f0 74 68 65 72 20 61 20 70 72 6f 74 65 63 74 65 64  ther a protected
26200 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74   or an unprotect
26210 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
26220 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72  ..** Every inter
26230 66 61 63 65 20 74 68 61 74 20 61 63 63 65 70 74  face that accept
26240 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  s sqlite3_value 
26250 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66  arguments specif
26260 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f  ies.** whether o
26270 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65  r not it require
26280 73 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71  s a protected sq
26290 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a  lite3_value..**.
262a0 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70 72  ** The terms "pr
262b0 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e  otected" and "un
262c0 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65 72  protected" refer
262d0 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e   to whether or n
262e0 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73  ot.** a mutex is
262f0 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72   held.  An inter
26300 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c  nal mutex is hel
26310 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65  d for a protecte
26320 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
26330 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f  ue object but no
26340 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66   mutex is held f
26350 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  or an unprotecte
26360 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
26370 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53  ue object.  If S
26380 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
26390 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74  d to be single-t
263a0 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68  hreaded.** (with
263b0 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
263c0 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20  AFE=0] and with 
263d0 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73  [sqlite3_threads
263e0 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67  afe()] returning
263f0 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c   0).** or if SQL
26400 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e  ite is run in on
26410 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74  e of reduced mut
26420 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51  ex modes .** [SQ
26430 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
26440 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51  LETHREAD] or [SQ
26450 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
26460 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e  ITHREAD].** then
26470 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73   there is no dis
26480 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e  tinction between
26490 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75   protected and u
264a0 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
264b0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
264c0 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e  cts and they can
264d0 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63 68   be used interch
264e0 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76  angeably.  Howev
264f0 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d  er,.** for maxim
26500 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c  um code portabil
26510 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d  ity it is recomm
26520 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69  ended that appli
26530 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c  cations.** still
26540 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e   make the distin
26550 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72  ction between pr
26560 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72  otected and unpr
26570 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
26580 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
26590 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73   even when not s
265a0 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 64  trictly required
265b0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
265c0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
265d0 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73  ts that are pass
265e0 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73  ed as parameters
265f0 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70   into the.** imp
26600 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b  lementation of [
26610 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
26620 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
26630 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 64  s] are protected
26640 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
26650 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72  3_value object r
26660 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
26670 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
26680 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74  lue()] is unprot
26690 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74  ected..** Unprot
266a0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
266b0 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20  lue objects may 
266c0 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74  only be used wit
266d0 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  h.** [sqlite3_re
266e0 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e  sult_value()] an
266f0 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  d [sqlite3_bind_
26700 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65  value()]..** The
26710 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
26720 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76  blob | sqlite3_v
26730 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d  alue_type()] fam
26740 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66  ily of.** interf
26750 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f  aces require pro
26760 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
26770 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f  alue objects..*/
26780 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
26790 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  Mem sqlite3_valu
267a0 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  e;../*.** CAPI3R
267b0 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  EF: SQL Function
267c0 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a   Context Object.
267d0 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78  **.** The contex
267e0 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51  t in which an SQ
267f0 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75  L function execu
26800 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e  tes is stored in
26810 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   an.** sqlite3_c
26820 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20  ontext object.  
26830 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e  ^A pointer to an
26840 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
26850 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c   object.** is al
26860 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61 6d  ways first param
26870 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61  eter to [applica
26880 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
26890 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20   functions]..** 
268a0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  The application-
268b0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
268c0 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
268d0 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68  ion will pass th
268e0 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68  is.** pointer th
268f0 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73  rough into calls
26900 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
26910 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65  ult_int | sqlite
26920 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20  3_result()],.** 
26930 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  [sqlite3_aggrega
26940 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b  te_context()], [
26950 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
26960 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  a()],.** [sqlite
26970 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e  3_context_db_han
26980 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  dle()], [sqlite3
26990 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c  _get_auxdata()],
269a0 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69  .** and/or [sqli
269b0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
269c0 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  )]..*/.typedef s
269d0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f  truct sqlite3_co
269e0 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f  ntext sqlite3_co
269f0 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ntext;../*.** CA
26a00 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20  PI3REF: Binding 
26a10 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72  Values To Prepar
26a20 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  ed Statements.**
26a30 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74   KEYWORDS: {host
26a40 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73   parameter} {hos
26a50 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68  t parameters} {h
26a60 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61  ost parameter na
26a70 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  me}.** KEYWORDS:
26a80 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d   {SQL parameter}
26a90 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   {SQL parameters
26aa0 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e  } {parameter bin
26ab0 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  ding}.**.** ^(In
26ac0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
26ad0 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f  nt text input to
26ae0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
26af0 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20  e_v2()] and its 
26b00 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74  variants,.** lit
26b10 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70  erals may be rep
26b20 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61 72 61  laced by a [para
26b30 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63  meter] that matc
26b40 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f  hes one of follo
26b50 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65  wing.** template
26b60 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
26b70 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e   <li>  ?.** <li>
26b80 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20    ?NNN.** <li>  
26b90 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56  :VVV.** <li>  @V
26ba0 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56  VV.** <li>  $VVV
26bb0 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
26bc0 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73  In the templates
26bd0 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72   above, NNN repr
26be0 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65  esents an intege
26bf0 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e  r literal,.** an
26c00 64 20 56 56 56 20 72 65 70 72 65 73 65 6e 74 73  d VVV represents
26c10 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63   an alphanumeric
26c20 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e 20 20   identifier.)^  
26c30 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74  ^The values of t
26c40 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hese.** paramete
26c50 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20  rs (also called 
26c60 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20  "host parameter 
26c70 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70  names" or "SQL p
26c80 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63  arameters").** c
26c90 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67 20  an be set using 
26ca0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
26cb0 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65  _*() routines de
26cc0 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a  fined here..**.*
26cd0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
26ce0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
26cf0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
26d00 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73  utines is always
26d10 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
26d20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
26d30 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72  mt] object retur
26d40 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c  ned from.** [sql
26d50 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
26d60 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
26d70 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ts..**.** ^The s
26d80 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
26d90 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
26da0 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  he SQL parameter
26db0 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e   to be set..** ^
26dc0 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c  The leftmost SQL
26dd0 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61   parameter has a
26de0 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e  n index of 1.  ^
26df0 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61  When the same na
26e00 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d  med.** SQL param
26e10 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72  eter is used mor
26e20 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63  e than once, sec
26e30 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65  ond and subseque
26e40 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65  nt.** occurrence
26e50 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65 20  s have the same 
26e60 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69 72  index as the fir
26e70 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a  st occurrence..*
26e80 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72  * ^The index for
26e90 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72   named parameter
26ea0 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20  s can be looked 
26eb0 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  up using the.** 
26ec0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
26ed0 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
26ee0 20 41 50 49 20 69 66 20 64 65 73 69 72 65 64 2e   API if desired.
26ef0 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20    ^The index.** 
26f00 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d  for "?NNN" param
26f10 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61 6c  eters is the val
26f20 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54  ue of NNN..** ^T
26f30 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73  he NNN value mus
26f40 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20 61  t be between 1 a
26f50 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  nd the [sqlite3_
26f60 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61  limit()].** para
26f70 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49  meter [SQLITE_LI
26f80 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
26f90 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61  BER] (default va
26fa0 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a  lue: 999)..**.**
26fb0 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75   ^The third argu
26fc0 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75  ment is the valu
26fd0 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65  e to bind to the
26fe0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
26ff0 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75  * ^(In those rou
27000 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 20  tines that have 
27010 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  a fourth argumen
27020 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 20  t, its value is 
27030 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
27040 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 70 61   bytes in the pa
27050 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20  rameter.  To be 
27060 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65  clear: the value
27070 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   is the.** numbe
27080 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75  r of <u>bytes</u
27090 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20  > in the value, 
270a0 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  not the number o
270b0 66 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a  f characters.)^.
270c0 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74  ** ^If the fourt
270d0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
270e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
270f0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  () or sqlite3_bi
27100 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 69  nd_text16().** i
27110 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
27120 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74   the length of t
27130 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20  he string is.** 
27140 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
27150 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69  tes up to the fi
27160 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  rst zero termina
27170 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66  tor..** If the f
27180 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
27190 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
271a0 62 6c 6f 62 28 29 20 69 73 20 6e 65 67 61 74 69  blob() is negati
271b0 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ve, then.** the 
271c0 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
271d0 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e  fined..** If a n
271e0 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72  on-negative four
271f0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
27200 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69  provided to sqli
27210 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a  te3_bind_text().
27220 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  ** or sqlite3_bi
27230 6e 64 5f 74 65 78 74 31 36 28 29 20 74 68 65 6e  nd_text16() then
27240 20 74 68 61 74 20 70 61 72 61 6d 65 74 65 72 20   that parameter 
27250 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74 65  must be the byte
27260 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65   offset.** where
27270 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61   the NUL termina
27280 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20  tor would occur 
27290 61 73 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72  assuming the str
272a0 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20  ing were NUL.** 
272b0 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20  terminated.  If 
272c0 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65  any NUL characte
272d0 72 73 20 6f 63 63 75 72 20 61 74 20 62 79 74 65  rs occur at byte
272e0 20 6f 66 66 73 65 74 73 20 6c 65 73 73 20 74 68   offsets less th
272f0 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65  an .** the value
27300 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   of the fourth p
27310 61 72 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68  arameter then th
27320 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69  e resulting stri
27330 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a  ng value will.**
27340 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65   contain embedde
27350 64 20 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73  d NULs.  The res
27360 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f  ult of expressio
27370 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72  ns involving str
27380 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62  ings.** with emb
27390 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e  edded NULs is un
273a0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
273b0 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  The fifth argume
273c0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  nt to sqlite3_bi
273d0 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74  nd_blob(), sqlit
273e0 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20  e3_bind_text(), 
273f0 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62  and.** sqlite3_b
27400 69 6e 64 5f 74 65 78 74 31 36 28 29 20 69 73 20  ind_text16() is 
27410 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 65  a destructor use
27420 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20  d to dispose of 
27430 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73  the BLOB or.** s
27440 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69  tring after SQLi
27450 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  te has finished 
27460 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64  with it.  ^The d
27470 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c  estructor is cal
27480 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73  led.** to dispos
27490 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72  e of the BLOB or
274a0 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20   string even if 
274b0 74 68 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  the call to sqli
274c0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c  te3_bind_blob(),
274d0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  .** sqlite3_bind
274e0 5f 74 65 78 74 28 29 2c 20 6f 72 20 73 71 6c 69  _text(), or sqli
274f0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
27500 29 20 66 61 69 6c 73 2e 20 20 0a 2a 2a 20 5e 49  ) fails.  .** ^I
27510 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75  f the fifth argu
27520 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73  ment is.** the s
27530 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51  pecial value [SQ
27540 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68  LITE_STATIC], th
27550 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65  en SQLite assume
27560 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e  s that the.** in
27570 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20  formation is in 
27580 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65  static, unmanage
27590 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73  d space and does
275a0 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
275b0 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68  freed..** ^If th
275c0 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
275d0 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b   has the value [
275e0 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
275f0 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74  ], then.** SQLit
27600 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20  e makes its own 
27610 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
27620 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61  the data immedia
27630 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20  tely, before.** 
27640 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
27650 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  _*() routine ret
27660 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  urns..**.** ^The
27670 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
27680 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65  roblob() routine
27690 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66   binds a BLOB of
276a0 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a   length N that.*
276b0 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  * is filled with
276c0 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72   zeroes.  ^A zer
276d0 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78  oblob uses a fix
276e0 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d  ed amount of mem
276f0 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20  ory.** (just an 
27700 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20  integer to hold 
27710 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20  its size) while 
27720 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63  it is being proc
27730 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c  essed..** Zerobl
27740 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  obs are intended
27750 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61   to serve as pla
27760 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c  ceholders for BL
27770 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e  OBs whose.** con
27780 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72  tent is later wr
27790 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  itten using.** [
277a0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
277b0 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20  n | incremental 
277c0 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e  BLOB I/O] routin
277d0 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69  es..** ^A negati
277e0 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65  ve value for the
277f0 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74   zeroblob result
27800 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67  s in a zero-leng
27810 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e  th BLOB..**.** ^
27820 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71  If any of the sq
27830 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
27840 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
27850 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70  ed with a NULL p
27860 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68  ointer.** for th
27870 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
27880 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61  ement] or with a
27890 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
278a0 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a  ent for which.**
278b0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
278c0 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65  ] has been calle
278d0 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20  d more recently 
278e0 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  than [sqlite3_re
278f0 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20  set()],.** then 
27900 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65  the call will re
27910 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  turn [SQLITE_MIS
27920 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71  USE].  If any sq
27930 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a  lite3_bind_().**
27940 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73   routine is pass
27950 65 64 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  ed a [prepared s
27960 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68  tatement] that h
27970 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  as been finalize
27980 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  d, the.** result
27990 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
279a0 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66  d probably harmf
279b0 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69  ul..**.** ^Bindi
279c0 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61  ngs are not clea
279d0 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  red by the [sqli
279e0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75  te3_reset()] rou
279f0 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e  tine..** ^Unboun
27a00 64 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  d parameters are
27a10 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
27a20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  NULL..**.** ^The
27a30 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20   sqlite3_bind_* 
27a40 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
27a50 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
27a60 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20  uccess or an.** 
27a70 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20  [error code] if 
27a80 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72  anything goes wr
27a90 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ong..** ^[SQLITE
27aa0 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72  _RANGE] is retur
27ab0 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d  ned if the param
27ac0 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73  eter.** index is
27ad0 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20   out of range.  
27ae0 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20  ^[SQLITE_NOMEM] 
27af0 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d  is returned if m
27b00 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a  alloc() fails..*
27b10 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
27b20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
27b30 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
27b40 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
27b50 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
27b60 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
27b70 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
27b80 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e  _index()]..*/.in
27b90 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  t sqlite3_bind_b
27ba0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
27bb0 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
27bc0 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64  id*, int n, void
27bd0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
27be0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f   sqlite3_bind_do
27bf0 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
27c00 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29  t*, int, double)
27c10 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
27c20 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  nd_int(sqlite3_s
27c30 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b  tmt*, int, int);
27c40 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
27c50 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  d_int64(sqlite3_
27c60 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69  stmt*, int, sqli
27c70 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20  te3_int64);.int 
27c80 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c  sqlite3_bind_nul
27c90 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  l(sqlite3_stmt*,
27ca0 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74   int);.int sqlit
27cb0 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c  e3_bind_text(sql
27cc0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
27cd0 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
27ce0 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  t n, void(*)(voi
27cf0 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
27d00 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71  3_bind_text16(sq
27d10 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
27d20 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
27d30 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
27d40 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
27d50 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69  _bind_value(sqli
27d60 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
27d70 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61  const sqlite3_va
27d80 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
27d90 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
27da0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
27db0 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a  int, int n);../*
27dc0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
27dd0 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61  mber Of SQL Para
27de0 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  meters.**.** ^Th
27df0 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62  is routine can b
27e00 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74  e used to find t
27e10 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51  he number of [SQ
27e20 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a  L parameters].**
27e30 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   in a [prepared 
27e40 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c  statement].  SQL
27e50 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
27e60 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a  tokens of the.**
27e70 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e   form "?", "?NNN
27e80 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41  ", ":AAA", "$AAA
27e90 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61  ", or "@AAA" tha
27ea0 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c  t serve as.** pl
27eb0 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76  aceholders for v
27ec0 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b  alues that are [
27ed0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
27ee0 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f  b | bound].** to
27ef0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20   the parameters 
27f00 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e  at a later time.
27f10 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f  .**.** ^(This ro
27f20 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72  utine actually r
27f30 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78  eturns the index
27f40 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20   of the largest 
27f50 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70  (rightmost).** p
27f60 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c  arameter. For al
27f70 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f  l forms except ?
27f80 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63  NNN, this will c
27f90 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65  orrespond to the
27fa0 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e  .** number of un
27fb0 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e  ique parameters.
27fc0 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20    If parameters 
27fd0 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d  of the ?NNN form
27fe0 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68   are used,.** th
27ff0 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20  ere may be gaps 
28000 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a  in the list.)^.*
28010 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
28020 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
28030 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
28040 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
28050 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
28060 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  me()], and.** [s
28070 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
28080 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
28090 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
280a0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
280b0 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
280c0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
280d0 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48  REF: Name Of A H
280e0 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a  ost Parameter.**
280f0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
28100 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
28110 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66  name(P,N) interf
28120 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  ace returns.** t
28130 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e  he name of the N
28140 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74  -th [SQL paramet
28150 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70  er] in the [prep
28160 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
28170 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61  P..** ^(SQL para
28180 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f  meters of the fo
28190 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41  rm "?NNN" or ":A
281a0 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72  AA" or "@AAA" or
281b0 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20   "$AAA".** have 
281c0 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20  a name which is 
281d0 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e  the string "?NNN
281e0 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22  " or ":AAA" or "
281f0 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a  @AAA" or "$AAA".
28200 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  ** respectively.
28210 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
28220 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20  ds, the initial 
28230 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40  ":" or "$" or "@
28240 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69  " or "?".** is i
28250 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20  ncluded as part 
28260 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a  of the name.)^.*
28270 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66  * ^Parameters of
28280 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69   the form "?" wi
28290 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e  thout a followin
282a0 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e  g integer have n
282b0 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72  o name.** and ar
282c0 65 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73  e referred to as
282d0 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22   "nameless" or "
282e0 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65  anonymous parame
282f0 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ters"..**.** ^Th
28300 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72  e first host par
28310 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
28320 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e  dex of 1, not 0.
28330 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76  .**.** ^If the v
28340 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66  alue N is out of
28350 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65   range or if the
28360 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20   N-th parameter 
28370 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20  is.** nameless, 
28380 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74  then NULL is ret
28390 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74  urned.  ^The ret
283a0 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a  urned string is.
283b0 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46  ** always in UTF
283c0 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e  -8 encoding even
283d0 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61   if the named pa
283e0 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f  rameter was.** o
283f0 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66  riginally specif
28400 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  ied as UTF-16 in
28410 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
28420 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  e16()] or.** [sq
28430 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
28440 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  v2()]..**.** See
28450 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
28460 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
28470 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
28480 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
28490 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20  meter_count()], 
284a0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
284b0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
284c0 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73  ndex()]..*/.cons
284d0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
284e0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
284f0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
28500 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *, int);../*.** 
28510 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20  CAPI3REF: Index 
28520 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57  Of A Parameter W
28530 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65  ith A Given Name
28540 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74  .**.** ^Return t
28550 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53  he index of an S
28560 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76  QL parameter giv
28570 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54  en its name.  ^T
28580 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75  he.** index valu
28590 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75  e returned is su
285a0 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61  itable for use a
285b0 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  s the second.** 
285c0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
285d0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
285e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e  sqlite3_bind()].
285f0 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20    ^A zero.** is 
28600 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d  returned if no m
28610 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65  atching paramete
28620 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68  r is found.  ^Th
28630 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e  e parameter.** n
28640 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65  ame must be give
28650 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20  n in UTF-8 even 
28660 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  if the original 
28670 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73  statement.** was
28680 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55   prepared from U
28690 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67  TF-16 text using
286a0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
286b0 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
286c0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
286d0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
286e0 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
286f0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
28700 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
28710 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
28720 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
28730 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
28740 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
28750 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
28760 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
28770 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
28780 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  e);../*.** CAPI3
28790 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42  REF: Reset All B
287a0 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65  indings On A Pre
287b0 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a  pared Statement.
287c0 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20  **.** ^Contrary 
287d0 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e  to the intuition
287e0 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74   of many, [sqlit
287f0 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73  e3_reset()] does
28800 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68   not reset.** th
28810 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
28820 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d  blob | bindings]
28830 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   on a [prepared 
28840 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
28850 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  Use this routine
28860 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f   to reset all ho
28870 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  st parameters to
28880 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71   NULL..*/.int sq
28890 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64  lite3_clear_bind
288a0 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ings(sqlite3_stm
288b0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
288c0 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20  3REF: Number Of 
288d0 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73  Columns In A Res
288e0 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52  ult Set.**.** ^R
288f0 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72  eturn the number
28900 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
28910 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65  he result set re
28920 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a  turned by the.**
28930 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
28940 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75  ment]. ^This rou
28950 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69  tine returns 0 i
28960 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51  f pStmt is an SQ
28970 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74  L.** statement t
28980 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74  hat does not ret
28990 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78  urn data (for ex
289a0 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45  ample an [UPDATE
289b0 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ])..**.** See al
289c0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74  so: [sqlite3_dat
289d0 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e  a_count()].*/.in
289e0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
289f0 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
28a00 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
28a10 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
28a20 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20  lumn Names In A 
28a30 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a  Result Set.**.**
28a40 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
28a50 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65   return the name
28a60 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70   assigned to a p
28a70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e  articular column
28a80 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c  .** in the resul
28a90 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45  t set of a [SELE
28aa0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  CT] statement.  
28ab0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ^The sqlite3_col
28ac0 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e  umn_name().** in
28ad0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
28ae0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a  a pointer to a z
28af0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
28b00 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61  TF-8 string.** a
28b10 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
28b20 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72  n_name16() retur
28b30 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
28b40 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
28b50 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69  d.** UTF-16 stri
28b60 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20  ng.  ^The first 
28b70 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
28b80 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
28b90 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d  ment].** that im
28ba0 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45  plements the [SE
28bb0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
28bc0 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
28bd0 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
28be0 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20   column number. 
28bf0 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63   ^The leftmost c
28c00 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20  olumn is number 
28c10 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65  0..**.** ^The re
28c20 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f  turned string po
28c30 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75  inter is valid u
28c40 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20  ntil either the 
28c50 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
28c60 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72  ent].** is destr
28c70 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  oyed by [sqlite3
28c80 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
28c90 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d  until the statem
28ca0 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ent is automatic
28cb0 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72  ally.** reprepar
28cc0 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
28cd0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
28ce0 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70  _step()] for a p
28cf0 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a  articular run.**
28d00 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65   or until the ne
28d10 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71  xt call to.** sq
28d20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
28d30 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  e() or sqlite3_c
28d40 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f  olumn_name16() o
28d50 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d  n the same colum
28d60 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c  n..**.** ^If sql
28d70 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61  ite3_malloc() fa
28d80 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70  ils during the p
28d90 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74  rocessing of eit
28da0 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28  her routine.** (
28db0 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69  for example duri
28dc0 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ng a conversion 
28dd0 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54  from UTF-8 to UT
28de0 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20  F-16) then a.** 
28df0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
28e00 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
28e10 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72  ^The name of a r
28e20 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20  esult column is 
28e30 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
28e40 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72   "AS" clause for
28e50 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c  .** that column,
28e60 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20   if there is an 
28e70 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74  AS clause.  If t
28e80 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c  here is no AS cl
28e90 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ause.** then the
28ea0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c   name of the col
28eb0 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69  umn is unspecifi
28ec0 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67  ed and may chang
28ed0 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65  e from.** one re
28ee0 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20  lease of SQLite 
28ef0 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a  to the next..*/.
28f00 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
28f10 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
28f20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
28f30 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  nt N);.const voi
28f40 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
28f50 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
28f60 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  _stmt*, int N);.
28f70 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
28f80 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20   Source Of Data 
28f90 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  In A Query Resul
28fa0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  t.**.** ^These r
28fb0 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20  outines provide 
28fc0 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72  a means to deter
28fd0 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62 61 73  mine the databas
28fe0 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a  e, table, and.**
28ff0 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
29000 61 74 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e  at is the origin
29010 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61 72   of a particular
29020 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69   result column i
29030 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74  n.** [SELECT] st
29040 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  atement..** ^The
29050 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
29060 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f  abase or table o
29070 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20  r column can be 
29080 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65  returned as.** e
29090 69 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72  ither a UTF-8 or
290a0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20   UTF-16 string. 
290b0 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f   ^The _database_
290c0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
290d0 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
290e0 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c   name, the _tabl
290f0 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  e_ routines retu
29100 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d  rn the table nam
29110 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72  e, and.** the or
29120 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72  igin_ routines r
29130 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e  eturn the column
29140 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72   name..** ^The r
29150 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
29160 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68  s valid until th
29170 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
29180 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f  ement] is destro
29190 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71  yed.** using [sq
291a0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
291b0 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  ] or until the s
291c0 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f  tatement is auto
291d0 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70  matically.** rep
291e0 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66  repared by the f
291f0 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  irst call to [sq
29200 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f  lite3_step()] fo
29210 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  r a particular r
29220 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74  un.** or until t
29230 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74  he same informat
29240 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64  ion is requested
29250 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64  .** again in a d
29260 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e  ifferent encodin
29270 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61  g..**.** ^The na
29280 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65  mes returned are
29290 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e   the original un
292a0 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f  -aliased names o
292b0 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  f the.** databas
292c0 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f  e, table, and co
292d0 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lumn..**.** ^The
292e0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
292f0 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  to these interfa
29300 63 65 73 20 69 73 20 61 20 5b 70 72 65 70 61 72  ces is a [prepar
29310 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
29320 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f  * ^These functio
29330 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  ns return inform
29340 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20  ation about the 
29350 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  Nth result colum
29360 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  n returned by.**
29370 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20   the statement, 
29380 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73  where N is the s
29390 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61  econd function a
293a0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  rgument..** ^The
293b0 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d   left-most colum
293c0 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f  n is column 0 fo
293d0 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  r these routines
293e0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
293f0 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  Nth column retur
29400 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65  ned by the state
29410 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65  ment is an expre
29420 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71  ssion or.** subq
29430 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20  uery and is not 
29440 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20  a column value, 
29450 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73  then all of thes
29460 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
29470 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68  rn.** NULL.  ^Th
29480 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68  ese routine migh
29490 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55  t also return NU
294a0 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61  LL if a memory a
294b0 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a  llocation error.
294c0 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68  ** occurs.  ^Oth
294d0 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74  erwise, they ret
294e0 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  urn the name of 
294f0 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74  the attached dat
29500 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a  abase, table,.**
29510 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20   or column that 
29520 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c  query result col
29530 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65  umn was extracte
29540 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41  d from..**.** ^A
29550 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72  s with all other
29560 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68   SQLite APIs, th
29570 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20  ose whose names 
29580 65 6e 64 20 77 69 74 68 20 22 31 36 22 20 72 65  end with "16" re
29590 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65  turn.** UTF-16 e
295a0 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61  ncoded strings a
295b0 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e  nd the other fun
295c0 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54  ctions return UT
295d0 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  F-8..**.** ^Thes
295e0 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20  e APIs are only 
295f0 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65  available if the
29600 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d   library was com
29610 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
29620 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
29630 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41  _COLUMN_METADATA
29640 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C-preprocessor
29650 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49   symbol..**.** I
29660 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68  f two or more th
29670 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f  reads call one o
29680 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20  r more of these 
29690 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74  routines against
296a0 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65   the same.** pre
296b0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
296c0 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68  and column at th
296d0 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e  e same time then
296e0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
296f0 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  .** undefined..*
29700 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d  *.** If two or m
29710 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c  ore threads call
29720 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
29730 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
29740 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20  database_name | 
29750 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20  column metadata 
29760 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66  interfaces].** f
29770 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65  or the same [pre
29780 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
29790 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75   and result colu
297a0 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d  mn.** at the sam
297b0 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20  e time then the 
297c0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
297d0 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  fined..*/.const 
297e0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
297f0 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
29800 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
29810 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
29820 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
29830 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31  n_database_name1
29840 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
29850 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  int);.const char
29860 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
29870 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69  _table_name(sqli
29880 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
29890 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
298a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65  te3_column_table
298b0 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
298c0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
298d0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
298e0 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
298f0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
29900 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
29910 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
29920 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28  n_origin_name16(
29930 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
29940 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
29950 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61  REF: Declared Da
29960 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72  tatype Of A Quer
29970 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e  y Result.**.** ^
29980 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  (The first param
29990 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61  eter is a [prepa
299a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
299b0 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65  ** If this state
299c0 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43  ment is a [SELEC
299d0 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  T] statement and
299e0 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
299f0 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e  of the.** return
29a00 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  ed result set of
29a10 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69   that [SELECT] i
29a20 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  s a table column
29a30 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72   (not an.** expr
29a40 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65  ession or subque
29a50 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63  ry) then the dec
29a60 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68  lared type of th
29a70 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d  e table.** colum
29a80 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  n is returned.)^
29a90 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f    ^If the Nth co
29aa0 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75  lumn of the resu
29ab0 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20  lt set is an.** 
29ac0 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
29ad0 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e  bquery, then a N
29ae0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
29af0 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65  eturned..** ^The
29b00 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
29b10 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38   is always UTF-8
29b20 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20   encoded..**.** 
29b30 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67  ^(For example, g
29b40 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  iven the databas
29b50 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20  e schema:.**.** 
29b60 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28  CREATE TABLE t1(
29b70 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a  c1 VARIANT);.**.
29b80 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f  ** and the follo
29b90 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74  wing statement t
29ba0 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a  o be compiled:.*
29bb0 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b  *.** SELECT c1 +
29bc0 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a   1, c1 FROM t1;.
29bd0 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69  **.** this routi
29be0 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20  ne would return 
29bf0 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49  the string "VARI
29c00 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63  ANT" for the sec
29c10 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f  ond result.** co
29c20 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64  lumn (i==1), and
29c30 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
29c40 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65  for the first re
29c50 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d  sult column (i==
29c60 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  0).)^.**.** ^SQL
29c70 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
29c80 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67   run-time typing
29c90 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61  .  ^So just beca
29ca0 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  use a column.** 
29cb0 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63  is declared to c
29cc0 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75  ontain a particu
29cd0 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f  lar type does no
29ce0 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a  t mean that the.
29cf0 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69  ** data stored i
29d00 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73  n that column is
29d10 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64   of the declared
29d20 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69   type.  SQLite i
29d30 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79  s.** strongly ty
29d40 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70  ped, but the typ
29d50 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e  ing is dynamic n
29d60 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70  ot static.  ^Typ
29d70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74  e.** is associat
29d80 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75  ed with individu
29d90 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77  al values, not w
29da0 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65  ith the containe
29db0 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f  rs.** used to ho
29dc0 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e  ld those values.
29dd0 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
29de0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
29df0 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ecltype(sqlite3_
29e00 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
29e10 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
29e20 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31  column_decltype1
29e30 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
29e40 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
29e50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20  I3REF: Evaluate 
29e60 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
29e70 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b  .**.** After a [
29e80 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
29e90 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65  nt] has been pre
29ea0 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68  pared using eith
29eb0 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  er.** [sqlite3_p
29ec0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
29ed0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
29ee0 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20  16_v2()] or one 
29ef0 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  of the legacy.**
29f00 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c   interfaces [sql
29f10 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
29f20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
29f30 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66  are16()], this f
29f40 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20  unction.** must 
29f50 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72  be called one or
29f60 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65   more times to e
29f70 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74  valuate the stat
29f80 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ement..**.** The
29f90 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20   details of the 
29fa0 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20  behavior of the 
29fb0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
29fc0 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a  nterface depend.
29fd0 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68  ** on whether th
29fe0 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20  e statement was 
29ff0 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74  prepared using t
2a000 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e  he newer "v2" in
2a010 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69  terface.** [sqli
2a020 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2a030 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
2a040 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
2a050 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61  r the older lega
2a060 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  cy.** interface 
2a070 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2a080 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2a090 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20  _prepare16()].  
2a0a0 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a  The use of the.*
2a0b0 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72  * new "v2" inter
2a0c0 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e  face is recommen
2a0d0 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c  ded for new appl
2a0e0 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65  ications but the
2a0f0 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
2a100 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e  face will contin
2a110 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ue to be support
2a120 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68  ed..**.** ^In th
2a130 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
2a140 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76  ce, the return v
2a150 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74  alue will be eit
2a160 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  her [SQLITE_BUSY
2a170 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f  ],.** [SQLITE_DO
2a180 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57  NE], [SQLITE_ROW
2a190 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ], [SQLITE_ERROR
2a1a0 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49  ], or [SQLITE_MI
2a1b0 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20  SUSE]..** ^With 
2a1c0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
2a1d0 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f  ce, any of the o
2a1e0 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64  ther [result cod
2a1f0 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e  es] or.** [exten
2a200 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
2a210 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72  ] might be retur
2a220 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a  ned as well..**.
2a230 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59  ** ^[SQLITE_BUSY
2a240 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
2a250 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65   database engine
2a260 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61   was unable to a
2a270 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61  cquire the.** da
2a280 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20  tabase locks it 
2a290 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20  needs to do its 
2a2a0 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74  job.  ^If the st
2a2b0 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f  atement is a [CO
2a2c0 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75  MMIT].** or occu
2a2d0 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e  rs outside of an
2a2e0 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
2a2f0 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20  ction, then you 
2a300 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a  can retry the.**
2a310 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20   statement.  If 
2a320 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
2a330 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20   not a [COMMIT] 
2a340 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69  and occurs withi
2a350 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74  n an.** explicit
2a360 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65   transaction the
2a370 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c  n you should rol
2a380 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61  lback the transa
2a390 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20  ction before.** 
2a3a0 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a  continuing..**.*
2a3b0 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  * ^[SQLITE_DONE]
2a3c0 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
2a3d0 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69  statement has fi
2a3e0 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67  nished executing
2a3f0 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79  .** successfully
2a400 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
2a410 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
2a420 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20  called again on 
2a430 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20  this virtual.** 
2a440 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20  machine without 
2a450 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73  first calling [s
2a460 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2a470 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72  to reset the vir
2a480 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20  tual.** machine 
2a490 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
2a4a0 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  ial state..**.**
2a4b0 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61   ^If the SQL sta
2a4c0 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65  tement being exe
2a4d0 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e  cuted returns an
2a4e0 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51  y data, then [SQ
2a4f0 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20  LITE_ROW].** is 
2a500 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69  returned each ti
2a510 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20  me a new row of 
2a520 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f  data is ready fo
2a530 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20  r processing by 
2a540 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54  the.** caller. T
2a550 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65  he values may be
2a560 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20   accessed using 
2a570 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65  the [column acce
2a580 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a  ss functions]..*
2a590 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
2a5a0 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   is called again
2a5b0 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65   to retrieve the
2a5c0 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74   next row of dat
2a5d0 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  a..**.** ^[SQLIT
2a5e0 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74  E_ERROR] means t
2a5f0 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65  hat a run-time e
2a600 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20  rror (such as a 
2a610 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69  constraint.** vi
2a620 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63  olation) has occ
2a630 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f  urred.  sqlite3_
2a640 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
2a650 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
2a660 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20  n on.** the VM. 
2a670 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  More information
2a680 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79   may be found by
2a690 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
2a6a0 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20  3_errmsg()]..** 
2a6b0 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79  ^With the legacy
2a6c0 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f   interface, a mo
2a6d0 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f  re specific erro
2a6e0 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d  r code (for exam
2a6f0 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ple,.** [SQLITE_
2a700 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c  INTERRUPT], [SQL
2a710 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51  ITE_SCHEMA], [SQ
2a720 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61  LITE_CORRUPT], a
2a730 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20  nd so forth).** 
2a740 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20  can be obtained 
2a750 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
2a760 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20  te3_reset()] on 
2a770 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
2a780 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49   statement].  ^I
2a790 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  n the "v2" inter
2a7a0 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72  face,.** the mor
2a7b0 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
2a7c0 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65   code is returne
2a7d0 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71  d directly by sq
2a7e0 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a  lite3_step()..**
2a7f0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  .** [SQLITE_MISU
2a800 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  SE] means that t
2a810 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  he this routine 
2a820 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70  was called inapp
2a830 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50  ropriately..** P
2a840 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61  erhaps it was ca
2a850 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61  lled on a [prepa
2a860 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
2a870 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61  hat has.** alrea
2a880 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33  dy been [sqlite3
2a890 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61  _finalize | fina
2a8a0 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65  lized] or on one
2a8b0 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65   that had.** pre
2a8c0 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64  viously returned
2a8d0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
2a8e0 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  or [SQLITE_DONE]
2a8f0 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a  .  Or it could.*
2a900 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68  * be the case th
2a910 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  at the same data
2a920 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2a930 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79  is being used by
2a940 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20   two or.** more 
2a950 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73  threads at the s
2a960 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69  ame moment in ti
2a970 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c  me..**.** For al
2a980 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  l versions of SQ
2a990 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69  Lite up to and i
2a9a0 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e  ncluding 3.6.23.
2a9b0 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  1, a call to.** 
2a9c0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2a9d0 5d 20 77 61 73 20 72 65 71 75 69 72 65 64 20 61  ] was required a
2a9e0 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65  fter sqlite3_ste
2a9f0 70 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79  p() returned any
2aa00 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74  thing.** other t
2aa10 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  han [SQLITE_ROW]
2aa20 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73   before any subs
2aa30 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f  equent invocatio
2aa40 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  n of.** sqlite3_
2aa50 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65  step().  Failure
2aa60 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 70 72   to reset the pr
2aa70 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2aa80 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69   using .** [sqli
2aa90 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75  te3_reset()] wou
2aaa0 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20  ld result in an 
2aab0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
2aac0 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73  return from.** s
2aad0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
2aae0 42 75 74 20 61 66 74 65 72 20 76 65 72 73 69 6f  But after versio
2aaf0 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69  n 3.6.23.1, sqli
2ab00 74 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e  te3_step() began
2ab10 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  .** calling [sql
2ab20 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75  ite3_reset()] au
2ab30 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74  tomatically in t
2ab40 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65  his circumstance
2ab50 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20   rather.** than 
2ab60 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54  returning [SQLIT
2ab70 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73  E_MISUSE].  This
2ab80 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72   is not consider
2ab90 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69  ed a compatibili
2aba0 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61  ty.** break beca
2abb0 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74  use any applicat
2abc0 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 65  ion that ever re
2abd0 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45  ceives an SQLITE
2abe0 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a  _MISUSE error.**
2abf0 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65   is broken by de
2ac00 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b  finition.  The [
2ac10 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f  SQLITE_OMIT_AUTO
2ac20 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74  RESET] compile-t
2ac30 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61  ime option.** ca
2ac40 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 73  n be used to res
2ac50 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 20  tore the legacy 
2ac60 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20  behavior..**.** 
2ac70 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61  <b>Goofy Interfa
2ac80 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e  ce Alert:</b> In
2ac90 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
2aca0 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74  rface, the sqlit
2acb0 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49  e3_step().** API
2acc0 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
2acd0 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20  a generic error 
2ace0 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52  code, [SQLITE_ER
2acf0 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20  ROR], following 
2ad00 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68  any.** error oth
2ad10 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
2ad20 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54  BUSY] and [SQLIT
2ad30 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20  E_MISUSE].  You 
2ad40 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71  must call.** [sq
2ad50 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
2ad60 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
2ad70 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20  ize()] in order 
2ad80 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74  to find one of t
2ad90 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b  he.** specific [
2ada0 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61  error codes] tha
2adb0 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62  t better describ
2adc0 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a  es the error..**
2add0 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74   We admit that t
2ade0 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64  his is a goofy d
2adf0 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62  esign.  The prob
2ae00 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78  lem has been fix
2ae10 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22  ed.** with the "
2ae20 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20  v2" interface.  
2ae30 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61  If you prepare a
2ae40 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73  ll of your SQL s
2ae50 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69  tatements.** usi
2ae60 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  ng either [sqlit
2ae70 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2ae80 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
2ae90 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73  pare16_v2()] ins
2aea0 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c  tead.** of the l
2aeb0 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70  egacy [sqlite3_p
2aec0 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73  repare()] and [s
2aed0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2aee0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a  ()] interfaces,.
2aef0 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65  ** then the more
2af00 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72   specific [error
2af10 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75   codes] are retu
2af20 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a  rned directly.**
2af30 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70   by sqlite3_step
2af40 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20  ().  The use of 
2af50 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
2af60 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ce is recommende
2af70 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
2af80 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73  3_step(sqlite3_s
2af90 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
2afa0 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f  PI3REF: Number o
2afb0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72  f columns in a r
2afc0 65 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20  esult set.**.** 
2afd0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
2afe0 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72  a_count(P) inter
2aff0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
2b000 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
2b010 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72  ns in the.** cur
2b020 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20  rent row of the 
2b030 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70  result set of [p
2b040 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2b050 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65  t] P..** ^If pre
2b060 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2b070 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  P does not have 
2b080 72 65 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f  results ready to
2b090 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20   return.** (via 
2b0a0 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71  calls to the [sq
2b0b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
2b0c0 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d   | sqlite3_colum
2b0d0 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74  n_*()] of.** int
2b0e0 65 72 66 61 63 65 73 29 20 74 68 65 6e 20 73 71  erfaces) then sq
2b0f0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2b100 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a  (P) returns 0..*
2b110 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
2b120 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75  ata_count(P) rou
2b130 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e  tine also return
2b140 73 20 30 20 69 66 20 50 20 69 73 20 61 20 4e 55  s 0 if P is a NU
2b150 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e  LL pointer..** ^
2b160 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
2b170 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e  _count(P) routin
2b180 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 74  e returns 0 if t
2b190 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  he previous call
2b1a0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
2b1b0 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65  step](P) returne
2b1c0 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  d [SQLITE_DONE].
2b1d0 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64    ^The sqlite3_d
2b1e0 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20  ata_count(P).** 
2b1f0 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d  will return non-
2b200 7a 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73  zero if previous
2b210 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2b220 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72  3_step](P) retur
2b230 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52  ned.** [SQLITE_R
2b240 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74  OW], except in t
2b250 68 65 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b  he case of the [
2b260 50 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74  PRAGMA increment
2b270 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68  al_vacuum].** wh
2b280 65 72 65 20 69 74 20 61 6c 77 61 79 73 20 72 65  ere it always re
2b290 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65  turns zero since
2b2a0 20 65 61 63 68 20 73 74 65 70 20 6f 66 20 74 68   each step of th
2b2b0 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a  at multi-step.**
2b2c0 20 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20   pragma returns 
2b2d0 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74  0 columns of dat
2b2e0 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  a..**.** See als
2b2f0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  o: [sqlite3_colu
2b300 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69  mn_count()].*/.i
2b310 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  nt sqlite3_data_
2b320 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
2b330 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
2b340 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e  ** CAPI3REF: Fun
2b350 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70  damental Datatyp
2b360 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
2b370 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a  SQLITE_TEXT.**.*
2b380 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20  * ^(Every value 
2b390 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e  in SQLite has on
2b3a0 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d  e of five fundam
2b3b0 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a  ental datatypes:
2b3c0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
2b3d0 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65  li> 64-bit signe
2b3e0 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69  d integer.** <li
2b3f0 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c  > 64-bit IEEE fl
2b400 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d  oating point num
2b410 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69  ber.** <li> stri
2b420 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a  ng.** <li> BLOB.
2b430 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20  ** <li> NULL.** 
2b440 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  </ul>)^.**.** Th
2b450 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
2b460 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68  e codes for each
2b470 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e   of those types.
2b480 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
2b490 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54   the SQLITE_TEXT
2b4a0 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c   constant was al
2b4b0 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74  so used in SQLit
2b4c0 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66  e version 2.** f
2b4d0 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20  or a completely 
2b4e0 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e  different meanin
2b4f0 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61  g.  Software tha
2b500 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20  t links against 
2b510 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76  both.** SQLite v
2b520 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c  ersion 2 and SQL
2b530 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68  ite version 3 sh
2b540 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33  ould use SQLITE3
2b550 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51  _TEXT, not.** SQ
2b560 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64  LITE_TEXT..*/.#d
2b570 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
2b580 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20  EGER  1.#define 
2b590 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20  SQLITE_FLOAT    
2b5a0 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
2b5b0 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66  _BLOB     4.#def
2b5c0 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20  ine SQLITE_NULL 
2b5d0 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c      5.#ifdef SQL
2b5e0 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66  ITE_TEXT.# undef
2b5f0 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c   SQLITE_TEXT.#el
2b600 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  se.# define SQLI
2b610 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65  TE_TEXT     3.#e
2b620 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c  ndif.#define SQL
2b630 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a  ITE3_TEXT     3.
2b640 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2b650 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46   Result Values F
2b660 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b  rom A Query.** K
2b670 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e  EYWORDS: {column
2b680 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
2b690 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  s}.**.** These r
2b6a0 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65  outines form the
2b6b0 20 22 72 65 73 75 6c 74 20 73 65 74 22 20 69 6e   "result set" in
2b6c0 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e  terface..**.** ^
2b6d0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
2b6e0 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f  eturn informatio
2b6f0 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65  n about a single
2b700 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63   column of the c
2b710 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74  urrent.** result
2b720 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e   row of a query.
2b730 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65    ^In every case
2b740 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
2b750 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
2b760 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70  .** to the [prep
2b770 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2b780 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65 76  that is being ev
2b790 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 71  aluated (the [sq
2b7a0 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20  lite3_stmt*].** 
2b7b0 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65  that was returne
2b7c0 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
2b7d0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
2b7e0 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69   one of its vari
2b7f0 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65  ants).** and the
2b800 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
2b810 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
2b820 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20   the column for 
2b830 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f  which informatio
2b840 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72  n.** should be r
2b850 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65  eturned. ^The le
2b860 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66  ftmost column of
2b870 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
2b880 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e  has the index 0.
2b890 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20  .** ^The number 
2b8a0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
2b8b0 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20  e result can be 
2b8c0 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67  determined using
2b8d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
2b8e0 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a  umn_count()]..**
2b8f0 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73  .** If the SQL s
2b900 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f  tatement does no
2b910 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e  t currently poin
2b920 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77  t to a valid row
2b930 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63  , or if the.** c
2b940 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f  olumn index is o
2b950 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65  ut of range, the
2b960 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66   result is undef
2b970 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72  ined..** These r
2b980 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79  outines may only
2b990 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20   be called when 
2b9a0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
2b9b0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
2b9c0 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
2b9d0 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
2b9e0 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65  _ROW] and neithe
2b9f0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  r.** [sqlite3_re
2ba00 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69  set()] nor [sqli
2ba10 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2ba20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  have been called
2ba30 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a   subsequently..*
2ba40 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73  * If any of thes
2ba50 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  e routines are c
2ba60 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c  alled after [sql
2ba70 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
2ba80 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
2ba90 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65  alize()] or afte
2baa0 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  r [sqlite3_step(
2bab0 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a  )] has returned.
2bac0 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68  ** something oth
2bad0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
2bae0 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74  ROW], the result
2baf0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
2bb00 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f  .** If [sqlite3_
2bb10 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
2bb20 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
2bb30 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2bb40 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c  e()].** are call
2bb50 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72  ed from a differ
2bb60 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65  ent thread while
2bb70 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
2bb80 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65  utines.** are pe
2bb90 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20  nding, then the 
2bba0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
2bbb0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
2bbc0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
2bbd0 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20  _type() routine 
2bbe0 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b  returns the.** [
2bbf0 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c  SQLITE_INTEGER |
2bc00 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20   datatype code] 
2bc10 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20  for the initial 
2bc20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20  data type.** of 
2bc30 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  the result colum
2bc40 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65  n.  ^The returne
2bc50 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f  d value is one o
2bc60 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  f [SQLITE_INTEGE
2bc70 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  R],.** [SQLITE_F
2bc80 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54  LOAT], [SQLITE_T
2bc90 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c  EXT], [SQLITE_BL
2bca0 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OB], or [SQLITE_
2bcb0 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75  NULL].  The valu
2bcc0 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79  e.** returned by
2bcd0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2bce0 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d  type() is only m
2bcf0 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20  eaningful if no 
2bd00 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69  type.** conversi
2bd10 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65  ons have occurre
2bd20 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20 62  d as described b
2bd30 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74  elow.  After a t
2bd40 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a  ype conversion,.
2bd50 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ** the value ret
2bd60 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
2bd70 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69  _column_type() i
2bd80 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75  s undefined.  Fu
2bd90 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73  ture.** versions
2bda0 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63   of SQLite may c
2bdb0 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69  hange the behavi
2bdc0 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f  or of sqlite3_co
2bdd0 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66  lumn_type().** f
2bde0 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20  ollowing a type 
2bdf0 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a  conversion..**.*
2be00 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2be10 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54   is a BLOB or UT
2be20 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20  F-8 string then 
2be30 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  the sqlite3_colu
2be40 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f  mn_bytes().** ro
2be50 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
2be60 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2be70 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f  s in that BLOB o
2be80 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  r string..** ^If
2be90 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
2bea0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20   UTF-16 string, 
2beb0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2bec0 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76  umn_bytes() conv
2bed0 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69  erts.** the stri
2bee0 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20  ng to UTF-8 and 
2bef0 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65  then returns the
2bf00 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2bf10 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
2bf20 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63  ult is a numeric
2bf30 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69   value then sqli
2bf40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2bf50 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69  () uses.** [sqli
2bf60 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
2bf70 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20  to convert that 
2bf80 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38  value to a UTF-8
2bf90 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
2bfa0 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  rns.** the numbe
2bfb0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
2bfc0 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  at string..** ^I
2bfd0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2bfe0 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74  NULL, then sqlit
2bff0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2c000 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a  ) returns zero..
2c010 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  **.** ^If the re
2c020 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f  sult is a BLOB o
2c030 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  r UTF-16 string 
2c040 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
2c050 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2c060 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
2c070 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
2c080 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
2c090 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e   BLOB or string.
2c0a0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2c0b0 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20 73 74  lt is a UTF-8 st
2c0c0 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74  ring, then sqlit
2c0d0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2c0e0 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  6() converts.** 
2c0f0 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54  the string to UT
2c100 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65  F-16 and then re
2c110 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
2c120 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49   of bytes..** ^I
2c130 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2c140 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20  a numeric value 
2c150 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2c160 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73  umn_bytes16() us
2c170 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  es.** [sqlite3_s
2c180 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f  nprintf()] to co
2c190 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65  nvert that value
2c1a0 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72   to a UTF-16 str
2c1b0 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a  ing and returns.
2c1c0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
2c1d0 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73   bytes in that s
2c1e0 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
2c1f0 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  e result is NULL
2c200 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
2c210 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
2c220 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a  returns zero..**
2c230 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20  .** ^The values 
2c240 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
2c250 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2c260 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71  s()] and .** [sq
2c270 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2c280 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69  es16()] do not i
2c290 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20  nclude the zero 
2c2a0 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74  terminators at t
2c2b0 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65  he end.** of the
2c2c0 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63   string.  ^For c
2c2d0 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75  larity: the valu
2c2e0 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  es returned by.*
2c2f0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2c300 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b  n_bytes()] and [
2c310 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2c320 79 74 65 73 31 36 28 29 5d 20 61 72 65 20 74 68  ytes16()] are th
2c330 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62  e number of.** b
2c340 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69  ytes in the stri
2c350 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62  ng, not the numb
2c360 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
2c370 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73  ..**.** ^Strings
2c380 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
2c390 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2c3a0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  () and sqlite3_c
2c3b0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a  olumn_text16(),.
2c3c0 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74  ** even empty st
2c3d0 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79  rings, are alway
2c3e0 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  s zero-terminate
2c3f0 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a  d.  ^The return.
2c400 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  ** value from sq
2c410 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
2c420 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c  b() for a zero-l
2c430 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20  ength BLOB is a 
2c440 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
2c450 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74 20  .** ^The object 
2c460 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
2c470 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
2c480 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75  e()] is an.** [u
2c490 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2c4a0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2c4b0 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65  .  An unprotecte
2c4c0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
2c4d0 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e  object.** may on
2c4e0 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 20  ly be used with 
2c4f0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
2c500 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  lue()] and [sqli
2c510 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
2c520 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b  ()]..** If the [
2c530 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2c540 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2c550 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  t returned by.**
2c560 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2c570 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65  _value()] is use
2c580 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77  d in any other w
2c590 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61  ay, including ca
2c5a0 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e  lls.** to routin
2c5b0 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33  es like [sqlite3
2c5c0 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b  _value_int()], [
2c5d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2c5e0 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71  xt()],.** or [sq
2c5f0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
2c600 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62  s()], then the b
2c610 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
2c620 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ined..**.** Thes
2c630 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d  e routines attem
2c640 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  pt to convert th
2c650 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70  e value where ap
2c660 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72  propriate.  ^For
2c670 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20  .** example, if 
2c680 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70  the internal rep
2c690 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46  resentation is F
2c6a0 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20  LOAT and a text 
2c6b0 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71  result.** is req
2c6c0 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33  uested, [sqlite3
2c6d0 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20  _snprintf()] is 
2c6e0 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  used internally 
2c6f0 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a  to perform the.*
2c700 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74  * conversion aut
2c710 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54  omatically.  ^(T
2c720 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62  he following tab
2c730 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63  le details the c
2c740 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68  onversions.** th
2c750 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a  at are applied:.
2c760 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
2c770 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72  e>.** <table bor
2c780 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e  der="1">.** <tr>
2c790 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72  <th> Internal<br
2c7a0 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65  >Type <th> Reque
2c7b0 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68  sted<br>Type <th
2c7c0 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a  >  Conversion.**
2c7d0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
2c7e0 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  LL    <td> INTEG
2c7f0 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  ER   <td> Result
2c800 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64   is 0.** <tr><td
2c810 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
2c820 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52   FLOAT    <td> R
2c830 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20  esult is 0.0.** 
2c840 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
2c850 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
2c860 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
2c870 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
2c880 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
2c890 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
2c8a0 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
2c8b0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
2c8c0 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
2c8d0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
2c8e0 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72   <td> Convert fr
2c8f0 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c  om integer to fl
2c900 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  oat.** <tr><td> 
2c910 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20  INTEGER  <td>   
2c920 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43  TEXT    <td> ASC
2c930 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  II rendering of 
2c940 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c  the integer.** <
2c950 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
2c960 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
2c970 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54  <td> Same as INT
2c980 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74  EGER->TEXT.** <t
2c990 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
2c9a0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
2c9b0 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d  td> Convert from
2c9c0 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67 65   float to intege
2c9d0 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  r.** <tr><td>  F
2c9e0 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45  LOAT   <td>   TE
2c9f0 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49  XT    <td> ASCII
2ca00 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
2ca10 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c  e float.** <tr><
2ca20 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
2ca30 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
2ca40 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e   Same as FLOAT->
2ca50 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  TEXT.** <tr><td>
2ca60 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49    TEXT    <td> I
2ca70 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 55 73  NTEGER   <td> Us
2ca80 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e  e atoi().** <tr>
2ca90 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
2caa0 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
2cab0 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20  > Use atof().** 
2cac0 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
2cad0 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
2cae0 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a   <td> No change.
2caf0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
2cb00 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  B    <td> INTEGE
2cb10 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74  R   <td> Convert
2cb20 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73   to TEXT then us
2cb30 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e  e atoi().** <tr>
2cb40 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
2cb50 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
2cb60 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58  > Convert to TEX
2cb70 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66 28  T then use atof(
2cb80 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  ).** <tr><td>  B
2cb90 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45  LOB    <td>   TE
2cba0 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61  XT    <td> Add a
2cbb0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
2cbc0 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f   if needed.** </
2cbd0 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63  table>.** </bloc
2cbe0 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20  kquote>)^.**.** 
2cbf0 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20  The table above 
2cc00 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20  makes reference 
2cc10 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  to standard C li
2cc20 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20  brary functions 
2cc30 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74  atoi().** and at
2cc40 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f  of().  SQLite do
2cc50 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73  es not really us
2cc60 65 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  e these function
2cc70 73 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a  s.  It has its.*
2cc80 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74  * own equivalent
2cc90 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e   internal routin
2cca0 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20  es.  The atoi() 
2ccb0 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73  and atof() names
2ccc0 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20   are.** used in 
2ccd0 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72  the table for br
2cce0 65 76 69 74 79 20 61 6e 64 20 62 65 63 61 75 73  evity and becaus
2ccf0 65 20 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c  e they are famil
2cd00 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43  iar to most.** C
2cd10 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a   programmers..**
2cd20 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68  .** Note that wh
2cd30 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69  en type conversi
2cd40 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74  ons occur, point
2cd50 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ers returned by 
2cd60 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74  prior.** calls t
2cd70 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
2cd80 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33  _blob(), sqlite3
2cd90 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20  _column_text(), 
2cda0 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  and/or.** sqlite
2cdb0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2cdc0 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64  ) may be invalid
2cdd0 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f  ated..** Type co
2cde0 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f  nversions and po
2cdf0 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69  inter invalidati
2ce00 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a  ons might occur.
2ce10 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77  ** in the follow
2ce20 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a  ing cases:.**.**
2ce30 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68   <ul>.** <li> Th
2ce40 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
2ce50 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20  t is a BLOB and 
2ce60 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2ce70 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  ext() or.**     
2ce80 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2ce90 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c  text16() is call
2cea0 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d  ed.  A zero-term
2ceb0 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20  inator might.** 
2cec0 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20       need to be 
2ced0 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72  added to the str
2cee0 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69  ing.</li>.** <li
2cef0 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
2cf00 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74  ntent is UTF-8 t
2cf10 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
2cf20 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2cf30 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
2cf40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2cf50 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  6() is called.  
2cf60 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74  The content must
2cf70 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a   be converted.**
2cf80 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e        to UTF-16.
2cf90 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  </li>.** <li> Th
2cfa0 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
2cfb0 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74  t is UTF-16 text
2cfc0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
2cfd0 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a  umn_bytes() or.*
2cfe0 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
2cff0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20  olumn_text() is 
2d000 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e  called.  The con
2d010 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e  tent must be con
2d020 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74  verted.**      t
2d030 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a  o UTF-8.</li>.**
2d040 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f   </ul>.**.** ^Co
2d050 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65  nversions betwee
2d060 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55  n UTF-16be and U
2d070 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61  TF-16le are alwa
2d080 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  ys done in place
2d090 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69   and do.** not i
2d0a0 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f  nvalidate a prio
2d0b0 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67  r pointer, thoug
2d0c0 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20  h of course the 
2d0d0 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62  content of the b
2d0e0 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68  uffer.** that th
2d0f0 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20  e prior pointer 
2d100 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20  references will 
2d110 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69  have been modifi
2d120 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73  ed.  Other kinds
2d130 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f  .** of conversio
2d140 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c  n are done in pl
2d150 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70  ace when it is p
2d160 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d  ossible, but som
2d170 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61  etimes they.** a
2d180 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  re not possible 
2d190 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73  and in those cas
2d1a0 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72  es prior pointer
2d1b0 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65  s are invalidate
2d1c0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66  d..**.** The saf
2d1d0 65 73 74 20 61 6e 64 20 65 61 73 69 65 73 74 20  est and easiest 
2d1e0 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69  to remember poli
2d1f0 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20  cy is to invoke 
2d200 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  these routines.*
2d210 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20  * in one of the 
2d220 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a  following ways:.
2d230 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c  **.** <ul>.**  <
2d240 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
2d250 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65  n_text() followe
2d260 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
2d270 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e  umn_bytes()</li>
2d280 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
2d290 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66  _column_blob() f
2d2a0 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
2d2b0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2d2c0 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  )</li>.**  <li>s
2d2d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2d2e0 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20  xt16() followed 
2d2f0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
2d300 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e  n_bytes16()</li>
2d310 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
2d320 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
2d330 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20  you should call 
2d340 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2d350 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  ext(),.** sqlite
2d360 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c  3_column_blob(),
2d370 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
2d380 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73  mn_text16() firs
2d390 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72  t to force the r
2d3a0 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68  esult.** into th
2d3b0 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74  e desired format
2d3c0 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71  , then invoke sq
2d3d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2d3e0 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  es() or.** sqlit
2d3f0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2d400 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20  6() to find the 
2d410 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75  size of the resu
2d420 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20  lt.  Do not mix 
2d430 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69  calls.** to sqli
2d440 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2d450 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ) or sqlite3_col
2d460 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20  umn_blob() with 
2d470 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69  calls to.** sqli
2d480 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2d490 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74  16(), and do not
2d4a0 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71   mix calls to sq
2d4b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2d4c0 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61  t16().** with ca
2d4d0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
2d4e0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a  olumn_bytes()..*
2d4f0 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65  *.** ^The pointe
2d500 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20  rs returned are 
2d510 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79  valid until a ty
2d520 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63  pe conversion oc
2d530 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72  curs as.** descr
2d540 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75  ibed above, or u
2d550 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ntil [sqlite3_st
2d560 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ep()] or [sqlite
2d570 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
2d580 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2d590 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e  ze()] is called.
2d5a0 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70    ^The memory sp
2d5b0 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64  ace used to hold
2d5c0 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20   strings.** and 
2d5d0 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20 61  BLOBs is freed a
2d5e0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44  utomatically.  D
2d5f0 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73  o <b>not</b> pas
2d600 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72  s the pointers r
2d610 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69  eturned.** [sqli
2d620 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
2d630 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  )], [sqlite3_col
2d640 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63  umn_text()], etc
2d650 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  . into.** [sqlit
2d660 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a  e3_free()]..**.*
2d670 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20  * ^(If a memory 
2d680 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
2d690 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74   occurs during t
2d6a0 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  he evaluation of
2d6b0 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65   any.** of these
2d6c0 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66   routines, a def
2d6d0 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65  ault value is re
2d6e0 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66  turned.  The def
2d6f0 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73  ault value.** is
2d700 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 65   either the inte
2d710 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74  ger 0, the float
2d720 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72  ing point number
2d730 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a   0.0, or a NULL.
2d740 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62  ** pointer.  Sub
2d750 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
2d760 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
2d770 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  e()] will return
2d780 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  .** [SQLITE_NOME
2d790 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76  M].)^.*/.const v
2d7a0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
2d7b0 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  umn_blob(sqlite3
2d7c0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2d7d0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
2d7e0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69  olumn_bytes(sqli
2d7f0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2d800 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
2d810 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2d820 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2d830 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c  int iCol);.doubl
2d840 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
2d850 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
2d860 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2d870 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
2d880 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33  lumn_int(sqlite3
2d890 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2d8a0 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
2d8b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2d8c0 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
2d8d0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2d8e0 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63  const unsigned c
2d8f0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
2d900 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33  umn_text(sqlite3
2d910 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2d920 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
2d930 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2d940 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt16(sqlite3_stm
2d950 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
2d960 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
2d970 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73  n_type(sqlite3_s
2d980 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2d990 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a  .sqlite3_value *
2d9a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
2d9b0 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  alue(sqlite3_stm
2d9c0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a  t*, int iCol);..
2d9d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2d9e0 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72  Destroy A Prepar
2d9f0 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
2da00 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ect.**.** ^The s
2da10 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2da20 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61  ) function is ca
2da30 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61  lled to delete a
2da40 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2da50 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68  ment]..** ^If th
2da60 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76  e most recent ev
2da70 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  aluation of the 
2da80 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e  statement encoun
2da90 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a  tered no errors.
2daa0 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74 61  ** or if the sta
2dab0 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20  tement is never 
2dac0 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20  been evaluated, 
2dad0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e  then sqlite3_fin
2dae0 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a  alize() returns.
2daf0 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e  ** SQLITE_OK.  ^
2db00 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
2db10 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  nt evaluation of
2db20 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69   statement S fai
2db30 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  led, then.** sql
2db40 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
2db50 20 72 65 74 75 72 6e 73 20 74 68 65 20 61 70 70   returns the app
2db60 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20  ropriate [error 
2db70 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  code] or.** [ext
2db80 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
2db90 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ]..**.** ^The sq
2dba0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53  lite3_finalize(S
2dbb0 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65  ) routine can be
2dbc0 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70   called at any p
2dbd0 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74  oint during.** t
2dbe0 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66  he life cycle of
2dbf0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2dc00 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f  ment] S:.** befo
2dc10 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69  re statement S i
2dc20 73 20 65 76 65 72 20 65 76 61 6c 75 61 74 65 64  s ever evaluated
2dc30 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f  , after.** one o
2dc40 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20  r more calls to 
2dc50 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2dc60 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20  ], or after any 
2dc70 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  call.** to [sqli
2dc80 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61  te3_step()] rega
2dc90 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
2dca0 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61  r or not the sta
2dcb0 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f  tement has.** co
2dcc0 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f  mpleted executio
2dcd0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69  n..**.** ^Invoki
2dce0 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  ng sqlite3_final
2dcf0 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20  ize() on a NULL 
2dd00 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61 72  pointer is a har
2dd10 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a  mless no-op..**.
2dd20 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
2dd30 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65  on must finalize
2dd40 20 65 76 65 72 79 20 5b 70 72 65 70 61 72 65 64   every [prepared
2dd50 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f   statement] in o
2dd60 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a  rder to avoid.**
2dd70 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e   resource leaks.
2dd80 20 20 49 74 20 69 73 20 61 20 67 72 69 65 76 6f    It is a grievo
2dd90 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65  us error for the
2dda0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20   application to 
2ddb0 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20  try to use.** a 
2ddc0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2ddd0 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20  nt after it has 
2dde0 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20  been finalized. 
2ddf0 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72   Any use of a pr
2de00 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
2de10 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73  ent after it has
2de20 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20   been finalized 
2de30 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e  can result in un
2de40 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75  defined and.** u
2de50 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76  ndesirable behav
2de60 69 6f 72 20 73 75 63 68 20 61 73 20 73 65 67 66  ior such as segf
2de70 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63  aults and heap c
2de80 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e  orruption..*/.in
2de90 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  t sqlite3_finali
2dea0 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ze(sqlite3_stmt 
2deb0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
2dec0 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
2ded0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
2dee0 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  ment Object.**.*
2def0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
2df00 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  set() function i
2df10 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65  s called to rese
2df20 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  t a [prepared st
2df30 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65  atement].** obje
2df40 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69  ct back to its i
2df50 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65  nitial state, re
2df60 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65  ady to be re-exe
2df70 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53  cuted..** ^Any S
2df80 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72  QL statement var
2df90 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20  iables that had 
2dfa0 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20  values bound to 
2dfb0 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68  them using.** th
2dfc0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
2dfd0 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62  blob | sqlite3_b
2dfe0 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74  ind_*() API] ret
2dff0 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73  ain their values
2e000 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65  ..** Use [sqlite
2e010 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73  3_clear_bindings
2e020 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65  ()] to reset the
2e030 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a   bindings..**.**
2e040 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72   ^The [sqlite3_r
2e050 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61  eset(S)] interfa
2e060 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70  ce resets the [p
2e070 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2e080 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20  t] S.** back to 
2e090 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
2e0a0 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a   its program..**
2e0b0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
2e0c0 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
2e0d0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
2e0e0 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72  ] for the.** [pr
2e0f0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2e100 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51  ] S returned [SQ
2e110 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51  LITE_ROW] or [SQ
2e120 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f  LITE_DONE],.** o
2e130 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  r if [sqlite3_st
2e140 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72  ep(S)] has never
2e150 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c   before been cal
2e160 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65  led on S,.** the
2e170 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
2e180 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51  (S)] returns [SQ
2e190 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  LITE_OK]..**.** 
2e1a0 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
2e1b0 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
2e1c0 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f  ite3_step(S)] fo
2e1d0 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  r the.** [prepar
2e1e0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
2e1f0 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72  indicated an err
2e200 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c  or, then.** [sql
2e210 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72  ite3_reset(S)] r
2e220 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70  eturns an approp
2e230 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
2e240 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  e]..**.** ^The [
2e250 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
2e260 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73  ] interface does
2e270 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
2e280 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79  values.** of any
2e290 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2e2a0 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  lob|bindings] on
2e2b0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2e2c0 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a  tatement] S..*/.
2e2d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65  int sqlite3_rese
2e2e0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
2e2f0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
2e300 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20  API3REF: Create 
2e310 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20  Or Redefine SQL 
2e320 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59  Functions.** KEY
2e330 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e  WORDS: {function
2e340 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
2e350 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  es}.** KEYWORDS:
2e360 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
2e370 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
2e380 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  on}.** KEYWORDS:
2e390 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
2e3a0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
2e3b0 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ons}.**.** ^Thes
2e3c0 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c  e functions (col
2e3d0 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20  lectively known 
2e3e0 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65  as "function cre
2e3f0 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29  ation routines")
2e400 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20  .** are used to 
2e410 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  add SQL function
2e420 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20  s or aggregates 
2e430 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74  or to redefine t
2e440 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f  he behavior.** o
2e450 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66  f existing SQL f
2e460 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72  unctions or aggr
2e470 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c  egates.  The onl
2e480 79 20 64 69 66 66 65 72 65 6e 63 65 73 20 62 65  y differences be
2e490 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72  tween.** these r
2e4a0 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68 65 20  outines are the 
2e4b0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78  text encoding ex
2e4c0 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68  pected for.** th
2e4d0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
2e4e0 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20  er (the name of 
2e4f0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69  the function bei
2e500 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61  ng created).** a
2e510 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63 65 20  nd the presence 
2e520 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20  or absence of a 
2e530 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62  destructor callb
2e540 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61  ack for.** the a
2e550 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
2e560 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
2e570 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
2e580 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 61  ter is the [data
2e590 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2e5a0 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 51   to which the SQ
2e5b0 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73  L.** function is
2e5c0 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e   to be added.  ^
2e5d0 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  If an applicatio
2e5e0 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e  n uses more than
2e5f0 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   one database.**
2e600 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e   connection then
2e610 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2e620 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
2e630 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64  ns must be added
2e640 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61  .** to each data
2e650 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2e660 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a  separately..**.*
2e670 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  * ^The second pa
2e680 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e  rameter is the n
2e690 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66  ame of the SQL f
2e6a0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72  unction to be cr
2e6b0 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65  eated or.** rede
2e6c0 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e  fined.  ^The len
2e6d0 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20  gth of the name 
2e6e0 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35  is limited to 25
2e6f0 35 20 62 79 74 65 73 20 69 6e 20 61 20 55 54 46  5 bytes in a UTF
2e700 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61  -8.** representa
2e710 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20  tion, exclusive 
2e720 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d  of the zero-term
2e730 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74  inator.  ^Note t
2e740 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20  hat the name.** 
2e750 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20  length limit is 
2e760 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20  in UTF-8 bytes, 
2e770 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 20 6e  not characters n
2e780 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e  or UTF-16 bytes.
2e790 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d    .** ^Any attem
2e7a0 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66  pt to create a f
2e7b0 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c  unction with a l
2e7c0 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69  onger name.** wi
2e7d0 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51  ll result in [SQ
2e7e0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69  LITE_MISUSE] bei
2e7f0 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  ng returned..**.
2e800 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70 61  ** ^The third pa
2e810 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a  rameter (nArg).*
2e820 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  * is the number 
2e830 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  of arguments tha
2e840 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
2e850 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
2e860 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68  te takes. ^If th
2e870 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  is parameter is 
2e880 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c  -1, then the SQL
2e890 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
2e8a0 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61  aggregate may ta
2e8b0 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66  ke any number of
2e8c0 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65   arguments betwe
2e8d0 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d  en 0 and the lim
2e8e0 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71  it.** set by [sq
2e8f0 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51  lite3_limit]([SQ
2e900 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
2e910 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74  ION_ARG]).  If t
2e920 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61  he third.** para
2e930 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20 74 68  meter is less th
2e940 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72  an -1 or greater
2e950 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74   than 127 then t
2e960 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a  he behavior is.*
2e970 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  * undefined..**.
2e980 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70  ** ^The fourth p
2e990 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52  arameter, eTextR
2e9a0 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68  ep, specifies wh
2e9b0 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  at.** [SQLITE_UT
2e9c0 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69  F8 | text encodi
2e9d0 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e  ng] this SQL fun
2e9e0 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f  ction prefers fo
2e9f0 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74  r.** its paramet
2ea00 65 72 73 2e 20 20 45 76 65 72 79 20 53 51 4c 20  ers.  Every SQL 
2ea10 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
2ea20 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 62 65 20  ntation must be 
2ea30 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20  able to work.** 
2ea40 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d  with UTF-8, UTF-
2ea50 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62  16le, or UTF-16b
2ea60 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70  e.  But some imp
2ea70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79  lementations may
2ea80 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69   be.** more effi
2ea90 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65  cient with one e
2eaa0 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f  ncoding than ano
2eab0 74 68 65 72 2e 20 20 5e 41 6e 20 61 70 70 6c 69  ther.  ^An appli
2eac0 63 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20 69 6e  cation may.** in
2ead0 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65  voke sqlite3_cre
2eae0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f  ate_function() o
2eaf0 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
2eb00 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75  _function16() mu
2eb10 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20  ltiple.** times 
2eb20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 66 75  with the same fu
2eb30 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20  nction but with 
2eb40 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73  different values
2eb50 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a   of eTextRep..**
2eb60 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20   ^When multiple 
2eb70 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
2eb80 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
2eb90 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62  tion are availab
2eba0 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69  le, SQLite.** wi
2ebb0 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20  ll pick the one 
2ebc0 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68  that involves th
2ebd0 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f  e least amount o
2ebe0 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f  f data conversio
2ebf0 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69  n..** If there i
2ec00 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20  s only a single 
2ec10 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
2ec20 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61  hich does not ca
2ec30 72 65 20 77 68 61 74 20 74 65 78 74 0a 2a 2a 20  re what text.** 
2ec40 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64  encoding is used
2ec50 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74  , then the fourt
2ec60 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  h argument shoul
2ec70 64 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59  d be [SQLITE_ANY
2ec80 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66  ]..**.** ^(The f
2ec90 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  ifth parameter i
2eca0 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70  s an arbitrary p
2ecb0 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70  ointer.  The imp
2ecc0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
2ecd0 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63  he.** function c
2ece0 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74  an gain access t
2ecf0 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75  o this pointer u
2ed00 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73  sing [sqlite3_us
2ed10 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a  er_data()].)^.**
2ed20 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20  .** ^The sixth, 
2ed30 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68  seventh and eigh
2ed40 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78  th parameters, x
2ed50 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20  Func, xStep and 
2ed60 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70  xFinal, are.** p
2ed70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e  ointers to C-lan
2ed80 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20  guage functions 
2ed90 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74  that implement t
2eda0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
2edb0 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e  or.** aggregate.
2edc0 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66   ^A scalar SQL f
2edd0 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73  unction requires
2ede0 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69   an implementati
2edf0 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a  on of the xFunc.
2ee00 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79  ** callback only
2ee10 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20  ; NULL pointers 
2ee20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61  must be passed a
2ee30 73 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20  s the xStep and 
2ee40 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65  xFinal.** parame
2ee50 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67  ters. ^An aggreg
2ee60 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
2ee70 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70   requires an imp
2ee80 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78  lementation of x
2ee90 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e  Step.** and xFin
2eea0 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e  al and NULL poin
2eeb0 74 65 72 20 6d 75 73 74 20 62 65 20 70 61 73 73  ter must be pass
2eec0 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54  ed for xFunc. ^T
2eed0 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73  o delete an exis
2eee0 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63  ting.** SQL func
2eef0 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74  tion or aggregat
2ef00 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69  e, pass NULL poi
2ef10 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68  nters for all th
2ef20 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ree function.** 
2ef30 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a  callbacks..**.**
2ef40 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20   ^(If the ninth 
2ef50 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
2ef60 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2ef70 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74  tion_v2() is not
2ef80 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69   NULL,.** then i
2ef90 74 20 69 73 20 64 65 73 74 72 75 63 74 6f 72 20  t is destructor 
2efa0 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  for the applicat
2efb0 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ion data pointer
2efc0 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75  . .** The destru
2efd0 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20  ctor is invoked 
2efe0 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f  when the functio
2eff0 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69  n is deleted, ei
2f000 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a  ther by being.**
2f010 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77   overloaded or w
2f020 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
2f030 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73   connection clos
2f040 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65  es.)^.** ^The de
2f050 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f  structor is also
2f060 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20   invoked if the 
2f070 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  call to.** sqlit
2f080 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2f090 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a  on_v2() fails..*
2f0a0 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74  * ^When the dest
2f0b0 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20  ructor callback 
2f0c0 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70 61 72  of the tenth par
2f0d0 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65  ameter is invoke
2f0e0 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73  d, it.** is pass
2f0f0 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  ed a single argu
2f100 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
2f110 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c  copy of the appl
2f120 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a  ication data .**
2f130 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77   pointer which w
2f140 61 73 20 74 68 65 20 66 69 66 74 68 20 70 61 72  as the fifth par
2f150 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
2f160 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2f170 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49  n_v2()..**.** ^I
2f180 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74  t is permitted t
2f190 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69  o register multi
2f1a0 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
2f1b0 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a  ons of the same.
2f1c0 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74  ** functions wit
2f1d0 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20  h the same name 
2f1e0 62 75 74 20 77 69 74 68 20 65 69 74 68 65 72 20  but with either 
2f1f0 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72  differing number
2f200 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  s of.** argument
2f210 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70  s or differing p
2f220 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
2f230 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74  codings.  ^SQLit
2f240 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68  e will use.** th
2f250 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2f260 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65   that most close
2f270 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77  ly matches the w
2f280 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a  ay in which the.
2f290 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ** SQL function 
2f2a0 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e  is used.  ^A fun
2f2b0 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
2f2c0 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d  tion with a non-
2f2d0 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67  negative.** nArg
2f2e0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
2f2f0 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 68 61  better match tha
2f300 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  n a function imp
2f310 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68  lementation with
2f320 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e  .** a negative n
2f330 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f  Arg.  ^A functio
2f340 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 65 66  n where the pref
2f350 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
2f360 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74  ing.** matches t
2f370 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f  he database enco
2f380 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 65 72  ding is a better
2f390 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61  .** match than a
2f3a0 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
2f3b0 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  the encoding is 
2f3c0 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20  different.  .** 
2f3d0 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72  ^A function wher
2f3e0 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64  e the encoding d
2f3f0 69 66 66 65 72 65 6e 63 65 20 69 73 20 62 65 74  ifference is bet
2f400 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64  ween UTF16le and
2f410 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61   UTF16be.** is a
2f420 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68   closer match th
2f430 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68  an a function wh
2f440 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
2f450 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a   difference is.*
2f460 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38 20 61  * between UTF8 a
2f470 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20  nd UTF16..**.** 
2f480 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69  ^Built-in functi
2f490 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c  ons may be overl
2f4a0 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61 70 70  oaded by new app
2f4b0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2f4c0 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a   functions..**.*
2f4d0 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f  * ^An applicatio
2f4e0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
2f4f0 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 20  on is permitted 
2f500 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a  to call other.**
2f510 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
2f520 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75  es.  However, su
2f530 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f  ch calls must no
2f540 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64  t.** close the d
2f550 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2f560 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20  on nor finalize 
2f570 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 72 65  or reset the pre
2f580 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
2f590 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 65 20  nt in which the 
2f5a0 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
2f5b0 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ing..*/.int sqli
2f5c0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2f5d0 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ion(.  sqlite3 *
2f5e0 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  db,.  const char
2f5f0 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
2f600 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
2f610 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
2f620 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
2f630 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
2f640 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
2f650 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
2f660 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
2f670 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
2f680 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
2f690 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
2f6a0 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
2f6b0 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69  3_context*).);.i
2f6c0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
2f6d0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20  e_function16(.  
2f6e0 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
2f6f0 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63  onst void *zFunc
2f700 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
2f710 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
2f720 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
2f730 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
2f740 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
2f750 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
2f760 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
2f770 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
2f780 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
2f790 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
2f7a0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
2f7b0 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
2f7c0 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  xt*).);.int sqli
2f7d0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2f7e0 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  ion_v2(.  sqlite
2f7f0 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63  3 *db,.  const c
2f800 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  har *zFunctionNa
2f810 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
2f820 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
2f830 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
2f840 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
2f850 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
2f860 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
2f870 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
2f880 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
2f890 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
2f8a0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
2f8b0 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
2f8c0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a  ite3_context*),.
2f8d0 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79    void(*xDestroy
2f8e0 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a  )(void*).);../*.
2f8f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 78  ** CAPI3REF: Tex
2f900 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a  t Encodings.**.*
2f910 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
2f920 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20   define integer 
2f930 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65  codes that repre
2f940 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73  sent the various
2f950 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  .** text encodin
2f960 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20  gs supported by 
2f970 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69  SQLite..*/.#defi
2f980 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20  ne SQLITE_UTF8  
2f990 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
2f9a0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  ne SQLITE_UTF16L
2f9b0 45 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69  E        2.#defi
2f9c0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42  ne SQLITE_UTF16B
2f9d0 45 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69  E        3.#defi
2f9e0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20  ne SQLITE_UTF16 
2f9f0 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a           4    /*
2fa00 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65   Use native byte
2fa10 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e   order */.#defin
2fa20 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20  e SQLITE_ANY    
2fa30 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20          5    /* 
2fa40 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2fa50 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a  unction only */.
2fa60 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
2fa70 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20  TF16_ALIGNED  8 
2fa80 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72     /* sqlite3_cr
2fa90 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f  eate_collation o
2faa0 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  nly */../*.** CA
2fab0 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74  PI3REF: Deprecat
2fac0 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  ed Functions.** 
2fad0 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a  DEPRECATED.**.**
2fae0 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
2faf0 20 61 72 65 20 5b 64 65 70 72 65 63 61 74 65 64   are [deprecated
2fb00 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20  ].  In order to 
2fb10 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b  maintain.** back
2fb20 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
2fb30 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63  ity with older c
2fb40 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74  ode, these funct
2fb50 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a  ions continue .*
2fb60 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  * to be supporte
2fb70 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77  d.  However, new
2fb80 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68   applications sh
2fb90 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68  ould avoid.** th
2fba0 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 66  e use of these f
2fbb0 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65  unctions.  To he
2fbc0 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f  lp encourage peo
2fbd0 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20  ple to avoid.** 
2fbe0 75 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63  using these func
2fbf0 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f  tions, we are no
2fc00 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20  t going to tell 
2fc10 79 6f 75 20 77 68 61 74 20 74 68 65 79 20 64 6f  you what they do
2fc20 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c  ..*/.#ifndef SQL
2fc30 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41  ITE_OMIT_DEPRECA
2fc40 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  TED.SQLITE_DEPRE
2fc50 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
2fc60 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e  3_aggregate_coun
2fc70 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
2fc80 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  t*);.SQLITE_DEPR
2fc90 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
2fca0 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74  e3_expired(sqlit
2fcb0 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54  e3_stmt*);.SQLIT
2fcc0 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
2fcd0 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65   sqlite3_transfe
2fce0 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74  r_bindings(sqlit
2fcf0 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65  e3_stmt*, sqlite
2fd00 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45  3_stmt*);.SQLITE
2fd10 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
2fd20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72  sqlite3_global_r
2fd30 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51  ecover(void);.SQ
2fd40 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
2fd50 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72  void sqlite3_thr
2fd60 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64  ead_cleanup(void
2fd70 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
2fd80 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
2fd90 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f  _memory_alarm(vo
2fda0 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
2fdb0 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76  te3_int64,int),v
2fdc0 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74  oid*,sqlite3_int
2fdd0 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  64);.#endif../*.
2fde0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74  ** CAPI3REF: Obt
2fdf0 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74  aining SQL Funct
2fe00 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61  ion Parameter Va
2fe10 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43  lues.**.** The C
2fe20 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d  -language implem
2fe30 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20  entation of SQL 
2fe40 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
2fe50 67 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a  gregates uses.**
2fe60 20 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74   this set of int
2fe70 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20  erface routines 
2fe80 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 61  to access the pa
2fe90 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f  rameter values o
2fea0 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f  n.** the functio
2feb0 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a  n or aggregate..
2fec0 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20  **.** The xFunc 
2fed0 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63  (for scalar func
2fee0 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20  tions) or xStep 
2fef0 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29  (for aggregates)
2ff00 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74   parameters.** t
2ff10 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  o [sqlite3_creat
2ff20 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e  e_function()] an
2ff30 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
2ff40 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a  e_function16()].
2ff50 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61  ** define callba
2ff60 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  cks that impleme
2ff70 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nt the SQL funct
2ff80 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
2ff90 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20  tes..** The 3rd 
2ffa0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
2ffb0 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20  se callbacks is 
2ffc0 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
2ffd0 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74  ters to.** [prot
2ffe0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2fff0 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54  lue] objects.  T
30000 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c  here is one [sql
30010 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
30020 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70  ct for.** each p
30030 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
30040 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54  SQL function.  T
30050 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
30060 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74  e used to.** ext
30070 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d  ract values from
30080 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
30090 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  lue] objects..**
300a0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
300b0 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74  es work only wit
300c0 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  h [protected sql
300d0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
300e0 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65  cts..** Any atte
300f0 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 65  mpt to use these
30100 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20   routines on an 
30110 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
30120 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f  ite3_value].** o
30130 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e  bject results in
30140 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
30150 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ior..**.** ^Thes
30160 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20  e routines work 
30170 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f  just like the co
30180 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c  rresponding [col
30190 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
301a0 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20  ions].** except 
301b0 74 68 61 74 20 20 74 68 65 73 65 20 72 6f 75 74  that  these rout
301c0 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67  ines take a sing
301d0 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  le [protected sq
301e0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
301f0 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69  ect.** pointer i
30200 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c  nstead of a [sql
30210 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e  ite3_stmt*] poin
30220 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67  ter and an integ
30230 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72  er column number
30240 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
30250 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
30260 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78  6() interface ex
30270 74 72 61 63 74 73 20 61 20 55 54 46 2d 31 36 20  tracts a UTF-16 
30280 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65  string.** in the
30290 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64   native byte-ord
302a0 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d  er of the host m
302b0 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a  achine.  ^The.**
302c0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
302d0 65 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71  ext16be() and sq
302e0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
302f0 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  16le() interface
30300 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46  s.** extract UTF
30310 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62  -16 strings as b
30320 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69  ig-endian and li
30330 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70  ttle-endian resp
30340 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ectively..**.** 
30350 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61  ^(The sqlite3_va
30360 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65  lue_numeric_type
30370 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74  () interface att
30380 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a  empts to apply.*
30390 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69  * numeric affini
303a0 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e  ty to the value.
303b0 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61    This means tha
303c0 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a  t an attempt is.
303d0 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65  ** made to conve
303e0 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20  rt the value to 
303f0 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c  an integer or fl
30400 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49  oating point.  I
30410 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76  f.** such a conv
30420 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62  ersion is possib
30430 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20  le without loss 
30440 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28  of information (
30450 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64  in other.** word
30460 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  s, if the value 
30470 69 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 74  is a string that
30480 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75   looks like a nu
30490 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68  mber).** then th
304a0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  e conversion is 
304b0 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65  performed.  Othe
304c0 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73  rwise no convers
304d0 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54  ion occurs..** T
304e0 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  he [SQLITE_INTEG
304f0 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61  ER | datatype] a
30500 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20  fter conversion 
30510 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a  is returned.)^.*
30520 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20  *.** Please pay 
30530 70 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e  particular atten
30540 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74  tion to the fact
30550 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65   that the pointe
30560 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72  r returned.** fr
30570 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  om [sqlite3_valu
30580 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69  e_blob()], [sqli
30590 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
305a0 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
305b0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
305c0 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64  ] can be invalid
305d0 61 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71  ated by a subseq
305e0 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  uent call to.** 
305f0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
30600 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65  ytes()], [sqlite
30610 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28  3_value_bytes16(
30620 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
30630 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f  ue_text()],.** o
30640 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r [sqlite3_value
30650 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a  _text16()]..**.*
30660 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
30670 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
30680 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
30690 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53  read as.** the S
306a0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  QL function that
306b0 20 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73   supplied the [s
306c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70  qlite3_value*] p
306d0 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f  arameters..*/.co
306e0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
306f0 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c  3_value_blob(sql
30700 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
30710 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
30720 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61  bytes(sqlite3_va
30730 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
30740 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36  e3_value_bytes16
30750 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
30760 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33  ;.double sqlite3
30770 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71  _value_double(sq
30780 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
30790 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
307a0 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c  _int(sqlite3_val
307b0 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  ue*);.sqlite3_in
307c0 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  t64 sqlite3_valu
307d0 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  e_int64(sqlite3_
307e0 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75  value*);.const u
307f0 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71  nsigned char *sq
30800 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
30810 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
30820 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
30830 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
30840 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  16(sqlite3_value
30850 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
30860 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
30870 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76  xt16le(sqlite3_v
30880 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  alue*);.const vo
30890 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
308a0 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74  e_text16be(sqlit
308b0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
308c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79  sqlite3_value_ty
308d0 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  pe(sqlite3_value
308e0 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
308f0 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79  value_numeric_ty
30900 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  pe(sqlite3_value
30910 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
30920 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72  REF: Obtain Aggr
30930 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43  egate Function C
30940 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70  ontext.**.** Imp
30950 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
30960 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
30970 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73  nctions use this
30980 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 61  .** routine to a
30990 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 66  llocate memory f
309a0 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72  or storing their
309b0 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54   state..**.** ^T
309c0 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68  he first time th
309d0 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  e sqlite3_aggreg
309e0 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
309f0 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c   routine is call
30a00 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72  ed .** for a par
30a10 74 69 63 75 6c 61 72 20 61 67 67 72 65 67 61 74  ticular aggregat
30a20 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69  e function, SQLi
30a30 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20  te.** allocates 
30a40 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72  N of memory, zer
30a50 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65 6d  oes out that mem
30a60 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73  ory, and returns
30a70 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
30a80 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e   the new memory.
30a90 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20   ^On second and 
30aa0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
30ab0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61   to.** sqlite3_a
30ac0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
30ad0 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  () for the same 
30ae0 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
30af0 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20  on instance,.** 
30b00 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 20  the same buffer 
30b10 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53 71  is returned.  Sq
30b20 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
30b30 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f 72  context() is nor
30b40 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20  mally.** called 
30b50 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69 6e  once for each in
30b60 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  vocation of the 
30b70 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20 61  xStep callback a
30b80 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c  nd then one.** l
30b90 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74 68  ast time when th
30ba0 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  e xFinal callbac
30bb0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e  k is invoked.  ^
30bc0 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61  (When no rows ma
30bd0 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67  tch.** an aggreg
30be0 61 74 65 20 71 75 65 72 79 2c 20 74 68 65 20 78  ate query, the x
30bf0 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b 20  Step() callback 
30c00 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 74 65  of the aggregate
30c10 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70   function.** imp
30c20 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e  lementation is n
30c30 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64 20  ever called and 
30c40 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c  xFinal() is call
30c50 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e  ed exactly once.
30c60 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61 73  .** In those cas
30c70 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67 72  es, sqlite3_aggr
30c80 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
30c90 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20  might be called 
30ca0 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73 74  for the.** first
30cb0 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68 69   time from withi
30cc0 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a  n xFinal().)^.**
30cd0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
30ce0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
30cf0 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20  xt(C,N) routine 
30d00 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
30d10 6f 69 6e 74 65 72 20 69 66 20 4e 20 69 73 0a 2a  ointer if N is.*
30d20 2a 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65  * less than or e
30d30 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20  qual to zero or 
30d40 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  if a memory allo
30d50 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63 75 72  cate error occur
30d60 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61  s..**.** ^(The a
30d70 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 20 61  mount of space a
30d80 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69  llocated by sqli
30d90 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
30da0 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a  ntext(C,N) is.**
30db0 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74   determined by t
30dc0 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 6f  he N parameter o
30dd0 6e 20 66 69 72 73 74 20 73 75 63 63 65 73 73 66  n first successf
30de0 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69  ul call.  Changi
30df0 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20  ng the.** value 
30e00 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71 75 65  of N in subseque
30e10 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  nt call to sqlit
30e20 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
30e30 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a  text() within.**
30e40 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67   the same aggreg
30e50 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73  ate function ins
30e60 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72  tance will not r
30e70 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  esize the memory
30e80 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29  .** allocation.)
30e90 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ^.**.** ^SQLite 
30ea0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72  automatically fr
30eb0 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ees the memory a
30ec0 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a 20  llocated by .** 
30ed0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
30ee0 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65 6e  e_context() when
30ef0 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 71   the aggregate q
30f00 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a  uery concludes..
30f10 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
30f20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62  parameter must b
30f30 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  e a copy of the.
30f40 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ** [sqlite3_cont
30f50 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69  ext | SQL functi
30f60 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74  on context] that
30f70 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61   is the first pa
30f80 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68  rameter.** to th
30f90 65 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e 61  e xStep or xFina
30fa0 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69  l callback routi
30fb0 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ne that implemen
30fc0 74 73 20 74 68 65 20 61 67 67 72 65 67 61 74 65  ts the aggregate
30fd0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  .** function..**
30fe0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
30ff0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
31000 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
31010 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
31020 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 53   the aggregate S
31030 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  QL function is r
31040 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20  unning..*/.void 
31050 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  *sqlite3_aggrega
31060 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74  te_context(sqlit
31070 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
31080 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a   nBytes);../*.**
31090 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72 20   CAPI3REF: User 
310a0 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f  Data For Functio
310b0 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ns.**.** ^The sq
310c0 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
310d0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
310e0 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a  rns a copy of.**
310f0 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61   the pointer tha
31100 74 20 77 61 73 20 74 68 65 20 70 55 73 65 72 44  t was the pUserD
31110 61 74 61 20 70 61 72 61 6d 65 74 65 72 20 28 74  ata parameter (t
31120 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
31130 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  ).** of the [sql
31140 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
31150 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  tion()].** and [
31160 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
31170 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75  unction16()] rou
31180 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69  tines that origi
31190 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65  nally.** registe
311a0 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  red the applicat
311b0 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63  ion defined func
311c0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  tion..**.** This
311d0 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65   routine must be
311e0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
311f0 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
31200 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70  which.** the app
31210 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
31220 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
31230 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  ning..*/.void *s
31240 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
31250 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
31260 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
31270 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f  REF: Database Co
31280 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e  nnection For Fun
31290 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  ctions.**.** ^Th
312a0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e sqlite3_contex
312b0 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e  t_db_handle() in
312c0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
312d0 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  a copy of.** the
312e0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
312f0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
31300 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70  tion] (the 1st p
31310 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20  arameter).** of 
31320 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
31330 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a  ate_function()].
31340 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
31350 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
31360 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68  6()] routines th
31370 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a  at originally.**
31380 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20   registered the 
31390 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
313a0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f  ned function..*/
313b0 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65  .sqlite3 *sqlite
313c0 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e  3_context_db_han
313d0 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  dle(sqlite3_cont
313e0 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ext*);../*.** CA
313f0 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e  PI3REF: Function
31400 20 41 75 78 69 6c 69 61 72 79 20 44 61 74 61 0a   Auxiliary Data.
31410 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77  **.** The follow
31420 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e  ing two function
31430 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79  s may be used by
31440 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63   scalar SQL func
31450 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f  tions to.** asso
31460 63 69 61 74 65 20 6d 65 74 61 64 61 74 61 20 77  ciate metadata w
31470 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c  ith argument val
31480 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65  ues. If the same
31490 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64   value is passed
314a0 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20   to.** multiple 
314b0 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
314c0 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63  he same SQL func
314d0 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72  tion during quer
314e0 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64  y execution, und
314f0 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75  er.** some circu
31500 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73  mstances the ass
31510 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61 74 61  ociated metadata
31520 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65   may be preserve
31530 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62  d. This may.** b
31540 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d  e used, for exam
31550 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72 65  ple, to add a re
31560 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e  gular-expression
31570 20 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61 72   matching scalar
31580 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68  .** function. Th
31590 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69  e compiled versi
315a0 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61  on of the regula
315b0 72 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20  r expression is 
315c0 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74  stored as.** met
315d0 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64  adata associated
315e0 20 77 69 74 68 20 74 68 65 20 53 51 4c 20 76 61   with the SQL va
315f0 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68  lue passed as th
31600 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73  e regular expres
31610 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e  sion.** pattern.
31620 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 72    The compiled r
31630 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
31640 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 20  n can be reused 
31650 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69  on multiple.** i
31660 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
31670 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
31680 73 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69 67  so that the orig
31690 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74 72  inal pattern str
316a0 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  ing.** does not 
316b0 6e 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f 6d  need to be recom
316c0 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 6e  piled on each in
316d0 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  vocation..**.** 
316e0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74  ^The sqlite3_get
316f0 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72  _auxdata() inter
31700 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
31710 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65  ointer to the me
31720 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69  tadata.** associ
31730 61 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69  ated by the sqli
31740 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
31750 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  ) function with 
31760 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74  the Nth argument
31770 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65  .** value to the
31780 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
31790 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e  ined function. ^
317a0 49 66 20 6e 6f 20 6d 65 74 61 64 61 74 61 20 68  If no metadata h
317b0 61 73 20 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20  as been ever.** 
317c0 62 65 65 6e 20 73 65 74 20 66 6f 72 20 74 68 65  been set for the
317d0 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 20 6f 66   Nth argument of
317e0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f   the function, o
317f0 72 20 69 66 20 74 68 65 20 63 6f 72 72 65 73 70  r if the corresp
31800 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69  onding.** functi
31810 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  on parameter has
31820 20 63 68 61 6e 67 65 64 20 73 69 6e 63 65 20 74   changed since t
31830 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77 61 73  he meta-data was
31840 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71   set,.** then sq
31850 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
31860 61 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55  a() returns a NU
31870 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
31880 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
31890 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74  et_auxdata() int
318a0 65 72 66 61 63 65 20 73 61 76 65 73 20 74 68 65  erface saves the
318b0 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70 6f 69   metadata.** poi
318c0 6e 74 65 64 20 74 6f 20 62 79 20 69 74 73 20 33  nted to by its 3
318d0 72 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20  rd parameter as 
318e0 74 68 65 20 6d 65 74 61 64 61 74 61 20 66 6f 72  the metadata for
318f0 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67   the N-th.** arg
31900 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70  ument of the app
31910 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
31920 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73   function.  Subs
31930 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20  equent.** calls 
31940 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  to sqlite3_get_a
31950 75 78 64 61 74 61 28 29 20 6d 69 67 68 74 20 72  uxdata() might r
31960 65 74 75 72 6e 20 74 68 69 73 20 64 61 74 61 2c  eturn this data,
31970 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f   if it has.** no
31980 74 20 62 65 65 6e 20 64 65 73 74 72 6f 79 65 64  t been destroyed
31990 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 6e  ..** ^If it is n
319a0 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20  ot NULL, SQLite 
319b0 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20  will invoke the 
319c0 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 66 75  destructor.** fu
319d0 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20 62 79 20  nction given by 
319e0 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
319f0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74  r to sqlite3_set
31a00 5f 61 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a  _auxdata() on.**
31a10 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 77 68   the metadata wh
31a20 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  en the correspon
31a30 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61  ding function pa
31a40 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 0a  rameter changes.
31a50 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20 53  ** or when the S
31a60 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  QL statement com
31a70 70 6c 65 74 65 73 2c 20 77 68 69 63 68 65 76 65  pletes, whicheve
31a80 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a  r comes first..*
31a90 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66  *.** SQLite is f
31aa0 72 65 65 20 74 6f 20 63 61 6c 6c 20 74 68 65 20  ree to call the 
31ab0 64 65 73 74 72 75 63 74 6f 72 20 61 6e 64 20 64  destructor and d
31ac0 72 6f 70 20 6d 65 74 61 64 61 74 61 20 6f 6e 20  rop metadata on 
31ad0 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  any.** parameter
31ae0 20 6f 66 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e   of any function
31af0 20 61 74 20 61 6e 79 20 74 69 6d 65 2e 20 20 5e   at any time.  ^
31b00 54 68 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74  The only guarant
31b10 65 65 20 69 73 20 74 68 61 74 0a 2a 2a 20 74 68  ee is that.** th
31b20 65 20 64 65 73 74 72 75 63 74 6f 72 20 77 69 6c  e destructor wil
31b30 6c 20 62 65 20 63 61 6c 6c 65 64 20 62 65 66 6f  l be called befo
31b40 72 65 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  re the metadata 
31b50 69 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a  is dropped..**.*
31b60 2a 20 5e 28 49 6e 20 70 72 61 63 74 69 63 65 2c  * ^(In practice,
31b70 20 6d 65 74 61 64 61 74 61 20 69 73 20 70 72 65   metadata is pre
31b80 73 65 72 76 65 64 20 62 65 74 77 65 65 6e 20 66  served between f
31b90 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f  unction calls fo
31ba0 72 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 73  r.** expressions
31bb0 20 74 68 61 74 20 61 72 65 20 63 6f 6e 73 74 61   that are consta
31bc0 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69  nt at compile ti
31bd0 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c 75 64 65  me. This include
31be0 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c  s literal.** val
31bf0 75 65 73 20 61 6e 64 20 5b 70 61 72 61 6d 65 74  ues and [paramet
31c00 65 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  ers].)^.**.** Th
31c10 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73  ese routines mus
31c20 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
31c30 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
31c40 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
31c50 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
31c60 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69   running..*/.voi
31c70 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  d *sqlite3_get_a
31c80 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  uxdata(sqlite3_c
31c90 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b  ontext*, int N);
31ca0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65  .void sqlite3_se
31cb0 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65  t_auxdata(sqlite
31cc0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
31cd0 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28  N, void*, void (
31ce0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a  *)(void*));.../*
31cf0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
31d00 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67  nstants Defining
31d10 20 53 70 65 63 69 61 6c 20 44 65 73 74 72 75 63   Special Destruc
31d20 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a  tor Behavior.**.
31d30 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73 70 65  ** These are spe
31d40 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20  cial values for 
31d50 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 74  the destructor t
31d60 68 61 74 20 69 73 20 70 61 73 73 65 64 20 69 6e  hat is passed in
31d70 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c   as the.** final
31d80 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75   argument to rou
31d90 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69  tines like [sqli
31da0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
31db0 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 64 65 73  )].  ^If the des
31dc0 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d  tructor.** argum
31dd0 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54  ent is SQLITE_ST
31de0 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74  ATIC, it means t
31df0 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  hat the content 
31e00 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74  pointer is const
31e10 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20  ant.** and will 
31e20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49  never change.  I
31e30 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  t does not need 
31e40 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e  to be destroyed.
31e50 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45    ^The.** SQLITE
31e60 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65  _TRANSIENT value
31e70 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
31e80 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b  content will lik
31e90 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a  ely change in.**
31ea0 20 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 65   the near future
31eb0 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65   and that SQLite
31ec0 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73   should make its
31ed0 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
31ee0 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74  y of.** the cont
31ef0 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 72  ent before retur
31f00 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ning..**.** The 
31f10 74 79 70 65 64 65 66 20 69 73 20 6e 65 63 65 73  typedef is neces
31f20 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f  sary to work aro
31f30 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20  und problems in 
31f40 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63  certain.** C++ c
31f50 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 20 74  ompilers.  See t
31f60 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a  icket #2191..*/.
31f70 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73  typedef void (*s
31f80 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
31f90 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a  r_type)(void*);.
31fa0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
31fb0 54 41 54 49 43 20 20 20 20 20 20 28 28 73 71 6c  TATIC      ((sql
31fc0 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f  ite3_destructor_
31fd0 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20  type)0).#define 
31fe0 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
31ff0 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73     ((sqlite3_des
32000 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29  tructor_type)-1)
32010 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
32020 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20 52 65  : Setting The Re
32030 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46  sult Of An SQL F
32040 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68  unction.**.** Th
32050 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
32060 20 75 73 65 64 20 62 79 20 74 68 65 20 78 46 75   used by the xFu
32070 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c  nc or xFinal cal
32080 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69  lbacks that.** i
32090 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e  mplement SQL fun
320a0 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
320b0 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b  gates.  See.** [
320c0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
320d0 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  unction()] and [
320e0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
320f0 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20  unction16()].** 
32100 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
32110 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
32120 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
32130 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68  s work very much
32140 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d   like the [param
32150 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61  eter binding] fa
32160 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74  mily of.** funct
32170 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e  ions used to bin
32180 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74  d values to host
32190 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70   parameters in p
321a0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
321b0 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20  ts..** Refer to 
321c0 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74  the [SQL paramet
321d0 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  er] documentatio
321e0 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  n for additional
321f0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
32200 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
32210 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69  _result_blob() i
32220 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
32230 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a  e result from.**
32240 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
32250 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
32260 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20   to be the BLOB 
32270 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73  whose content is
32280 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62   pointed.** to b
32290 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  y the second par
322a0 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63 68  ameter and which
322b0 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67   is N bytes long
322c0 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a   where N is the.
322d0 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  ** third paramet
322e0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
322f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65  qlite3_result_ze
32300 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61  roblob() interfa
32310 63 65 73 20 73 65 74 20 74 68 65 20 72 65 73 75  ces set the resu
32320 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70  lt of.** the app
32330 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
32340 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
32350 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e  a BLOB containin
32360 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79  g all zero.** by
32370 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20  tes and N bytes 
32380 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e  in size, where N
32390 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
323a0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
323b0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
323c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f  qlite3_result_do
323d0 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  uble() interface
323e0 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74   sets the result
323f0 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c   from.** an appl
32400 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
32410 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
32420 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
32430 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a  value specified.
32440 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 72  ** by its 2nd ar
32450 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gument..**.** ^T
32460 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
32470 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71  t_error() and sq
32480 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
32490 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73  or16() functions
324a0 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d  .** cause the im
324b0 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75  plemented SQL fu
324c0 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20  nction to throw 
324d0 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a  an exception..**
324e0 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68   ^SQLite uses th
324f0 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64  e string pointed
32500 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e   to by the.** 2n
32510 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73  d parameter of s
32520 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
32530 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ror() or sqlite3
32540 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
32550 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74  ).** as the text
32560 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73   of an error mes
32570 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 20 69  sage.  ^SQLite i
32580 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 65 72  nterprets the er
32590 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73  ror.** message s
325a0 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74  tring from sqlit
325b0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
325c0 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c  ) as UTF-8. ^SQL
325d0 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74  ite.** interpret
325e0 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f  s the string fro
325f0 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  m sqlite3_result
32600 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 55 54  _error16() as UT
32610 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a  F-16 in native.*
32620 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20 5e  * byte order.  ^
32630 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72  If the third par
32640 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
32650 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
32660 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
32670 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
32680 69 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  is negative then
32690 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73   SQLite takes as
326a0 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65   the error.** me
326b0 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75  ssage all text u
326c0 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69  p through the fi
326d0 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74  rst zero charact
326e0 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74  er..** ^If the t
326f0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
32700 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
32710 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73  _error() or.** s
32720 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
32730 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e  ror16() is non-n
32740 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c  egative then SQL
32750 69 74 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d  ite takes that m
32760 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f  any.** bytes (no
32770 74 20 63 68 61 72 61 63 74 65 72 73 29 20 66 72  t characters) fr
32780 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  om the 2nd param
32790 65 74 65 72 20 61 73 20 74 68 65 20 65 72 72 6f  eter as the erro
327a0 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54  r message..** ^T
327b0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
327c0 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71  t_error() and sq
327d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
327e0 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  or16().** routin
327f0 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74  es make a privat
32800 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72  e copy of the er
32810 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74  ror message text
32820 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20   before.** they 
32830 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20  return.  Hence, 
32840 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63  the calling func
32850 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63  tion can dealloc
32860 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79  ate or.** modify
32870 20 74 68 65 20 74 65 78 74 20 61 66 74 65 72 20   the text after 
32880 74 68 65 79 20 72 65 74 75 72 6e 20 77 69 74 68  they return with
32890 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68  out harm..** ^Th
328a0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
328b0 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75  _error_code() fu
328c0 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74  nction changes t
328d0 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a  he error code.**
328e0 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c   returned by SQL
328f0 69 74 65 20 61 73 20 61 20 72 65 73 75 6c 74 20  ite as a result 
32900 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61  of an error in a
32910 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20   function.  ^By 
32920 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20  default,.** the 
32930 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51  error code is SQ
32940 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20  LITE_ERROR.  ^A 
32950 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20  subsequent call 
32960 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  to sqlite3_resul
32970 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20  t_error().** or 
32980 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
32990 72 72 6f 72 31 36 28 29 20 72 65 73 65 74 73 20  rror16() resets 
329a0 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74  the error code t
329b0 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a  o SQLITE_ERROR..
329c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
329d0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
329e0 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66 61  toobig() interfa
329f0 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65  ce causes SQLite
32a00 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20   to throw an.** 
32a10 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e 67  error indicating
32a20 20 74 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f   that a string o
32a30 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f 20 6c 6f  r BLOB is too lo
32a40 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e 74 2e  ng to represent.
32a50 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
32a60 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
32a70 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61  _nomem() interfa
32a80 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65  ce causes SQLite
32a90 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20   to throw an.** 
32aa0 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e 67  error indicating
32ab0 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61   that a memory a
32ac0 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64  llocation failed
32ad0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
32ae0 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28  ite3_result_int(
32af0 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
32b00 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
32b10 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c  e.** of the appl
32b20 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
32b30 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74  function to be t
32b40 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64  he 32-bit signed
32b50 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75   integer.** valu
32b60 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32  e given in the 2
32b70 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  nd argument..** 
32b80 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
32b90 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65  ult_int64() inte
32ba0 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
32bb0 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f  eturn value.** o
32bc0 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
32bd0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
32be0 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d  on to be the 64-
32bf0 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
32c00 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65  er.** value give
32c10 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67  n in the 2nd arg
32c20 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ument..**.** ^Th
32c30 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
32c40 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63  _null() interfac
32c50 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72  e sets the retur
32c60 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68  n value.** of th
32c70 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
32c80 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
32c90 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  o be NULL..**.**
32ca0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
32cb0 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c  sult_text(), sql
32cc0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
32cd0 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  16(),.** sqlite3
32ce0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65  _result_text16le
32cf0 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  (), and sqlite3_
32d00 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28  result_text16be(
32d10 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
32d20 73 65 74 20 74 68 65 20 72 65 74 75 72 6e 20 76  set the return v
32d30 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c  alue of the appl
32d40 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
32d50 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a  function to be.*
32d60 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20  * a text string 
32d70 77 68 69 63 68 20 69 73 20 72 65 70 72 65 73 65  which is represe
32d80 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55  nted as UTF-8, U
32d90 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74  TF-16 native byt
32da0 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d  e order,.** UTF-
32db0 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e  16 little endian
32dc0 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20  , or UTF-16 big 
32dd0 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69  endian, respecti
32de0 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  vely..** ^SQLite
32df0 20 74 61 6b 65 73 20 74 68 65 20 74 65 78 74 20   takes the text 
32e00 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20  result from the 
32e10 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d  application from
32e20 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61  .** the 2nd para
32e30 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c  meter of the sql
32e40 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
32e50 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a  * interfaces..**
32e60 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72   ^If the 3rd par
32e70 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
32e80 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
32e90 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
32ea0 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
32eb0 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
32ec0 72 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d  result text from
32ed0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
32ee0 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68  er.** through th
32ef0 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61  e first zero cha
32f00 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74  racter..** ^If t
32f10 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
32f20 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
32f30 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
32f40 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f  erfaces.** is no
32f50 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  n-negative, then
32f60 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28   as many bytes (
32f70 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20  not characters) 
32f80 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70  of the text.** p
32f90 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65  ointed to by the
32fa0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
32fb0 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20  re taken as the 
32fc0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
32fd0 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ned.** function 
32fe0 72 65 73 75 6c 74 2e 20 20 49 66 20 74 68 65 20  result.  If the 
32ff0 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  3rd parameter is
33000 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
33010 68 65 6e 20 69 74 0a 2a 2a 20 6d 75 73 74 20 62  hen it.** must b
33020 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73 65  e the byte offse
33030 74 20 69 6e 74 6f 20 74 68 65 20 73 74 72 69 6e  t into the strin
33040 67 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20  g where the NUL 
33050 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64  terminator would
33060 0a 2a 2a 20 61 70 70 65 61 72 20 69 66 20 74 68  .** appear if th
33070 65 20 73 74 72 69 6e 67 20 77 68 65 72 65 20 4e  e string where N
33080 55 4c 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  UL terminated.  
33090 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61  If any NUL chara
330a0 63 74 65 72 73 20 6f 63 63 75 72 0a 2a 2a 20 69  cters occur.** i
330b0 6e 20 74 68 65 20 73 74 72 69 6e 67 20 61 74 20  n the string at 
330c0 61 20 62 79 74 65 20 6f 66 66 73 65 74 20 74 68  a byte offset th
330d0 61 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  at is less than 
330e0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
330f0 20 33 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65   3rd.** paramete
33100 72 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  r, then the resu
33110 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 77 69 6c  lting string wil
33120 6c 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64  l contain embedd
33130 65 64 20 4e 55 4c 73 20 61 6e 64 20 74 68 65 0a  ed NULs and the.
33140 2a 2a 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70  ** result of exp
33150 72 65 73 73 69 6f 6e 73 20 6f 70 65 72 61 74 69  ressions operati
33160 6e 67 20 6f 6e 20 73 74 72 69 6e 67 73 20 77 69  ng on strings wi
33170 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73  th embedded NULs
33180 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
33190 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61  * ^If the 4th pa
331a0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
331b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
331c0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
331d0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
331e0 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f  ult_blob is a no
331f0 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  n-NULL pointer, 
33200 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c  then SQLite call
33210 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69  s that.** functi
33220 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74 72 75  on as the destru
33230 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74  ctor on the text
33240 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20   or BLOB result 
33250 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66  when it has.** f
33260 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68  inished using th
33270 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49  at result..** ^I
33280 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
33290 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
332a0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
332b0 69 6e 74 65 72 66 61 63 65 73 20 6f 72 20 74 6f  interfaces or to
332c0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
332d0 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73  lt_blob is the s
332e0 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20  pecial constant 
332f0 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74  SQLITE_STATIC, t
33300 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73  hen SQLite.** as
33310 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 74  sumes that the t
33320 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75  ext or BLOB resu
33330 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e  lt is in constan
33340 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73  t space and does
33350 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65   not.** copy the
33360 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
33370 70 61 72 61 6d 65 74 65 72 20 6e 6f 72 20 63 61  parameter nor ca
33380 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  ll a destructor 
33390 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a  on the content.*
333a0 2a 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69  * when it has fi
333b0 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61  nished using tha
333c0 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66  t result..** ^If
333d0 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
333e0 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
333f0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
33400 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20  nterfaces.** or 
33410 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
33420 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69  lob is the speci
33430 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49  al constant SQLI
33440 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20  TE_TRANSIENT.** 
33450 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65  then SQLite make
33460 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
33470 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63  result into spac
33480 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a  e obtained from.
33490 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
334a0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72  _malloc()] befor
334b0 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  e it returns..**
334c0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
334d0 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
334e0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
334f0 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20  he result of.** 
33500 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
33510 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
33520 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68   to be a copy th
33530 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65  e.** [unprotecte
33540 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
33550 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65   object specifie
33560 64 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72  d by the 2nd par
33570 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a  ameter.  ^The.**
33580 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33590 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63  value() interfac
335a0 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
335b0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  f the [sqlite3_v
335c0 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74  alue].** so that
335d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
335e0 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64 20 69  lue] specified i
335f0 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  n the parameter 
33600 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a  may change or.**
33610 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
33620 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65  after sqlite3_re
33630 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74  sult_value() ret
33640 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72  urns without har
33650 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63  m..** ^A [protec
33660 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
33670 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c  e] object may al
33680 77 61 79 73 20 62 65 20 75 73 65 64 20 77 68 65  ways be used whe
33690 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74  re an.** [unprot
336a0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
336b0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72  lue] object is r
336c0 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68  equired, so eith
336d0 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73  er.** kind of [s
336e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
336f0 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73 65 64  ject can be used
33700 20 77 69 74 68 20 74 68 69 73 20 69 6e 74 65 72   with this inter
33710 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  face..**.** If t
33720 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
33730 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69  e called from wi
33740 74 68 69 6e 20 74 68 65 20 64 69 66 66 65 72 65  thin the differe
33750 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61  nt thread.** tha
33760 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69  n the one contai
33770 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61  ning the applica
33780 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
33790 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69  ction that recei
337a0 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  ved.** the [sqli
337b0 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69  te3_context] poi
337c0 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74  nter, the result
337d0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
337e0 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
337f0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c  _result_blob(sql
33800 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
33810 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
33820 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
33830 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
33840 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c  esult_double(sql
33850 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64  ite3_context*, d
33860 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c  ouble);.void sql
33870 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
33880 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  r(sqlite3_contex
33890 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  t*, const char*,
338a0 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
338b0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
338c0 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  16(sqlite3_conte
338d0 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
338e0 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
338f0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
33900 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33  r_toobig(sqlite3
33910 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64  _context*);.void
33920 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33930 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69  error_nomem(sqli
33940 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76  te3_context*);.v
33950 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
33960 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71  lt_error_code(sq
33970 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
33980 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
33990 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71  e3_result_int(sq
339a0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
339b0 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
339c0 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28  e3_result_int64(
339d0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
339e0 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
339f0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
33a00 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74  esult_null(sqlit
33a10 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f  e3_context*);.vo
33a20 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
33a30 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63  t_text(sqlite3_c
33a40 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63  ontext*, const c
33a50 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  har*, int, void(
33a60 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
33a70 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33a80 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63  text16(sqlite3_c
33a90 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
33aa0 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
33ab0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
33ac0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33ad0 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33  text16le(sqlite3
33ae0 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
33af0 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64   void*, int,void
33b00 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
33b10 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
33b20 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65  _text16be(sqlite
33b30 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
33b40 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69  t void*, int,voi
33b50 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
33b60 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
33b70 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  t_value(sqlite3_
33b80 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65  context*, sqlite
33b90 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20  3_value*);.void 
33ba0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a  sqlite3_result_z
33bb0 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  eroblob(sqlite3_
33bc0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29  context*, int n)
33bd0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
33be0 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f  F: Define New Co
33bf0 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65  llating Sequence
33c00 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66  s.**.** ^These f
33c10 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c 20 72 65  unctions add, re
33c20 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 66 79 20  move, or modify 
33c30 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61 73  a [collation] as
33c40 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68  sociated.** with
33c50 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
33c60 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69  onnection] speci
33c70 66 69 65 64 20 61 73 20 74 68 65 20 66 69 72 73  fied as the firs
33c80 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  t argument..**.*
33c90 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74  * ^The name of t
33ca0 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20  he collation is 
33cb0 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a  a UTF-8 string.*
33cc0 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  * for sqlite3_cr
33cd0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
33ce0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65   and sqlite3_cre
33cf0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
33d00 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d  ().** and a UTF-
33d10 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74  16 string in nat
33d20 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 66  ive byte order f
33d30 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
33d40 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e  e_collation16().
33d50 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20 6e  .** ^Collation n
33d60 61 6d 65 73 20 74 68 61 74 20 63 6f 6d 70 61 72  ames that compar
33d70 65 20 65 71 75 61 6c 20 61 63 63 6f 72 64 69 6e  e equal accordin
33d80 67 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  g to [sqlite3_st
33d90 72 6e 69 63 6d 70 28 29 5d 20 61 72 65 0a 2a 2a  rnicmp()] are.**
33da0 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 62   considered to b
33db0 65 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e  e the same name.
33dc0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 74 68 69  .**.** ^(The thi
33dd0 72 64 20 61 72 67 75 6d 65 6e 74 20 28 65 54 65  rd argument (eTe
33de0 78 74 52 65 70 29 20 6d 75 73 74 20 62 65 20 6f  xtRep) must be o
33df0 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61  ne of the consta
33e00 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  nts:.** <ul>.** 
33e10 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46  <li> [SQLITE_UTF
33e20 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  8],.** <li> [SQL
33e30 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a 2a  ITE_UTF16LE],.**
33e40 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54   <li> [SQLITE_UT
33e50 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  F16BE],.** <li> 
33e60 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20  [SQLITE_UTF16], 
33e70 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  or.** <li> [SQLI
33e80 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44  TE_UTF16_ALIGNED
33e90 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  ]..** </ul>)^.**
33ea0 20 5e 54 68 65 20 65 54 65 78 74 52 65 70 20 61   ^The eTextRep a
33eb0 72 67 75 6d 65 6e 74 20 64 65 74 65 72 6d 69 6e  rgument determin
33ec0 65 73 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  es the encoding 
33ed0 6f 66 20 73 74 72 69 6e 67 73 20 70 61 73 73 65  of strings passe
33ee0 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6c 6c  d.** to the coll
33ef0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63  ating function c
33f00 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c 6c 62 61  allback, xCallba
33f10 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  ck..** ^The [SQL
33f20 49 54 45 5f 55 54 46 31 36 5d 20 61 6e 64 20 5b  ITE_UTF16] and [
33f30 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49  SQLITE_UTF16_ALI
33f40 47 4e 45 44 5d 20 76 61 6c 75 65 73 20 66 6f 72  GNED] values for
33f50 20 65 54 65 78 74 52 65 70 0a 2a 2a 20 66 6f 72   eTextRep.** for
33f60 63 65 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65  ce strings to be
33f70 20 55 54 46 31 36 20 77 69 74 68 20 6e 61 74 69   UTF16 with nati
33f80 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
33f90 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55  * ^The [SQLITE_U
33fa0 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61  TF16_ALIGNED] va
33fb0 6c 75 65 20 66 6f 72 20 65 54 65 78 74 52 65 70  lue for eTextRep
33fc0 20 66 6f 72 63 65 73 20 73 74 72 69 6e 67 73 20   forces strings 
33fd0 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20 61  to begin.** on a
33fe0 6e 20 65 76 65 6e 20 62 79 74 65 20 61 64 64 72  n even byte addr
33ff0 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ess..**.** ^The 
34000 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c  fourth argument,
34010 20 70 41 72 67 2c 20 69 73 20 61 6e 20 61 70 70   pArg, is an app
34020 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
34030 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 70 61  inter that is pa
34040 73 73 65 64 0a 2a 2a 20 74 68 72 6f 75 67 68 20  ssed.** through 
34050 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
34060 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 6f 6c  ument to the col
34070 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
34080 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  callback..**.** 
34090 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d  ^The fifth argum
340a0 65 6e 74 2c 20 78 43 61 6c 6c 62 61 63 6b 2c 20  ent, xCallback, 
340b0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
340c0 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  the collating fu
340d0 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74  nction..** ^Mult
340e0 69 70 6c 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66  iple collating f
340f0 75 6e 63 74 69 6f 6e 73 20 63 61 6e 20 62 65 20  unctions can be 
34100 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67  registered using
34110 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62   the same name b
34120 75 74 0a 2a 2a 20 77 69 74 68 20 64 69 66 66 65  ut.** with diffe
34130 72 65 6e 74 20 65 54 65 78 74 52 65 70 20 70 61  rent eTextRep pa
34140 72 61 6d 65 74 65 72 73 20 61 6e 64 20 53 51 4c  rameters and SQL
34150 69 74 65 20 77 69 6c 6c 20 75 73 65 20 77 68 69  ite will use whi
34160 63 68 65 76 65 72 0a 2a 2a 20 66 75 6e 63 74 69  chever.** functi
34170 6f 6e 20 72 65 71 75 69 72 65 73 20 74 68 65 20  on requires the 
34180 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20  least amount of 
34190 64 61 74 61 20 74 72 61 6e 73 66 6f 72 6d 61 74  data transformat
341a0 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ion..** ^If the 
341b0 78 43 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65  xCallback argume
341c0 6e 74 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20  nt is NULL then 
341d0 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  the collating fu
341e0 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 6c  nction is.** del
341f0 65 74 65 64 2e 20 20 5e 57 68 65 6e 20 61 6c 6c  eted.  ^When all
34200 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
34210 69 6f 6e 73 20 68 61 76 69 6e 67 20 74 68 65 20  ions having the 
34220 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 64 65  same name are de
34230 6c 65 74 65 64 2c 0a 2a 2a 20 74 68 61 74 20 63  leted,.** that c
34240 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 20 6c  ollation is no l
34250 6f 6e 67 65 72 20 75 73 61 62 6c 65 2e 0a 2a 2a  onger usable..**
34260 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c 61 74 69  .** ^The collati
34270 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c  ng function call
34280 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
34290 77 69 74 68 20 61 20 63 6f 70 79 20 6f 66 20 74  with a copy of t
342a0 68 65 20 70 41 72 67 20 0a 2a 2a 20 61 70 70 6c  he pArg .** appl
342b0 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
342c0 6e 74 65 72 20 61 6e 64 20 77 69 74 68 20 74 77  nter and with tw
342d0 6f 20 73 74 72 69 6e 67 73 20 69 6e 20 74 68 65  o strings in the
342e0 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66   encoding specif
342f0 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 65 54  ied.** by the eT
34300 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74 2e  extRep argument.
34310 20 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20    The collating 
34320 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 72 65  function must re
34330 74 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65 67  turn an.** integ
34340 65 72 20 74 68 61 74 20 69 73 20 6e 65 67 61 74  er that is negat
34350 69 76 65 2c 20 7a 65 72 6f 2c 20 6f 72 20 70 6f  ive, zero, or po
34360 73 69 74 69 76 65 0a 2a 2a 20 69 66 20 74 68 65  sitive.** if the
34370 20 66 69 72 73 74 20 73 74 72 69 6e 67 20 69 73   first string is
34380 20 6c 65 73 73 20 74 68 61 6e 2c 20 65 71 75 61   less than, equa
34390 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72  l to, or greater
343a0 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64   than the second
343b0 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c  ,.** respectivel
343c0 79 2e 20 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20  y.  A collating 
343d0 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 61 6c  function must al
343e0 77 61 79 73 20 72 65 74 75 72 6e 20 74 68 65 20  ways return the 
343f0 73 61 6d 65 20 61 6e 73 77 65 72 0a 2a 2a 20 67  same answer.** g
34400 69 76 65 6e 20 74 68 65 20 73 61 6d 65 20 69 6e  iven the same in
34410 70 75 74 73 2e 20 20 49 66 20 74 77 6f 20 6f 72  puts.  If two or
34420 20 6d 6f 72 65 20 63 6f 6c 6c 61 74 69 6e 67 20   more collating 
34430 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 72 65  functions are re
34440 67 69 73 74 65 72 65 64 0a 2a 2a 20 74 6f 20 74  gistered.** to t
34450 68 65 20 73 61 6d 65 20 63 6f 6c 6c 61 74 69 6f  he same collatio
34460 6e 20 6e 61 6d 65 20 28 75 73 69 6e 67 20 64 69  n name (using di
34470 66 66 65 72 65 6e 74 20 65 54 65 78 74 52 65 70  fferent eTextRep
34480 20 76 61 6c 75 65 73 29 20 74 68 65 6e 20 61 6c   values) then al
34490 6c 0a 2a 2a 20 6d 75 73 74 20 67 69 76 65 20 61  l.** must give a
344a0 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 73  n equivalent ans
344b0 77 65 72 20 77 68 65 6e 20 69 6e 76 6f 6b 65 64  wer when invoked
344c0 20 77 69 74 68 20 65 71 75 69 76 61 6c 65 6e 74   with equivalent
344d0 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65   strings..** The
344e0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
344f0 69 6f 6e 20 6d 75 73 74 20 6f 62 65 79 20 74 68  ion must obey th
34500 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f 70  e following prop
34510 65 72 74 69 65 73 20 66 6f 72 20 61 6c 6c 0a 2a  erties for all.*
34520 2a 20 73 74 72 69 6e 67 73 20 41 2c 20 42 2c 20  * strings A, B, 
34530 61 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c  and C:.**.** <ol
34540 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d  >.** <li> If A==
34550 42 20 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a 20  B then B==A..** 
34560 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 61 6e 64  <li> If A==B and
34570 20 42 3d 3d 43 20 74 68 65 6e 20 41 3d 3d 43 2e   B==C then A==C.
34580 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74  .** <li> If A&lt
34590 3b 42 20 54 48 45 4e 20 42 26 67 74 3b 41 2e 0a  ;B THEN B&gt;A..
345a0 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b  ** <li> If A&lt;
345b0 42 20 61 6e 64 20 42 26 6c 74 3b 43 20 74 68 65  B and B&lt;C the
345c0 6e 20 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f  n A&lt;C..** </o
345d0 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 6f  l>.**.** If a co
345e0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
345f0 20 66 61 69 6c 73 20 61 6e 79 20 6f 66 20 74 68   fails any of th
34600 65 20 61 62 6f 76 65 20 63 6f 6e 73 74 72 61 69  e above constrai
34610 6e 74 73 20 61 6e 64 20 74 68 61 74 0a 2a 2a 20  nts and that.** 
34620 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
34630 6f 6e 20 69 73 20 20 72 65 67 69 73 74 65 72 65  on is  registere
34640 64 20 61 6e 64 20 75 73 65 64 2c 20 74 68 65 6e  d and used, then
34650 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
34660 20 53 51 4c 69 74 65 0a 2a 2a 20 69 73 20 75 6e   SQLite.** is un
34670 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
34680 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  The sqlite3_crea
34690 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
346a0 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c  ) works like sql
346b0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
346c0 61 74 69 6f 6e 28 29 0a 2a 2a 20 77 69 74 68 20  ation().** with 
346d0 74 68 65 20 61 64 64 69 74 69 6f 6e 20 74 68 61  the addition tha
346e0 74 20 74 68 65 20 78 44 65 73 74 72 6f 79 20 63  t the xDestroy c
346f0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
34700 65 64 20 6f 6e 20 70 41 72 67 20 77 68 65 6e 0a  ed on pArg when.
34710 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67  ** the collating
34720 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c   function is del
34730 65 74 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74  eted..** ^Collat
34740 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  ing functions ar
34750 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74  e deleted when t
34760 68 65 79 20 61 72 65 20 6f 76 65 72 72 69 64 64  hey are overridd
34770 65 6e 20 62 79 20 6c 61 74 65 72 0a 2a 2a 20 63  en by later.** c
34780 61 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c 6c  alls to the coll
34790 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66  ation creation f
347a0 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e  unctions or when
347b0 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73   the.** [databas
347c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73  e connection] is
347d0 20 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73   closed using [s
347e0 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e  qlite3_close()].
347f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 44 65 73  .**.** ^The xDes
34800 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  troy callback is
34810 20 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c 6c   <u>not</u> call
34820 65 64 20 69 66 20 74 68 65 20 0a 2a 2a 20 73 71  ed if the .** sq
34830 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
34840 6c 61 74 69 6f 6e 5f 76 32 28 29 20 66 75 6e 63  lation_v2() func
34850 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 41 70 70  tion fails.  App
34860 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 69  lications that i
34870 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
34880 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
34890 6e 5f 76 32 28 29 20 77 69 74 68 20 61 20 6e 6f  n_v2() with a no
348a0 6e 2d 4e 55 4c 4c 20 78 44 65 73 74 72 6f 79 20  n-NULL xDestroy 
348b0 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
348c0 0a 2a 2a 20 63 68 65 63 6b 20 74 68 65 20 72 65  .** check the re
348d0 74 75 72 6e 20 63 6f 64 65 20 61 6e 64 20 64 69  turn code and di
348e0 73 70 6f 73 65 20 6f 66 20 74 68 65 20 61 70 70  spose of the app
348f0 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
34900 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6d 73 65 6c  inter.** themsel
34910 76 65 73 20 72 61 74 68 65 72 20 74 68 61 6e 20  ves rather than 
34920 65 78 70 65 63 74 69 6e 67 20 53 51 4c 69 74 65  expecting SQLite
34930 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20 69 74   to deal with it
34940 20 66 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20 54 68   for them..** Th
34950 69 73 20 69 73 20 64 69 66 66 65 72 65 6e 74 20  is is different 
34960 66 72 6f 6d 20 65 76 65 72 79 20 6f 74 68 65 72  from every other
34970 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
34980 65 2e 20 20 54 68 65 20 69 6e 63 6f 6e 73 69 73  e.  The inconsis
34990 74 65 6e 63 79 20 0a 2a 2a 20 69 73 20 75 6e 66  tency .** is unf
349a0 6f 72 74 75 6e 61 74 65 20 62 75 74 20 63 61 6e  ortunate but can
349b0 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20 77  not be changed w
349c0 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20  ithout breaking 
349d0 62 61 63 6b 77 61 72 64 73 20 0a 2a 2a 20 63 6f  backwards .** co
349e0 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a  mpatibility..**.
349f0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 73  ** See also:  [s
34a00 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
34a10 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 20 5b  _needed()] and [
34a20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
34a30 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a  n_needed16()]..*
34a40 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  /.int sqlite3_cr
34a50 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a  eate_collation(.
34a60 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63    sqlite3*, .  c
34a70 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
34a80 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  , .  int eTextRe
34a90 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67  p, .  void *pArg
34aa0 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72  ,.  int(*xCompar
34ab0 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  e)(void*,int,con
34ac0 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  st void*,int,con
34ad0 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74  st void*).);.int
34ae0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
34af0 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20  collation_v2(.  
34b00 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e  sqlite3*, .  con
34b10 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
34b20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
34b30 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a   .  void *pArg,.
34b40 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29    int(*xCompare)
34b50 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
34b60 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74   void*,int,const
34b70 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28   void*),.  void(
34b80 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a  *xDestroy)(void*
34b90 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
34ba0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
34bb0 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  n16(.  sqlite3*,
34bc0 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a   .  const void *
34bd0 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65  zName,.  int eTe
34be0 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a  xtRep, .  void *
34bf0 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f  pArg,.  int(*xCo
34c00 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74  mpare)(void*,int
34c10 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74  ,const void*,int
34c20 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b  ,const void*).);
34c30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
34c40 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64  : Collation Need
34c50 65 64 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a  ed Callbacks.**.
34c60 2a 2a 20 5e 54 6f 20 61 76 6f 69 64 20 68 61 76  ** ^To avoid hav
34c70 69 6e 67 20 74 6f 20 72 65 67 69 73 74 65 72 20  ing to register 
34c80 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  all collation se
34c90 71 75 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61  quences before a
34ca0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e   database.** can
34cb0 20 62 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67   be used, a sing
34cc0 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  le callback func
34cd0 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69  tion may be regi
34ce0 73 74 65 72 65 64 20 77 69 74 68 20 74 68 65 0a  stered with the.
34cf0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
34d00 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20 69  nection] to be i
34d10 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20  nvoked whenever 
34d20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c  an undefined col
34d30 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e  lation.** sequen
34d40 63 65 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a  ce is required..
34d50 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 75  **.** ^If the fu
34d60 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73 74  nction is regist
34d70 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 73  ered using the s
34d80 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
34d90 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a 2a  _needed() API,.*
34da0 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70 61 73  * then it is pas
34db0 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f 66  sed the names of
34dc0 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61   undefined colla
34dd0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 61  tion sequences a
34de0 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63  s strings.** enc
34df0 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 5e  oded in UTF-8. ^
34e00 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  If sqlite3_colla
34e10 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20  tion_needed16() 
34e20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20  is used,.** the 
34e30 6e 61 6d 65 73 20 61 72 65 20 70 61 73 73 65 64  names are passed
34e40 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61   as UTF-16 in ma
34e50 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74  chine native byt
34e60 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41 20 63  e order..** ^A c
34e70 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 66 75  all to either fu
34e80 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20  nction replaces 
34e90 74 68 65 20 65 78 69 73 74 69 6e 67 20 63 6f 6c  the existing col
34ea0 6c 61 74 69 6f 6e 2d 6e 65 65 64 65 64 20 63 61  lation-needed ca
34eb0 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28  llback..**.** ^(
34ec0 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
34ed0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68  k is invoked, th
34ee0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
34ef0 20 70 61 73 73 65 64 20 69 73 20 61 20 63 6f 70   passed is a cop
34f00 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 6f  y.** of the seco
34f10 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  nd argument to s
34f20 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
34f30 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20  _needed() or.** 
34f40 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
34f50 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 20 54  n_needed16().  T
34f60 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
34f70 6e 74 20 69 73 20 74 68 65 20 64 61 74 61 62 61  nt is the databa
34f80 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
34f90 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67  .  The third arg
34fa0 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20  ument is one of 
34fb0 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b  [SQLITE_UTF8], [
34fc0 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c  SQLITE_UTF16BE],
34fd0 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  .** or [SQLITE_U
34fe0 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74  TF16LE], indicat
34ff0 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 65 73  ing the most des
35000 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74  irable form of t
35010 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20  he collation.** 
35020 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69 6f  sequence functio
35030 6e 20 72 65 71 75 69 72 65 64 2e 20 20 54 68 65  n required.  The
35040 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
35050 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  r is the name of
35060 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64   the.** required
35070 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
35080 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  nce.)^.**.** The
35090 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
350a0 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74  on should regist
350b0 65 72 20 74 68 65 20 64 65 73 69 72 65 64 20 63  er the desired c
350c0 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a  ollation using.*
350d0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  * [sqlite3_creat
350e0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20  e_collation()], 
350f0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
35100 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20  collation16()], 
35110 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  or.** [sqlite3_c
35120 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
35130 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  v2()]..*/.int sq
35140 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
35150 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74 65  needed(.  sqlite
35160 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20  3*, .  void*, . 
35170 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73   void(*)(void*,s
35180 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78  qlite3*,int eTex
35190 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a  tRep,const char*
351a0 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
351b0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
351c0 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  d16(.  sqlite3*,
351d0 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69   .  void*,.  voi
351e0 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
351f0 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70  e3*,int eTextRep
35200 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b  ,const void*).);
35210 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  ..#ifdef SQLITE_
35220 48 41 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a 20  HAS_CODEC./*.** 
35230 53 70 65 63 69 66 79 20 74 68 65 20 6b 65 79 20  Specify the key 
35240 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74 65 64  for an encrypted
35250 20 64 61 74 61 62 61 73 65 2e 20 20 54 68 69 73   database.  This
35260 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20   routine should 
35270 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67  be.** called rig
35280 68 74 20 61 66 74 65 72 20 73 71 6c 69 74 65 33  ht after sqlite3
35290 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54  _open()..**.** T
352a0 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65  he code to imple
352b0 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73  ment this API is
352c0 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69   not available i
352d0 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c  n the public rel
352e0 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ease.** of SQLit
352f0 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
35300 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33  3_key(.  sqlite3
35310 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
35320 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
35330 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65  ase to be rekeye
35340 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  d */.  const voi
35350 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65  d *pKey, int nKe
35360 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79  y     /* The key
35370 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68   */.);../*.** Ch
35380 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f 6e 20  ange the key on 
35390 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  an open database
353a0 2e 20 20 49 66 20 74 68 65 20 63 75 72 72 65 6e  .  If the curren
353b0 74 20 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f  t database is no
353c0 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c 20  t.** encrypted, 
353d0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c  this routine wil
353e0 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20 20 49  l encrypt it.  I
353f0 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65  f pNew==0 or nNe
35400 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74  w==0, the.** dat
35410 61 62 61 73 65 20 69 73 20 64 65 63 72 79 70 74  abase is decrypt
35420 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ed..**.** The co
35430 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  de to implement 
35440 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20  this API is not 
35450 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65  available in the
35460 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a   public release.
35470 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  ** of SQLite..*/
35480 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b  .int sqlite3_rek
35490 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  ey(.  sqlite3 *d
354a0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  b,              
354b0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
354c0 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a   to be rekeyed *
354d0 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
354e0 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20  pKey, int nKey  
354f0 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65     /* The new ke
35500 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53  y */.);../*.** S
35510 70 65 63 69 66 79 20 74 68 65 20 61 63 74 69 76  pecify the activ
35520 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20  ation key for a 
35530 53 45 45 20 64 61 74 61 62 61 73 65 2e 20 20 55  SEE database.  U
35540 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61  nless .** activa
35550 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65  ted, none of the
35560 20 53 45 45 20 72 6f 75 74 69 6e 65 73 20 77 69   SEE routines wi
35570 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64  ll work..*/.void
35580 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74   sqlite3_activat
35590 65 5f 73 65 65 28 0a 20 20 63 6f 6e 73 74 20 63  e_see(.  const c
355a0 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65  har *zPassPhrase
355b0 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76          /* Activ
355c0 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a  ation phrase */.
355d0 29 3b 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64 65  );.#endif..#ifde
355e0 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f  f SQLITE_ENABLE_
355f0 43 45 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63  CEROD./*.** Spec
35600 69 66 79 20 74 68 65 20 61 63 74 69 76 61 74 69  ify the activati
35610 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 43 45 52  on key for a CER
35620 4f 44 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e  OD database.  Un
35630 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74  less .** activat
35640 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20  ed, none of the 
35650 43 45 52 4f 44 20 72 6f 75 74 69 6e 65 73 20 77  CEROD routines w
35660 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69  ill work..*/.voi
35670 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61  d sqlite3_activa
35680 74 65 5f 63 65 72 6f 64 28 0a 20 20 63 6f 6e 73  te_cerod(.  cons
35690 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72  t char *zPassPhr
356a0 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63  ase        /* Ac
356b0 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20  tivation phrase 
356c0 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a  */.);.#endif../*
356d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75  .** CAPI3REF: Su
356e0 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20  spend Execution 
356f0 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65  For A Short Time
35700 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
35710 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74  e3_sleep() funct
35720 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65 20 63  ion causes the c
35730 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f  urrent thread to
35740 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74 69   suspend executi
35750 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61  on.** for at lea
35760 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d  st a number of m
35770 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63  illiseconds spec
35780 69 66 69 65 64 20 69 6e 20 69 74 73 20 70 61 72  ified in its par
35790 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66  ameter..**.** If
357a0 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
357b0 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73  ystem does not s
357c0 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65 71  upport sleep req
357d0 75 65 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69  uests with.** mi
357e0 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 72  llisecond time r
357f0 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20  esolution, then 
35800 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 65  the time will be
35810 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a   rounded up to.*
35820 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20 73 65  * the nearest se
35830 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65 72  cond. The number
35840 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   of milliseconds
35850 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c   of sleep actual
35860 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20  ly.** requested 
35870 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69  from the operati
35880 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72 65 74  ng system is ret
35890 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51  urned..**.** ^SQ
358a0 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20  Lite implements 
358b0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 62  this interface b
358c0 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53  y calling the xS
358d0 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  leep().** method
358e0 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20   of the default 
358f0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
35900 6a 65 63 74 2e 20 20 49 66 20 74 68 65 20 78 53  ject.  If the xS
35910 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 0a 2a 2a  leep() method.**
35920 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20   of the default 
35930 56 46 53 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65  VFS is not imple
35940 6d 65 6e 74 65 64 20 63 6f 72 72 65 63 74 6c 79  mented correctly
35950 2c 20 6f 72 20 6e 6f 74 20 69 6d 70 6c 65 6d 65  , or not impleme
35960 6e 74 65 64 20 61 74 0a 2a 2a 20 61 6c 6c 2c 20  nted at.** all, 
35970 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
35980 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6c 65  r of sqlite3_sle
35990 65 70 28 29 20 6d 61 79 20 64 65 76 69 61 74 65  ep() may deviate
359a0 20 66 72 6f 6d 20 74 68 65 20 64 65 73 63 72 69   from the descri
359b0 70 74 69 6f 6e 0a 2a 2a 20 69 6e 20 74 68 65 20  ption.** in the 
359c0 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61  previous paragra
359d0 70 68 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  phs..*/.int sqli
359e0 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a  te3_sleep(int);.
359f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
35a00 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c   Name Of The Fol
35a10 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70  der Holding Temp
35a20 6f 72 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a  orary Files.**.*
35a30 2a 20 5e 28 49 66 20 74 68 69 73 20 67 6c 6f 62  * ^(If this glob
35a40 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d  al variable is m
35a50 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
35a60 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69  a string which i
35a70 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66  s.** the name of
35a80 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61   a folder (a.k.a
35a90 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68  . directory), th
35aa0 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79  en all temporary
35ab0 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65   files.** create
35ac0 64 20 62 79 20 53 51 4c 69 74 65 20 77 68 65 6e  d by SQLite when
35ad0 20 75 73 69 6e 67 20 61 20 62 75 69 6c 74 2d 69   using a built-i
35ae0 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c  n [sqlite3_vfs |
35af0 20 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65   VFS].** will be
35b00 20 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20   placed in that 
35b10 64 69 72 65 63 74 6f 72 79 2e 29 5e 20 20 5e 49  directory.)^  ^I
35b20 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a  f this variable.
35b30 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  ** is a NULL poi
35b40 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74  nter, then SQLit
35b50 65 20 70 65 72 66 6f 72 6d 73 20 61 20 73 65 61  e performs a sea
35b60 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f  rch for an appro
35b70 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72  priate.** tempor
35b80 61 72 79 20 66 69 6c 65 20 64 69 72 65 63 74 6f  ary file directo
35b90 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20  ry..**.** It is 
35ba0 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64  not safe to read
35bb0 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20   or modify this 
35bc0 76 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65  variable in more
35bd0 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72   than one.** thr
35be0 65 61 64 20 61 74 20 61 20 74 69 6d 65 2e 20 20  ead at a time.  
35bf0 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
35c00 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79  o read or modify
35c10 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a   this variable.*
35c20 2a 20 69 66 20 61 20 5b 64 61 74 61 62 61 73 65  * if a [database
35c30 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20   connection] is 
35c40 62 65 69 6e 67 20 75 73 65 64 20 61 74 20 74 68  being used at th
35c50 65 20 73 61 6d 65 20 74 69 6d 65 20 69 6e 20 61  e same time in a
35c60 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 74 68 72   separate.** thr
35c70 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e  ead..** It is in
35c80 74 65 6e 64 65 64 20 74 68 61 74 20 74 68 69 73  tended that this
35c90 20 76 61 72 69 61 62 6c 65 20 62 65 20 73 65 74   variable be set
35ca0 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74   once.** as part
35cb0 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74   of process init
35cc0 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62  ialization and b
35cd0 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65  efore any SQLite
35ce0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f   interface.** ro
35cf0 75 74 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e  utines have been
35d00 20 63 61 6c 6c 65 64 20 61 6e 64 20 74 68 61 74   called and that
35d10 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 72   this variable r
35d20 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a  emain unchanged.
35d30 2a 2a 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a  ** thereafter..*
35d40 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74 65 6d 70 5f  *.** ^The [temp_
35d50 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
35d60 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69  pragma] may modi
35d70 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  fy this variable
35d80 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 74   and cause.** it
35d90 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d   to point to mem
35da0 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
35db0 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
35dc0 63 5d 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f 72  c].  ^Furthermor
35dd0 65 2c 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f  e,.** the [temp_
35de0 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
35df0 70 72 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 61  pragma] always a
35e00 73 73 75 6d 65 73 20 74 68 61 74 20 61 6e 79 20  ssumes that any 
35e10 73 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74  string.** that t
35e20 68 69 73 20 76 61 72 69 61 62 6c 65 20 70 6f 69  his variable poi
35e30 6e 74 73 20 74 6f 20 69 73 20 68 65 6c 64 20 69  nts to is held i
35e40 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  n memory obtaine
35e50 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69  d from .** [sqli
35e60 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20  te3_malloc] and 
35e70 74 68 65 20 70 72 61 67 6d 61 20 6d 61 79 20 61  the pragma may a
35e80 74 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74  ttempt to free t
35e90 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73  hat memory.** us
35ea0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  ing [sqlite3_fre
35eb0 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66  e]..** Hence, if
35ec0 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69   this variable i
35ed0 73 20 6d 6f 64 69 66 69 65 64 20 64 69 72 65 63  s modified direc
35ee0 74 6c 79 2c 20 65 69 74 68 65 72 20 69 74 20 73  tly, either it s
35ef0 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65  hould be.** made
35f00 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f   NULL or made to
35f10 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79   point to memory
35f20 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
35f30 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a  sqlite3_malloc].
35f40 2a 2a 20 6f 72 20 65 6c 73 65 20 74 68 65 20 75  ** or else the u
35f50 73 65 20 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f  se of the [temp_
35f60 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
35f70 70 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62  pragma] should b
35f80 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2a 0a 2a 2a  e avoided..**.**
35f90 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64   <b>Note to Wind
35fa0 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72  ows Runtime user
35fb0 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70  s:</b>  The temp
35fc0 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72 79 20  orary directory 
35fd0 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70  must be set.** p
35fe0 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20  rior to calling 
35ff0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5d 20 6f  [sqlite3_open] o
36000 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  r [sqlite3_open_
36010 76 32 5d 2e 20 20 4f 74 68 65 72 77 69 73 65 2c  v2].  Otherwise,
36020 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74   various.** feat
36030 75 72 65 73 20 74 68 61 74 20 72 65 71 75 69 72  ures that requir
36040 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d  e the use of tem
36050 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79  porary files may
36060 20 66 61 69 6c 2e 20 20 48 65 72 65 20 69 73 20   fail.  Here is 
36070 61 6e 0a 2a 2a 20 65 78 61 6d 70 6c 65 20 6f 66  an.** example of
36080 20 68 6f 77 20 74 6f 20 64 6f 20 74 68 69 73 20   how to do this 
36090 75 73 69 6e 67 20 43 2b 2b 20 77 69 74 68 20 74  using C++ with t
360a0 68 65 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69  he Windows Runti
360b0 6d 65 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  me:.**.** <block
360c0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 4c  quote><pre>.** L
360d0 50 43 57 53 54 52 20 7a 50 61 74 68 20 3d 20 57  PCWSTR zPath = W
360e0 69 6e 64 6f 77 73 3a 3a 53 74 6f 72 61 67 65 3a  indows::Storage:
360f0 3a 41 70 70 6c 69 63 61 74 69 6f 6e 44 61 74 61  :ApplicationData
36100 3a 3a 43 75 72 72 65 6e 74 2d 3e 0a 2a 2a 20 26  ::Current->.** &
36110 6e 62 73 70 3b 20 20 20 20 20 54 65 6d 70 6f 72  nbsp;     Tempor
36120 61 72 79 46 6f 6c 64 65 72 2d 3e 50 61 74 68 2d  aryFolder->Path-
36130 3e 44 61 74 61 28 29 3b 0a 2a 2a 20 63 68 61 72  >Data();.** char
36140 20 7a 50 61 74 68 42 75 66 26 23 39 31 3b 4d 41   zPathBuf&#91;MA
36150 58 5f 50 41 54 48 20 2b 20 31 26 23 39 33 3b 3b  X_PATH + 1&#93;;
36160 0a 2a 2a 20 6d 65 6d 73 65 74 28 7a 50 61 74 68  .** memset(zPath
36170 42 75 66 2c 20 30 2c 20 73 69 7a 65 6f 66 28 7a  Buf, 0, sizeof(z
36180 50 61 74 68 42 75 66 29 29 3b 0a 2a 2a 20 57 69  PathBuf));.** Wi
36190 64 65 43 68 61 72 54 6f 4d 75 6c 74 69 42 79 74  deCharToMultiByt
361a0 65 28 43 50 5f 55 54 46 38 2c 20 30 2c 20 7a 50  e(CP_UTF8, 0, zP
361b0 61 74 68 2c 20 2d 31 2c 20 7a 50 61 74 68 42 75  ath, -1, zPathBu
361c0 66 2c 20 73 69 7a 65 6f 66 28 7a 50 61 74 68 42  f, sizeof(zPathB
361d0 75 66 29 2c 0a 2a 2a 20 26 6e 62 73 70 3b 20 20  uf),.** &nbsp;  
361e0 20 20 20 4e 55 4c 4c 2c 20 4e 55 4c 4c 29 3b 0a     NULL, NULL);.
361f0 2a 2a 20 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f  ** sqlite3_temp_
36200 64 69 72 65 63 74 6f 72 79 20 3d 20 73 71 6c 69  directory = sqli
36210 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 25 73 22  te3_mprintf("%s"
36220 2c 20 7a 50 61 74 68 42 75 66 29 3b 0a 2a 2a 20  , zPathBuf);.** 
36230 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
36240 74 65 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58  te>.*/.SQLITE_EX
36250 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69 74  TERN char *sqlit
36260 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72  e3_temp_director
36270 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  y;../*.** CAPI3R
36280 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20  EF: Name Of The 
36290 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 44  Folder Holding D
362a0 61 74 61 62 61 73 65 20 46 69 6c 65 73 0a 2a 2a  atabase Files.**
362b0 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73 20 67 6c  .** ^(If this gl
362c0 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73  obal variable is
362d0 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
362e0 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68  o a string which
362f0 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20   is.** the name 
36300 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b  of a folder (a.k
36310 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20  .a. directory), 
36320 74 68 65 6e 20 61 6c 6c 20 64 61 74 61 62 61 73  then all databas
36330 65 20 66 69 6c 65 73 0a 2a 2a 20 73 70 65 63 69  e files.** speci
36340 66 69 65 64 20 77 69 74 68 20 61 20 72 65 6c 61  fied with a rela
36350 74 69 76 65 20 70 61 74 68 6e 61 6d 65 20 61 6e  tive pathname an
36360 64 20 63 72 65 61 74 65 64 20 6f 72 20 61 63 63  d created or acc
36370 65 73 73 65 64 20 62 79 0a 2a 2a 20 53 51 4c 69  essed by.** SQLi
36380 74 65 20 77 68 65 6e 20 75 73 69 6e 67 20 61 20  te when using a 
36390 62 75 69 6c 74 2d 69 6e 20 77 69 6e 64 6f 77 73  built-in windows
363a0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20   [sqlite3_vfs | 
363b0 56 46 53 5d 20 77 69 6c 6c 20 62 65 20 61 73 73  VFS] will be ass
363c0 75 6d 65 64 0a 2a 2a 20 74 6f 20 62 65 20 72 65  umed.** to be re
363d0 6c 61 74 69 76 65 20 74 6f 20 74 68 61 74 20 64  lative to that d
363e0 69 72 65 63 74 6f 72 79 2e 29 5e 20 5e 49 66 20  irectory.)^ ^If 
363f0 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 73  this variable is
36400 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
36410 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  er, then SQLite 
36420 61 73 73 75 6d 65 73 20 74 68 61 74 20 61 6c 6c  assumes that all
36430 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20   database files 
36440 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 77 69 74  specified.** wit
36450 68 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74  h a relative pat
36460 68 6e 61 6d 65 20 61 72 65 20 72 65 6c 61 74 69  hname are relati
36470 76 65 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e  ve to the curren
36480 74 20 64 69 72 65 63 74 6f 72 79 0a 2a 2a 20 66  t directory.** f
36490 6f 72 20 74 68 65 20 70 72 6f 63 65 73 73 2e 20  or the process. 
364a0 20 4f 6e 6c 79 20 74 68 65 20 77 69 6e 64 6f 77   Only the window
364b0 73 20 56 46 53 20 6d 61 6b 65 73 20 75 73 65 20  s VFS makes use 
364c0 6f 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 0a 2a  of this global.*
364d0 2a 20 76 61 72 69 61 62 6c 65 3b 20 69 74 20 69  * variable; it i
364e0 73 20 69 67 6e 6f 72 65 64 20 62 79 20 74 68 65  s ignored by the
364f0 20 75 6e 69 78 20 56 46 53 2e 0a 2a 2a 0a 2a 2a   unix VFS..**.**
36500 20 43 68 61 6e 67 69 6e 67 20 74 68 65 20 76 61   Changing the va
36510 6c 75 65 20 6f 66 20 74 68 69 73 20 76 61 72 69  lue of this vari
36520 61 62 6c 65 20 77 68 69 6c 65 20 61 20 64 61 74  able while a dat
36530 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
36540 20 69 73 0a 2a 2a 20 6f 70 65 6e 20 63 61 6e 20   is.** open can 
36550 72 65 73 75 6c 74 20 69 6e 20 61 20 63 6f 72 72  result in a corr
36560 75 70 74 20 64 61 74 61 62 61 73 65 2e 0a 2a 2a  upt database..**
36570 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61  .** It is not sa
36580 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f  fe to read or mo
36590 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62  dify this variab
365a0 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e 20  le in more than 
365b0 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20 61 74  one.** thread at
365c0 20 61 20 74 69 6d 65 2e 20 20 49 74 20 69 73 20   a time.  It is 
365d0 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64  not safe to read
365e0 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20   or modify this 
365f0 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20 61  variable.** if a
36600 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
36610 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20  ction] is being 
36620 75 73 65 64 20 61 74 20 74 68 65 20 73 61 6d 65  used at the same
36630 20 74 69 6d 65 20 69 6e 20 61 20 73 65 70 61 72   time in a separ
36640 61 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a 2a  ate.** thread..*
36650 2a 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64  * It is intended
36660 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61   that this varia
36670 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a  ble be set once.
36680 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70 72  ** as part of pr
36690 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61  ocess initializa
366a0 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20  tion and before 
366b0 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72  any SQLite inter
366c0 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  face.** routines
366d0 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65   have been calle
366e0 64 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20  d and that this 
366f0 76 61 72 69 61 62 6c 65 20 72 65 6d 61 69 6e 20  variable remain 
36700 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68 65  unchanged.** the
36710 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  reafter..**.** ^
36720 54 68 65 20 5b 64 61 74 61 5f 73 74 6f 72 65 5f  The [data_store_
36730 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
36740 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20 74 68 69  ] may modify thi
36750 73 20 76 61 72 69 61 62 6c 65 20 61 6e 64 20 63  s variable and c
36760 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20 70 6f  ause.** it to po
36770 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  int to memory ob
36780 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
36790 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 5e  ite3_malloc].  ^
367a0 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20  Furthermore,.** 
367b0 74 68 65 20 5b 64 61 74 61 5f 73 74 6f 72 65 5f  the [data_store_
367c0 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
367d0 5d 20 61 6c 77 61 79 73 20 61 73 73 75 6d 65 73  ] always assumes
367e0 20 74 68 61 74 20 61 6e 79 20 73 74 72 69 6e 67   that any string
367f0 0a 2a 2a 20 74 68 61 74 20 74 68 69 73 20 76 61  .** that this va
36800 72 69 61 62 6c 65 20 70 6f 69 6e 74 73 20 74 6f  riable points to
36810 20 69 73 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f   is held in memo
36820 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
36830 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61   .** [sqlite3_ma
36840 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20 70 72  lloc] and the pr
36850 61 67 6d 61 20 6d 61 79 20 61 74 74 65 6d 70 74  agma may attempt
36860 20 74 6f 20 66 72 65 65 20 74 68 61 74 20 6d 65   to free that me
36870 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20 5b 73  mory.** using [s
36880 71 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a  qlite3_free]..**
36890 20 48 65 6e 63 65 2c 20 69 66 20 74 68 69 73 20   Hence, if this 
368a0 76 61 72 69 61 62 6c 65 20 69 73 20 6d 6f 64 69  variable is modi
368b0 66 69 65 64 20 64 69 72 65 63 74 6c 79 2c 20 65  fied directly, e
368c0 69 74 68 65 72 20 69 74 20 73 68 6f 75 6c 64 20  ither it should 
368d0 62 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c 20  be.** made NULL 
368e0 6f 72 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  or made to point
368f0 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69   to memory obtai
36900 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
36910 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20  3_malloc].** or 
36920 65 6c 73 65 20 74 68 65 20 75 73 65 20 6f 66 20  else the use of 
36930 74 68 65 20 5b 64 61 74 61 5f 73 74 6f 72 65 5f  the [data_store_
36940 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
36950 5d 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f 69  ] should be avoi
36960 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45  ded..*/.SQLITE_E
36970 58 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69  XTERN char *sqli
36980 74 65 33 5f 64 61 74 61 5f 64 69 72 65 63 74 6f  te3_data_directo
36990 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ry;../*.** CAPI3
369a0 52 45 46 3a 20 54 65 73 74 20 46 6f 72 20 41 75  REF: Test For Au
369b0 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 0a 2a  to-Commit Mode.*
369c0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75 74  * KEYWORDS: {aut
369d0 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a  ocommit mode}.**
369e0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
369f0 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28  _get_autocommit(
36a00 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
36a10 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a  rns non-zero or.
36a20 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68 65 20 67  ** zero if the g
36a30 69 76 65 6e 20 64 61 74 61 62 61 73 65 20 63 6f  iven database co
36a40 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72 20 69  nnection is or i
36a50 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d  s not in autocom
36a60 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73  mit mode,.** res
36a70 70 65 63 74 69 76 65 6c 79 2e 20 20 5e 41 75 74  pectively.  ^Aut
36a80 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20  ocommit mode is 
36a90 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  on by default..*
36aa0 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  * ^Autocommit mo
36ab0 64 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62  de is disabled b
36ac0 79 20 61 20 5b 42 45 47 49 4e 5d 20 73 74 61 74  y a [BEGIN] stat
36ad0 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63  ement..** ^Autoc
36ae0 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 72 65  ommit mode is re
36af0 2d 65 6e 61 62 6c 65 64 20 62 79 20 61 20 5b 43  -enabled by a [C
36b00 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42  OMMIT] or [ROLLB
36b10 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63  ACK]..**.** If c
36b20 65 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20  ertain kinds of 
36b30 65 72 72 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20  errors occur on 
36b40 61 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  a statement with
36b50 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61 74 65  in a multi-state
36b60 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74  ment.** transact
36b70 69 6f 6e 20 28 65 72 72 6f 72 73 20 69 6e 63 6c  ion (errors incl
36b80 75 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 55  uding [SQLITE_FU
36b90 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f 45  LL], [SQLITE_IOE
36ba0 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  RR],.** [SQLITE_
36bb0 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f  NOMEM], [SQLITE_
36bc0 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c 49  BUSY], and [SQLI
36bd0 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 29 20 74  TE_INTERRUPT]) t
36be0 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e 73  hen the.** trans
36bf0 61 63 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20  action might be 
36c00 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f  rolled back auto
36c10 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20  matically.  The 
36c20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20 66  only way to.** f
36c30 69 6e 64 20 6f 75 74 20 77 68 65 74 68 65 72 20  ind out whether 
36c40 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63  SQLite automatic
36c50 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
36c60 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
36c70 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65 72 72   after.** an err
36c80 6f 72 20 69 73 20 74 6f 20 75 73 65 20 74 68 69  or is to use thi
36c90 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  s function..**.*
36ca0 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72  * If another thr
36cb0 65 61 64 20 63 68 61 6e 67 65 73 20 74 68 65 20  ead changes the 
36cc0 61 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75  autocommit statu
36cd0 73 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  s of the databas
36ce0 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
36cf0 77 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69  while this routi
36d00 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74  ne is running, t
36d10 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76  hen the return v
36d20 61 6c 75 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66  alue.** is undef
36d30 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ined..*/.int sql
36d40 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d  ite3_get_autocom
36d50 6d 69 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  mit(sqlite3*);..
36d60 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
36d70 46 69 6e 64 20 54 68 65 20 44 61 74 61 62 61 73  Find The Databas
36d80 65 20 48 61 6e 64 6c 65 20 4f 66 20 41 20 50 72  e Handle Of A Pr
36d90 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
36da0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
36db0 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 6e  te3_db_handle in
36dc0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
36dd0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
36de0 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
36df0 0a 2a 2a 20 74 6f 20 77 68 69 63 68 20 61 20 5b  .** to which a [
36e00 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
36e10 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 20 20 5e 54  nt] belongs.  ^T
36e20 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
36e30 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 72 65 74 75  nection].** retu
36e40 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
36e50 64 62 5f 68 61 6e 64 6c 65 20 69 73 20 74 68 65  db_handle is the
36e60 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
36e70 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 74  connection].** t
36e80 68 61 74 20 77 61 73 20 74 68 65 20 66 69 72 73  hat was the firs
36e90 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  t argument.** to
36ea0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   the [sqlite3_pr
36eb0 65 70 61 72 65 5f 76 32 28 29 5d 20 63 61 6c 6c  epare_v2()] call
36ec0 20 28 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74   (or its variant
36ed0 73 29 20 74 68 61 74 20 77 61 73 20 75 73 65 64  s) that was used
36ee0 20 74 6f 0a 2a 2a 20 63 72 65 61 74 65 20 74 68   to.** create th
36ef0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74  e statement in t
36f00 68 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a  he first place..
36f10 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69  */.sqlite3 *sqli
36f20 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71  te3_db_handle(sq
36f30 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
36f40 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
36f50 65 74 75 72 6e 20 54 68 65 20 46 69 6c 65 6e 61  eturn The Filena
36f60 6d 65 20 46 6f 72 20 41 20 44 61 74 61 62 61 73  me For A Databas
36f70 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a  e Connection.**.
36f80 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
36f90 64 62 5f 66 69 6c 65 6e 61 6d 65 28 44 2c 4e 29  db_filename(D,N)
36fa0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
36fb0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
36fc0 61 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 61 73  a filename.** as
36fd0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 64 61  sociated with da
36fe0 74 61 62 61 73 65 20 4e 20 6f 66 20 63 6f 6e 6e  tabase N of conn
36ff0 65 63 74 69 6f 6e 20 44 2e 20 20 5e 54 68 65 20  ection D.  ^The 
37000 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69  main database fi
37010 6c 65 0a 2a 2a 20 68 61 73 20 74 68 65 20 6e 61  le.** has the na
37020 6d 65 20 22 6d 61 69 6e 22 2e 20 20 49 66 20 74  me "main".  If t
37030 68 65 72 65 20 69 73 20 6e 6f 20 61 74 74 61 63  here is no attac
37040 68 65 64 20 64 61 74 61 62 61 73 65 20 4e 20 6f  hed database N o
37050 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  n the database.*
37060 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c 20  * connection D, 
37070 6f 72 20 69 66 20 64 61 74 61 62 61 73 65 20 4e  or if database N
37080 20 69 73 20 61 20 74 65 6d 70 6f 72 61 72 79 20   is a temporary 
37090 6f 72 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  or in-memory dat
370a0 61 62 61 73 65 2c 20 74 68 65 6e 0a 2a 2a 20 61  abase, then.** a
370b0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
370c0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
370d0 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 72   ^The filename r
370e0 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20  eturned by this 
370f0 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 20  function is the 
37100 6f 75 74 70 75 74 20 6f 66 20 74 68 65 0a 2a 2a  output of the.**
37110 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 20 6d   xFullPathname m
37120 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 56 46  ethod of the [VF
37130 53 5d 2e 20 20 5e 49 6e 20 6f 74 68 65 72 20 77  S].  ^In other w
37140 6f 72 64 73 2c 20 74 68 65 20 66 69 6c 65 6e 61  ords, the filena
37150 6d 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 61 6e  me.** will be an
37160 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 6e 61   absolute pathna
37170 6d 65 2c 20 65 76 65 6e 20 69 66 20 74 68 65 20  me, even if the 
37180 66 69 6c 65 6e 61 6d 65 20 75 73 65 64 0a 2a 2a  filename used.**
37190 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74   to open the dat
371a0 61 62 61 73 65 20 6f 72 69 67 69 6e 61 6c 6c 79  abase originally
371b0 20 77 61 73 20 61 20 55 52 49 20 6f 72 20 72 65   was a URI or re
371c0 6c 61 74 69 76 65 20 70 61 74 68 6e 61 6d 65 2e  lative pathname.
371d0 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
371e0 73 71 6c 69 74 65 33 5f 64 62 5f 66 69 6c 65 6e  sqlite3_db_filen
371f0 61 6d 65 28 73 71 6c 69 74 65 33 20 2a 64 62 2c  ame(sqlite3 *db,
37200 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62   const char *zDb
37210 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Name);../*.** CA
37220 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
37230 65 20 69 66 20 61 20 64 61 74 61 62 61 73 65 20  e if a database 
37240 69 73 20 72 65 61 64 2d 6f 6e 6c 79 0a 2a 2a 0a  is read-only.**.
37250 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
37260 64 62 5f 72 65 61 64 6f 6e 6c 79 28 44 2c 4e 29  db_readonly(D,N)
37270 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
37280 6e 73 20 31 20 69 66 20 74 68 65 20 64 61 74 61  ns 1 if the data
37290 62 61 73 65 20 4e 0a 2a 2a 20 6f 66 20 63 6f 6e  base N.** of con
372a0 6e 65 63 74 69 6f 6e 20 44 20 69 73 20 72 65 61  nection D is rea
372b0 64 2d 6f 6e 6c 79 2c 20 30 20 69 66 20 69 74 20  d-only, 0 if it 
372c0 69 73 20 72 65 61 64 2f 77 72 69 74 65 2c 20 6f  is read/write, o
372d0 72 20 2d 31 20 69 66 20 4e 20 69 73 20 6e 6f 74  r -1 if N is not
372e0 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  .** the name of 
372f0 61 20 64 61 74 61 62 61 73 65 20 6f 6e 20 63 6f  a database on co
37300 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2f 0a 69  nnection D..*/.i
37310 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 72 65  nt sqlite3_db_re
37320 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 20 2a  adonly(sqlite3 *
37330 64 62 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  db, const char *
37340 7a 44 62 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a  zDbName);../*.**
37350 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20   CAPI3REF: Find 
37360 74 68 65 20 6e 65 78 74 20 70 72 65 70 61 72 65  the next prepare
37370 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a  d statement.**.*
37380 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63  * ^This interfac
37390 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
373a0 74 65 72 20 74 6f 20 74 68 65 20 6e 65 78 74 20  ter to the next 
373b0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
373c0 65 6e 74 5d 20 61 66 74 65 72 0a 2a 2a 20 70 53  ent] after.** pS
373d0 74 6d 74 20 61 73 73 6f 63 69 61 74 65 64 20 77  tmt associated w
373e0 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
373f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 44  e connection] pD
37400 62 2e 20 20 5e 49 66 20 70 53 74 6d 74 20 69 73  b.  ^If pStmt is
37410 20 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e 20 74 68   NULL.** then th
37420 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  is interface ret
37430 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
37440 6f 20 74 68 65 20 66 69 72 73 74 20 70 72 65 70  o the first prep
37450 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a  ared statement.*
37460 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
37470 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  h the database c
37480 6f 6e 6e 65 63 74 69 6f 6e 20 70 44 62 2e 20 20  onnection pDb.  
37490 5e 49 66 20 6e 6f 20 70 72 65 70 61 72 65 64 20  ^If no prepared 
374a0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 73 61 74  statement.** sat
374b0 69 73 66 69 65 73 20 74 68 65 20 63 6f 6e 64 69  isfies the condi
374c0 74 69 6f 6e 73 20 6f 66 20 74 68 69 73 20 72 6f  tions of this ro
374d0 75 74 69 6e 65 2c 20 69 74 20 72 65 74 75 72 6e  utine, it return
374e0 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68  s NULL..**.** Th
374f0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
37500 65 63 74 69 6f 6e 5d 20 70 6f 69 6e 74 65 72 20  ection] pointer 
37510 44 20 69 6e 20 61 20 63 61 6c 6c 20 74 6f 0a 2a  D in a call to.*
37520 2a 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f  * [sqlite3_next_
37530 73 74 6d 74 28 44 2c 53 29 5d 20 6d 75 73 74 20  stmt(D,S)] must 
37540 72 65 66 65 72 20 74 6f 20 61 6e 20 6f 70 65 6e  refer to an open
37550 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
37560 6e 65 63 74 69 6f 6e 20 61 6e 64 20 69 6e 20 70  nection and in p
37570 61 72 74 69 63 75 6c 61 72 20 6d 75 73 74 20 6e  articular must n
37580 6f 74 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  ot be a NULL poi
37590 6e 74 65 72 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  nter..*/.sqlite3
375a0 5f 73 74 6d 74 20 2a 73 71 6c 69 74 65 33 5f 6e  _stmt *sqlite3_n
375b0 65 78 74 5f 73 74 6d 74 28 73 71 6c 69 74 65 33  ext_stmt(sqlite3
375c0 20 2a 70 44 62 2c 20 73 71 6c 69 74 65 33 5f 73   *pDb, sqlite3_s
375d0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
375e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
375f0 6d 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62 61 63  mmit And Rollbac
37600 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43  k Notification C
37610 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e  allbacks.**.** ^
37620 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d  The sqlite3_comm
37630 69 74 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66  it_hook() interf
37640 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
37650 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63  callback.** func
37660 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b  tion to be invok
37670 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 74 72  ed whenever a tr
37680 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b 43 4f  ansaction is [CO
37690 4d 4d 49 54 20 7c 20 63 6f 6d 6d 69 74 74 65 64  MMIT | committed
376a0 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62  ]..** ^Any callb
376b0 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65  ack set by a pre
376c0 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71  vious call to sq
376d0 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
376e0 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73  k().** for the s
376f0 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
37700 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72  nection is overr
37710 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20 73  idden..** ^The s
37720 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f  qlite3_rollback_
37730 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65  hook() interface
37740 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
37750 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f  lback.** functio
37760 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  n to be invoked 
37770 77 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73  whenever a trans
37780 61 63 74 69 6f 6e 20 69 73 20 5b 52 4f 4c 4c 42  action is [ROLLB
37790 41 43 4b 20 7c 20 72 6f 6c 6c 65 64 20 62 61 63  ACK | rolled bac
377a0 6b 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c  k]..** ^Any call
377b0 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72  back set by a pr
377c0 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73  evious call to s
377d0 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f  qlite3_rollback_
377e0 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68  hook().** for th
377f0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
37800 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76  connection is ov
37810 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68  erridden..** ^Th
37820 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20  e pArg argument 
37830 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67  is passed throug
37840 68 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  h to the callbac
37850 6b 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61  k..** ^If the ca
37860 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d  llback on a comm
37870 69 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e  it hook function
37880 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
37890 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63  o,.** then the c
378a0 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76 65 72 74  ommit is convert
378b0 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61  ed into a rollba
378c0 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ck..**.** ^The s
378d0 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
378e0 6f 6b 28 44 2c 43 2c 50 29 20 61 6e 64 20 73 71  ok(D,C,P) and sq
378f0 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68  lite3_rollback_h
37900 6f 6f 6b 28 44 2c 43 2c 50 29 20 66 75 6e 63 74  ook(D,C,P) funct
37910 69 6f 6e 73 0a 2a 2a 20 72 65 74 75 72 6e 20 74  ions.** return t
37920 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 66 72  he P argument fr
37930 6f 6d 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  om the previous 
37940 63 61 6c 6c 20 6f 66 20 74 68 65 20 73 61 6d 65  call of the same
37950 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6f 6e 20   function.** on 
37960 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61  the same [databa
37970 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
37980 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 0a 2a 2a  , or NULL for.**
37990 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20   the first call 
379a0 66 6f 72 20 65 61 63 68 20 66 75 6e 63 74 69 6f  for each functio
379b0 6e 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 54 68  n on D..**.** Th
379c0 65 20 63 6f 6d 6d 69 74 20 61 6e 64 20 72 6f 6c  e commit and rol
379d0 6c 62 61 63 6b 20 68 6f 6f 6b 20 63 61 6c 6c 62  lback hook callb
379e0 61 63 6b 73 20 61 72 65 20 6e 6f 74 20 72 65 65  acks are not ree
379f0 6e 74 72 61 6e 74 2e 0a 2a 2a 20 54 68 65 20 63  ntrant..** The c
37a00 61 6c 6c 62 61 63 6b 20 69 6d 70 6c 65 6d 65 6e  allback implemen
37a10 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  tation must not 
37a20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
37a30 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
37a40 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
37a50 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
37a60 6f 6b 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63  oked the callbac
37a70 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a  k.  Any actions.
37a80 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 65  ** to modify the
37a90 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
37aa0 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 64 65 66  tion must be def
37ab0 65 72 72 65 64 20 75 6e 74 69 6c 20 61 66 74 65  erred until afte
37ac0 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  r the.** complet
37ad0 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ion of the [sqli
37ae0 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c  te3_step()] call
37af0 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20   that triggered 
37b00 74 68 65 20 63 6f 6d 6d 69 74 0a 2a 2a 20 6f 72  the commit.** or
37b10 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69   rollback hook i
37b20 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c 61 63  n the first plac
37b30 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  e..** Note that 
37b40 72 75 6e 6e 69 6e 67 20 61 6e 79 20 6f 74 68 65  running any othe
37b50 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  r SQL statements
37b60 2c 20 69 6e 63 6c 75 64 69 6e 67 20 53 45 4c 45  , including SELE
37b70 43 54 20 73 74 61 74 65 6d 65 6e 74 73 2c 0a 2a  CT statements,.*
37b80 2a 20 6f 72 20 6d 65 72 65 6c 79 20 63 61 6c 6c  * or merely call
37b90 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
37ba0 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
37bb0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
37bc0 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74  will modify.** t
37bd0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
37be0 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20  ections for the 
37bf0 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69  meaning of "modi
37c00 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61  fy" in this para
37c10 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65  graph..**.** ^Re
37c20 67 69 73 74 65 72 69 6e 67 20 61 20 4e 55 4c 4c  gistering a NULL
37c30 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c   function disabl
37c40 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e  es the callback.
37c50 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65  .**.** ^When the
37c60 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 63 61 6c   commit hook cal
37c70 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65  lback routine re
37c80 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20  turns zero, the 
37c90 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 70 65 72  [COMMIT].** oper
37ca0 61 74 69 6f 6e 20 69 73 20 61 6c 6c 6f 77 65 64  ation is allowed
37cb0 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 6e 6f 72   to continue nor
37cc0 6d 61 6c 6c 79 2e 20 20 5e 49 66 20 74 68 65 20  mally.  ^If the 
37cd0 63 6f 6d 6d 69 74 20 68 6f 6f 6b 0a 2a 2a 20 72  commit hook.** r
37ce0 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
37cf0 20 74 68 65 6e 20 74 68 65 20 5b 43 4f 4d 4d 49   then the [COMMI
37d00 54 5d 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20  T] is converted 
37d10 69 6e 74 6f 20 61 20 5b 52 4f 4c 4c 42 41 43 4b  into a [ROLLBACK
37d20 5d 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c 62  ]..** ^The rollb
37d30 61 63 6b 20 68 6f 6f 6b 20 69 73 20 69 6e 76 6f  ack hook is invo
37d40 6b 65 64 20 6f 6e 20 61 20 72 6f 6c 6c 62 61 63  ked on a rollbac
37d50 6b 20 74 68 61 74 20 72 65 73 75 6c 74 73 20 66  k that results f
37d60 72 6f 6d 20 61 20 63 6f 6d 6d 69 74 0a 2a 2a 20  rom a commit.** 
37d70 68 6f 6f 6b 20 72 65 74 75 72 6e 69 6e 67 20 6e  hook returning n
37d80 6f 6e 2d 7a 65 72 6f 2c 20 6a 75 73 74 20 61 73  on-zero, just as
37d90 20 69 74 20 77 6f 75 6c 64 20 62 65 20 77 69 74   it would be wit
37da0 68 20 61 6e 79 20 6f 74 68 65 72 20 72 6f 6c 6c  h any other roll
37db0 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72  back..**.** ^For
37dc0 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66   the purposes of
37dd0 20 74 68 69 73 20 41 50 49 2c 20 61 20 74 72 61   this API, a tra
37de0 6e 73 61 63 74 69 6f 6e 20 69 73 20 73 61 69 64  nsaction is said
37df0 20 74 6f 20 68 61 76 65 20 62 65 65 6e 0a 2a 2a   to have been.**
37e00 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 69 66 20   rolled back if 
37e10 61 6e 20 65 78 70 6c 69 63 69 74 20 22 52 4f 4c  an explicit "ROL
37e20 4c 42 41 43 4b 22 20 73 74 61 74 65 6d 65 6e 74  LBACK" statement
37e30 20 69 73 20 65 78 65 63 75 74 65 64 2c 20 6f 72   is executed, or
37e40 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 6f 72 20  .** an error or 
37e50 63 6f 6e 73 74 72 61 69 6e 74 20 63 61 75 73 65  constraint cause
37e60 73 20 61 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f  s an implicit ro
37e70 6c 6c 62 61 63 6b 20 74 6f 20 6f 63 63 75 72 2e  llback to occur.
37e80 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c 62 61 63  .** ^The rollbac
37e90 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f  k callback is no
37ea0 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 74  t invoked if a t
37eb0 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a  ransaction is.**
37ec0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
37ed0 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65 63 61 75  olled back becau
37ee0 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
37ef0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c  connection is cl
37f00 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  osed..**.** See 
37f10 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  also the [sqlite
37f20 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 5d  3_update_hook()]
37f30 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 76   interface..*/.v
37f40 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  oid *sqlite3_com
37f50 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33  mit_hook(sqlite3
37f60 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29  *, int(*)(void*)
37f70 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a  , void*);.void *
37f80 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b  sqlite3_rollback
37f90 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20  _hook(sqlite3*, 
37fa0 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 29 2c  void(*)(void *),
37fb0 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
37fc0 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 20 43  CAPI3REF: Data C
37fd0 68 61 6e 67 65 20 4e 6f 74 69 66 69 63 61 74 69  hange Notificati
37fe0 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a  on Callbacks.**.
37ff0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
38000 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 20 69 6e  update_hook() in
38010 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
38020 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
38030 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68  ction.** with th
38040 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
38050 65 63 74 69 6f 6e 5d 20 69 64 65 6e 74 69 66 69  ection] identifi
38060 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
38070 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 62  argument.** to b
38080 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  e invoked whenev
38090 65 72 20 61 20 72 6f 77 20 69 73 20 75 70 64 61  er a row is upda
380a0 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72  ted, inserted or
380b0 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 41 6e   deleted..** ^An
380c0 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62  y callback set b
380d0 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c  y a previous cal
380e0 6c 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69  l to this functi
380f0 6f 6e 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  on.** for the sa
38100 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
38110 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69  ection is overri
38120 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  dden..**.** ^The
38130 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
38140 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
38150 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 74 6f   the function to
38160 20 69 6e 76 6f 6b 65 20 77 68 65 6e 20 61 0a 2a   invoke when a.*
38170 2a 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 64  * row is updated
38180 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65  , inserted or de
38190 6c 65 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 66  leted..** ^The f
381a0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
381b0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
381c0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74   a copy of the t
381d0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  hird argument.**
381e0 20 74 6f 20 73 71 6c 69 74 65 33 5f 75 70 64 61   to sqlite3_upda
381f0 74 65 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 5e 54  te_hook()..** ^T
38200 68 65 20 73 65 63 6f 6e 64 20 63 61 6c 6c 62 61  he second callba
38210 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f  ck argument is o
38220 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e  ne of [SQLITE_IN
38230 53 45 52 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44  SERT], [SQLITE_D
38240 45 4c 45 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53  ELETE],.** or [S
38250 51 4c 49 54 45 5f 55 50 44 41 54 45 5d 2c 20 64  QLITE_UPDATE], d
38260 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
38270 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 63  operation that c
38280 61 75 73 65 64 20 74 68 65 20 63 61 6c 6c 62 61  aused the callba
38290 63 6b 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f  ck.** to be invo
382a0 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 74 68 69  ked..** ^The thi
382b0 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 61 72  rd and fourth ar
382c0 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 63  guments to the c
382d0 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20  allback contain 
382e0 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 0a  pointers to the.
382f0 2a 2a 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  ** database and 
38300 74 61 62 6c 65 20 6e 61 6d 65 20 63 6f 6e 74 61  table name conta
38310 69 6e 69 6e 67 20 74 68 65 20 61 66 66 65 63 74  ining the affect
38320 65 64 20 72 6f 77 2e 0a 2a 2a 20 5e 54 68 65 20  ed row..** ^The 
38330 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 70  final callback p
38340 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
38350 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 72  [rowid] of the r
38360 6f 77 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 63  ow..** ^In the c
38370 61 73 65 20 6f 66 20 61 6e 20 75 70 64 61 74 65  ase of an update
38380 2c 20 74 68 69 73 20 69 73 20 74 68 65 20 5b 72  , this is the [r
38390 6f 77 69 64 5d 20 61 66 74 65 72 20 74 68 65 20  owid] after the 
383a0 75 70 64 61 74 65 20 74 61 6b 65 73 20 70 6c 61  update takes pla
383b0 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ce..**.** ^(The 
383c0 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 73 20 6e  update hook is n
383d0 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  ot invoked when 
383e0 69 6e 74 65 72 6e 61 6c 20 73 79 73 74 65 6d 20  internal system 
383f0 74 61 62 6c 65 73 20 61 72 65 0a 2a 2a 20 6d 6f  tables are.** mo
38400 64 69 66 69 65 64 20 28 69 2e 65 2e 20 73 71 6c  dified (i.e. sql
38410 69 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 20 73  ite_master and s
38420 71 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 29 2e  qlite_sequence).
38430 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65  )^.**.** ^In the
38440 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65   current impleme
38450 6e 74 61 74 69 6f 6e 2c 20 74 68 65 20 75 70 64  ntation, the upd
38460 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 73 20 6e  ate hook.** is n
38470 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  ot invoked when 
38480 64 75 70 6c 69 63 61 74 69 6f 6e 20 72 6f 77 73  duplication rows
38490 20 61 72 65 20 64 65 6c 65 74 65 64 20 62 65 63   are deleted bec
384a0 61 75 73 65 20 6f 66 20 61 6e 0a 2a 2a 20 5b 4f  ause of an.** [O
384b0 4e 20 43 4f 4e 46 4c 49 43 54 20 7c 20 4f 4e 20  N CONFLICT | ON 
384c0 43 4f 4e 46 4c 49 43 54 20 52 45 50 4c 41 43 45  CONFLICT REPLACE
384d0 5d 20 63 6c 61 75 73 65 2e 20 20 5e 4e 6f 72 20  ] clause.  ^Nor 
384e0 69 73 20 74 68 65 20 75 70 64 61 74 65 20 68 6f  is the update ho
384f0 6f 6b 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 77 68  ok.** invoked wh
38500 65 6e 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65  en rows are dele
38510 74 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 74  ted using the [t
38520 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61  runcate optimiza
38530 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 65 78  tion]..** The ex
38540 63 65 70 74 69 6f 6e 73 20 64 65 66 69 6e 65 64  ceptions defined
38550 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61   in this paragra
38560 70 68 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20  ph might change 
38570 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72  in a future.** r
38580 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
38590 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 70 64 61  ..**.** The upda
385a0 74 65 20 68 6f 6f 6b 20 69 6d 70 6c 65 6d 65 6e  te hook implemen
385b0 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  tation must not 
385c0 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
385d0 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
385e0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
385f0 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
38600 6f 6b 65 64 20 74 68 65 20 75 70 64 61 74 65 20  oked the update 
38610 68 6f 6f 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f  hook.  Any actio
38620 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20  ns.** to modify 
38630 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
38640 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20  nection must be 
38650 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61  deferred until a
38660 66 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70  fter the.** comp
38670 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73  letion of the [s
38680 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63  qlite3_step()] c
38690 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
386a0 65 64 20 74 68 65 20 75 70 64 61 74 65 20 68 6f  ed the update ho
386b0 6f 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  ok..** Note that
386c0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
386d0 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
386e0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74  ite3_step()] bot
386f0 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a  h modify their.*
38700 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
38710 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d  ctions for the m
38720 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66  eaning of "modif
38730 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67  y" in this parag
38740 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  raph..**.** ^The
38750 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f   sqlite3_update_
38760 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 66 75 6e 63  hook(D,C,P) func
38770 74 69 6f 6e 0a 2a 2a 20 72 65 74 75 72 6e 73 20  tion.** returns 
38780 74 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 66  the P argument f
38790 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f 75 73  rom the previous
387a0 20 63 61 6c 6c 0a 2a 2a 20 6f 6e 20 74 68 65 20   call.** on the 
387b0 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63  same [database c
387c0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72  onnection] D, or
387d0 20 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68 65   NULL for.** the
387e0 20 66 69 72 73 74 20 63 61 6c 6c 20 6f 6e 20 44   first call on D
387f0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
38800 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
38810 6d 6d 69 74 5f 68 6f 6f 6b 28 29 5d 20 61 6e 64  mmit_hook()] and
38820 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61   [sqlite3_rollba
38830 63 6b 5f 68 6f 6f 6b 28 29 5d 0a 2a 2a 20 69 6e  ck_hook()].** in
38840 74 65 72 66 61 63 65 73 2e 0a 2a 2f 0a 76 6f 69  terfaces.