/ Hex Artifact Content
Login

Artifact a2580d959495539fe9e9c17804a90b2aca176c88:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
07d0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
07e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
07f0: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0800: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0810: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0820: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0830: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0840: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0850: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0860: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
0870: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
0880: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
0890: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08a0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08b0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08c0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
08d0: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
08e0: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
08f0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0900: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0910: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0920: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0930: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0940: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0950: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0960: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
0970: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
0980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0990: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09b0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09c0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
09d0: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
09e0: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
09f0: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a00: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a20: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a30: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a40: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a50: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a60: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0a70: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0a80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0a90: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0aa0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ab0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0ac0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0ad0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0ae0: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0af0: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b00: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b10: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b20: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b30: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b40: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b50: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b60: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0b70: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0b80: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0b90: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0ba0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0bb0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bc0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0bd0: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0be0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0bf0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c00: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c20: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c30: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c40: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c50: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c60: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0c70: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0c80: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0c90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0ca0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0cb0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cc0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0cd0: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0ce0: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0cf0: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d00: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d10: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d20: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d30: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d40: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d50: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d60: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0d70: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0d80: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0d90: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0da0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0db0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0dc0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0dd0: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0de0: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0df0: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e00: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e10: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e20: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e30: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e40: 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a  ro evaluates to.
0e50: 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  ** a string whic
0e60: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70  h identifies a p
0e70: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d  articular check-
0e80: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  in of SQLite.** 
0e90: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69  within its confi
0ea0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
0eb0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68  ent system.  ^Th
0ec0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
0ed0: 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ID.** string con
0ee0: 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61  tains the date a
0ef0: 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63  nd time of the c
0f00: 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e  heck-in (UTC) an
0f10: 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73  d an SHA1.** has
0f20: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
0f30: 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a  source tree..**.
0f40: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
0f50: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
0f60: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
0f70: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
0f80: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  er()], [sqlite3_
0f90: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20  sourceid()],.** 
0fa0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
0fb0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
0fc0: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
0fd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
0fe0: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d  ERSION        "-
0ff0: 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65  -VERS--".#define
1000: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
1010: 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e  NUMBER --VERSION
1020: 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e  -NUMBER--.#defin
1030: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
1040: 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43  ID      "--SOURC
1050: 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43  E-ID--"../*.** C
1060: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1070: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
1080: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59  n Numbers.** KEY
1090: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
10a0: 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f  ersion, sqlite3_
10b0: 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54  sourceid.**.** T
10c0: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
10d0: 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65  provide the same
10e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20   information as 
10f0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  the [SQLITE_VERS
1100: 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  ION],.** [SQLITE
1110: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d  _VERSION_NUMBER]
1120: 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f  , and [SQLITE_SO
1130: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72  URCE_ID] C prepr
1140: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a  ocessor macros.*
1150: 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69  * but are associ
1160: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69  ated with the li
1170: 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66  brary instead of
1180: 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65   the header file
1190: 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a  .  ^(Cautious.**
11a0: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
11b0: 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72  ht include asser
11c0: 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69  t() statements i
11d0: 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74  n their applicat
11e0: 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79  ion to.** verify
11f0: 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74   that values ret
1200: 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69  urned by these i
1210: 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20  nterfaces match 
1220: 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a  the macros in.**
1230: 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64   the header, and
1240: 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61   thus insure tha
1250: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
1260: 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  n is.** compiled
1270: 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c   with matching l
1280: 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65  ibrary and heade
1290: 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c  r files..**.** <
12a0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
12b0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69  .** assert( sqli
12c0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
12d0: 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f  umber()==SQLITE_
12e0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29  VERSION_NUMBER )
12f0: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72  ;.** assert( str
1300: 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72  cmp(sqlite3_sour
1310: 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f  ceid(),SQLITE_SO
1320: 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a  URCE_ID)==0 );.*
1330: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70  * assert( strcmp
1340: 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  (sqlite3_libvers
1350: 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52  ion(),SQLITE_VER
1360: 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c  SION)==0 );.** <
1370: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1380: 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1390: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
13a0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
13b0: 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74  t contains the t
13c0: 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56  ext of [SQLITE_V
13d0: 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f  ERSION].** macro
13e0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
13f0: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e  libversion() fun
1400: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20  ction returns a 
1410: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
1420: 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  * to the sqlite3
1430: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
1440: 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65  g constant.  The
1450: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1460: 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f  ion().** functio
1470: 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f  n is provided fo
1480: 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69  r use in DLLs si
1490: 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73  nce DLL users us
14a0: 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76  ually do not hav
14b0: 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65  e.** direct acce
14c0: 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e  ss to string con
14d0: 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68  stants within th
14e0: 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20  e DLL.  ^The.** 
14f0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1500: 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63  on_number() func
1510: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20  tion returns an 
1520: 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f  integer equal to
1530: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
1540: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54  ION_NUMBER].  ^T
1550: 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  he sqlite3_sourc
1560: 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  eid() function r
1570: 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69  eturns .** a poi
1580: 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67  nter to a string
1590: 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20   constant whose 
15a0: 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d  value is the sam
15b0: 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51  e as the .** [SQ
15c0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20  LITE_SOURCE_ID] 
15d0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
15e0: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  acro..**.** See 
15f0: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65  also: [sqlite_ve
1600: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
1610: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
1620: 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54  ]..*/.SQLITE_EXT
1630: 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73  ERN const char s
1640: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
1650: 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
1660: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1670: 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68  (void);.const ch
1680: 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72  ar *sqlite3_sour
1690: 63 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20  ceid(void);.int 
16a0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
16b0: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b  on_number(void);
16c0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16d0: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61  : Run-Time Libra
16e0: 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f  ry Compilation O
16f0: 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69  ptions Diagnosti
1700: 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  cs.**.** ^The sq
1710: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1720: 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74  ion_used() funct
1730: 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72  ion returns 0 or
1740: 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e   1 .** indicatin
1750: 67 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70  g whether the sp
1760: 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77  ecified option w
1770: 61 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a  as defined at .*
1780: 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  * compile time. 
1790: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72   ^The SQLITE_ pr
17a0: 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74  efix may be omit
17b0: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a  ted from the .**
17c0: 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73   option name pas
17d0: 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  sed to sqlite3_c
17e0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
17f0: 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  d().  .**.** ^Th
1800: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  e sqlite3_compil
1810: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75  eoption_get() fu
1820: 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74  nction allows it
1830: 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20  erating.** over 
1840: 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69  the list of opti
1850: 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65  ons that were de
1860: 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  fined at compile
1870: 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75   time by.** retu
1880: 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63  rning the N-th c
1890: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69  ompile time opti
18a0: 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20  on string.  ^If 
18b0: 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
18c0: 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  e,.** sqlite3_co
18d0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
18e0: 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
18f0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
1900: 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66  SQLITE_ .** pref
1910: 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  ix is omitted fr
1920: 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72  om any strings r
1930: 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73  eturned by .** s
1940: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1950: 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a  tion_get()..**.*
1960: 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74  * ^Support for t
1970: 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75  he diagnostic fu
1980: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f  nctions sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
19a0: 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ed().** and sqli
19b0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19c0: 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f  n_get() may be o
19d0: 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66  mitted by specif
19e0: 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51  ying the .** [SQ
19f0: 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c  LITE_OMIT_COMPIL
1a00: 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f  EOPTION_DIAGS] o
1a10: 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65  ption at compile
1a20: 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   time..**.** See
1a30: 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74   also: SQL funct
1a40: 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d  ions [sqlite_com
1a50: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1a60: 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
1a70: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
1a80: 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b  get()] and the [
1a90: 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20  compile_options 
1aa0: 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e  pragma]..*/.#ifn
1ab0: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
1ac0: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49  COMPILEOPTION_DI
1ad0: 41 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  AGS.int sqlite3_
1ae0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
1af0: 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  ed(const char *z
1b00: 4f 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20  OptName);.const 
1b10: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
1b20: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1b30: 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a  int N);.#endif..
1b40: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b50: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
1b60: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68  he Library Is Th
1b70: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e  readsafe.**.** ^
1b80: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65  The sqlite3_thre
1b90: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
1ba0: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69  n returns zero i
1bb0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
1bc0: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70   SQLite was comp
1bd0: 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69  iled with mutexi
1be0: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20  ng code omitted 
1bf0: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53  due to the.** [S
1c00: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1c10: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
1c20: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20  ption being set 
1c30: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  to 0..**.** SQLi
1c40: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c  te can be compil
1c50: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f  ed with or witho
1c60: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65  ut mutexes.  Whe
1c70: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  n.** the [SQLITE
1c80: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70  _THREADSAFE] C p
1c90: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
1ca0: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74  o is 1 or 2, mut
1cb0: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
1cc0: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69  led and SQLite i
1cd0: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57  s threadsafe.  W
1ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  hen the.** [SQLI
1cf0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
1d00: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74  acro is 0, .** t
1d10: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f  he mutexes are o
1d20: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74  mitted.  Without
1d30: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74   the mutexes, it
1d40: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20   is not safe.** 
1d50: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f  to use SQLite co
1d60: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20  ncurrently from 
1d70: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68  more than one th
1d80: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62  read..**.** Enab
1d90: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63  ling mutexes inc
1da0: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65  urs a measurable
1db0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e   performance pen
1dc0: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73  alty..** So if s
1dd0: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73  peed is of utmos
1de0: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74  t importance, it
1df0: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20   makes sense to 
1e00: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d  disable.** the m
1e10: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72  utexes.  But for
1e20: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c   maximum safety,
1e30: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20   mutexes should 
1e40: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e  be enabled..** ^
1e50: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  The default beha
1e60: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65  vior is for mute
1e70: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65  xes to be enable
1e80: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  d..**.** This in
1e90: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
1ea0: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63  sed by an applic
1eb0: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75  ation to make su
1ec0: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76  re that the.** v
1ed0: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
1ee0: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b   that it is link
1ef0: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20  ing against was 
1f00: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
1f10: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74   the desired set
1f20: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c  ting of the [SQL
1f30: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
1f40: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  macro..**.** Thi
1f50: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79  s interface only
1f60: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20   reports on the 
1f70: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74  compile-time mut
1f80: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66  ex setting.** of
1f90: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
1fa0: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20  EADSAFE] flag.  
1fb0: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
1fc0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51  piled with.** SQ
1fd0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
1fe0: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74  1 or =2 then mut
1ff0: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
2000: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
2010: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
2020: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
2030: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
2040: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
2050: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
2060: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
2070: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
2080: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
2090: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
20a0: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
20b0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
20c0: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e  ].  ^(The return
20d0: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a   value of the.**
20e0: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
20f0: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73  afe() function s
2100: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f  hows only the co
2110: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69  mpile-time setti
2120: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20  ng of.** thread 
2130: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20  safety, not any 
2140: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73  run-time changes
2150: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67   to that setting
2160: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69   made by.** sqli
2170: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e  te3_config(). In
2180: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2190: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
21a0: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65  rom sqlite3_thre
21b0: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75  adsafe().** is u
21c0: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c  nchanged by call
21d0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  s to sqlite3_con
21e0: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  fig().)^.**.** S
21f0: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
2200: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
2210: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
2220: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
2230: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2240: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64  _threadsafe(void
2250: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2260: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
2270: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a  nection Handle.*
2280: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74  * KEYWORDS: {dat
2290: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22a0: 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  } {database conn
22b0: 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45  ections}.**.** E
22c0: 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20  ach open SQLite 
22d0: 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72  database is repr
22e0: 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69  esented by a poi
22f0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
2300: 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70  nce of.** the op
2310: 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e  aque structure n
2320: 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20  amed "sqlite3". 
2330: 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f   It is useful to
2340: 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c   think of an sql
2350: 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ite3.** pointer 
2360: 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54  as an object.  T
2370: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
2380: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
2390: 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  en16()], and.** 
23a0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
23b0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61  ()] interfaces a
23c0: 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74  re its construct
23d0: 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ors, and [sqlite
23e0: 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e  3_close()].** an
23f0: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
2400: 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73 20 64  _v2()] are its d
2410: 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65  estructors.  The
2420: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
2430: 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  r.** interfaces 
2440: 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c  (such as.** [sql
2450: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2460: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
2470: 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c  ate_function()],
2480: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2490: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
24a0: 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72   to name but thr
24b0: 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74  ee) that are met
24c0: 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71  hods on an.** sq
24d0: 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f  lite3 object..*/
24e0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
24f0: 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b  sqlite3 sqlite3;
2500: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2510: 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72  : 64-Bit Integer
2520: 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Types.** KEYWOR
2530: 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  DS: sqlite_int64
2540: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a   sqlite_uint64.*
2550: 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
2560: 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70  re is no cross-p
2570: 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73  latform way to s
2580: 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e  pecify 64-bit in
2590: 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53  teger types.** S
25a0: 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74  QLite includes t
25b0: 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62  ypedefs for 64-b
25c0: 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e  it signed and un
25d0: 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e  signed integers.
25e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
25f0: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  e3_int64 and sql
2600: 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20  ite3_uint64 are 
2610: 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 79  the preferred ty
2620: 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a  pe definitions..
2630: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e  ** The sqlite_in
2640: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2650: 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 20  int64 types are 
2660: 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61  supported for ba
2670: 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61  ckwards.** compa
2680: 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a  tibility only..*
2690: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
26a0: 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  3_int64 and sqli
26b0: 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63  te_int64 types c
26c0: 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72  an store integer
26d0: 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65   values.** betwe
26e0: 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 35  en -922337203685
26f0: 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32  4775808 and +922
2700: 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30 37  3372036854775807
2710: 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68   inclusive.  ^Th
2720: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e  e.** sqlite3_uin
2730: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2740: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
2750: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
2760: 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e  lues .** between
2770: 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34   0 and +18446744
2780: 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 63  073709551615 inc
2790: 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65  lusive..*/.#ifde
27a0: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
27b0: 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51  YPE.  typedef SQ
27c0: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
27d0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20  sqlite_int64;.  
27e0: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64  typedef unsigned
27f0: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
2800: 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  PE sqlite_uint64
2810: 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28  ;.#elif defined(
2820: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66  _MSC_VER) || def
2830: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
2840: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69  _).  typedef __i
2850: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36  nt64 sqlite_int6
2860: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2870: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71  igned __int64 sq
2880: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
2890: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e  se.  typedef lon
28a0: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
28b0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
28c0: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67  ef unsigned long
28d0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
28e0: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a  _uint64;.#endif.
28f0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69  typedef sqlite_i
2900: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74  nt64 sqlite3_int
2910: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69  64;.typedef sqli
2920: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  te_uint64 sqlite
2930: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a  3_uint64;../*.**
2940: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f   If compiling fo
2950: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68  r a processor th
2960: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e  at lacks floatin
2970: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c  g point support,
2980: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69  .** substitute i
2990: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74  nteger for float
29a0: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69  ing-point..*/.#i
29b0: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
29c0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
29d0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
29e0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
29f0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2a00: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
2a10: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2a20: 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ion.**.** ^The s
2a30: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61  qlite3_close() a
2a40: 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nd sqlite3_close
2a50: 5f 76 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61  _v2() routines a
2a60: 72 65 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a  re destructors.*
2a70: 2a 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  * for the [sqlit
2a80: 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e  e3] object..** ^
2a90: 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
2aa0: 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c  _close() and sql
2ab0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
2ac0: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
2ad0: 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69   if.** the [sqli
2ae0: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73  te3] object is s
2af0: 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74  uccessfully dest
2b00: 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73  royed and all as
2b10: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f  sociated.** reso
2b20: 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f  urces are deallo
2b30: 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  cated..**.** ^If
2b40: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2b50: 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f  nnection is asso
2b60: 63 69 61 74 65 64 20 77 69 74 68 20 75 6e 66 69  ciated with unfi
2b70: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64  nalized prepared
2b80: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  .** statements o
2b90: 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c  r unfinished sql
2ba0: 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65  ite3_backup obje
2bb0: 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33  cts then sqlite3
2bc0: 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c  _close().** will
2bd0: 20 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 62   leave the datab
2be0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
2bf0: 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  pen and return [
2c00: 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a  SQLITE_BUSY]..**
2c10: 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f   ^If sqlite3_clo
2c20: 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65  se_v2() is calle
2c30: 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a  d with unfinaliz
2c40: 65 64 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ed prepared stat
2c50: 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 20 75 6e  ements.** and un
2c60: 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33  finished sqlite3
2c70: 5f 62 61 63 6b 75 70 73 2c 20 74 68 65 6e 20 74  _backups, then t
2c80: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2c90: 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a  ection becomes.*
2ca0: 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a  * an unusable "z
2cb0: 6f 6d 62 69 65 22 20 77 68 69 63 68 20 77 69 6c  ombie" which wil
2cc0: 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  l automatically 
2cd0: 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 77  be deallocated w
2ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20  hen the.** last 
2cf0: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d00: 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 20  nt is finalized 
2d10: 6f 72 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69  or the last sqli
2d20: 74 65 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a  te3_backup is.**
2d30: 20 66 69 6e 69 73 68 65 64 2e 20 20 54 68 65 20   finished.  The 
2d40: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
2d50: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
2d60: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
2d70: 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61   with.** host la
2d80: 6e 67 75 61 67 65 73 20 74 68 61 74 20 61 72 65  nguages that are
2d90: 20 67 61 72 62 61 67 65 20 63 6f 6c 6c 65 63 74   garbage collect
2da0: 65 64 2c 20 61 6e 64 20 77 68 65 72 65 20 74 68  ed, and where th
2db0: 65 20 6f 72 64 65 72 20 69 6e 20 77 68 69 63 68  e order in which
2dc0: 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 73 20  .** destructors 
2dd0: 61 72 65 20 63 61 6c 6c 65 64 20 69 73 20 61 72  are called is ar
2de0: 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41  bitrary..**.** A
2df0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
2e00: 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ld [sqlite3_fina
2e10: 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d  lize | finalize]
2e20: 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73   all [prepared s
2e30: 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b  tatements],.** [
2e40: 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
2e50: 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20  se | close] all 
2e60: 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20  [BLOB handles], 
2e70: 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  and .** [sqlite3
2e80: 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c  _backup_finish |
2e90: 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71   finish] all [sq
2ea0: 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62  lite3_backup] ob
2eb0: 6a 65 63 74 73 20 61 73 73 6f 63 69 61 74 65 64  jects associated
2ec0: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73 71  .** with the [sq
2ed0: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72  lite3] object pr
2ee0: 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e  ior to attemptin
2ef0: 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f  g to close the o
2f00: 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73  bject.  ^If.** s
2f10: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
2f20: 29 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61  ) is called on a
2f30: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2f40: 63 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c  ction] that stil
2f50: 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e  l has.** outstan
2f60: 64 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73  ding [prepared s
2f70: 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f  tatements], [BLO
2f80: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f  B handles], and/
2f90: 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  or.** [sqlite3_b
2fa0: 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 74  ackup] objects t
2fb0: 68 65 6e 20 69 74 20 72 65 74 75 72 6e 73 20 53  hen it returns S
2fc0: 51 4c 49 54 45 5f 4f 4b 20 62 75 74 20 74 68 65  QLITE_OK but the
2fd0: 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a   deallocation.**
2fe0: 20 6f 66 20 72 65 73 6f 75 72 63 65 73 20 69 73   of resources is
2ff0: 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20   deferred until 
3000: 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74  all [prepared st
3010: 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42  atements], [BLOB
3020: 20 68 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e   handles],.** an
3030: 64 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  d [sqlite3_backu
3040: 70 5d 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61  p] objects are a
3050: 6c 73 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a  lso destroyed..*
3060: 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c  *.** ^If an [sql
3070: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20  ite3] object is 
3080: 64 65 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20  destroyed while 
3090: 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
30a0: 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72   open,.** the tr
30b0: 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74  ansaction is aut
30c0: 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65  omatically rolle
30d0: 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68  d back..**.** Th
30e0: 65 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e C parameter to
30f0: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
3100: 43 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  C)] and [sqlite3
3110: 5f 63 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a  _close_v2(C)].**
3120: 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
3130: 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
3140: 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33  r or an [sqlite3
3150: 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72  ] object pointer
3160: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
3170: 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  m [sqlite3_open(
3180: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
3190: 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  n16()], or.** [s
31a0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
31b0: 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69  ], and not previ
31c0: 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a  ously closed..**
31d0: 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65   ^Calling sqlite
31e0: 33 5f 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c  3_close() or sql
31f0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
3200: 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
3210: 74 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ter.** argument 
3220: 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
3230: 2d 6f 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  -op..*/.int sqli
3240: 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65  te3_close(sqlite
3250: 33 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  3*);.int sqlite3
3260: 5f 63 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65  _close_v2(sqlite
3270: 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20  3*);../*.** The 
3280: 74 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62  type for a callb
3290: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ack function..**
32a0: 20 54 68 69 73 20 69 73 20 6c 65 67 61 63 79 20   This is legacy 
32b0: 61 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e 20  and deprecated. 
32c0: 20 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20   It is included 
32d0: 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a  for historical.*
32e0: 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  * compatibility 
32f0: 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d  and is not docum
3300: 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65  ented..*/.typede
3310: 66 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f  f int (*sqlite3_
3320: 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c  callback)(void*,
3330: 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72  int,char**, char
3340: 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  **);../*.** CAPI
3350: 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51  3REF: One-Step Q
3360: 75 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49  uery Execution I
3370: 6e 74 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54  nterface.**.** T
3380: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3390: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 61  ) interface is a
33a0: 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61   convenience wra
33b0: 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b  pper around.** [
33c0: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
33d0: 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v2()], [sqlite3_
33e0: 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71  step()], and [sq
33f0: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
3400: 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77  ],.** that allow
3410: 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  s an application
3420: 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65   to run multiple
3430: 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53   statements of S
3440: 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61  QL.** without ha
3450: 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f  ving to use a lo
3460: 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a  t of C code. .**
3470: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
3480: 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63  _exec() interfac
3490: 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d  e runs zero or m
34a0: 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  ore UTF-8 encode
34b0: 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d  d,.** semicolon-
34c0: 73 65 70 61 72 61 74 65 20 53 51 4c 20 73 74 61  separate SQL sta
34d0: 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69  tements passed i
34e0: 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75  nto its 2nd argu
34f0: 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20  ment,.** in the 
3500: 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b  context of the [
3510: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
3520: 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61  ion] passed in a
3530: 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67  s its 1st.** arg
3540: 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20  ument.  ^If the 
3550: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
3560: 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61 72 67  n of the 3rd arg
3570: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69  ument to.** sqli
3580: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f  te3_exec() is no
3590: 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20  t NULL, then it 
35a0: 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65  is invoked for e
35b0: 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a  ach result row.*
35c0: 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20  * coming out of 
35d0: 74 68 65 20 65 76 61 6c 75 61 74 65 64 20 53 51  the evaluated SQ
35e0: 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e  L statements.  ^
35f0: 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74  The 4th argument
3600: 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65   to.** sqlite3_e
3610: 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 65 64  xec() is relayed
3620: 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20   through to the 
3630: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  1st argument of 
3640: 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  each.** callback
3650: 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49   invocation.  ^I
3660: 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 70  f the callback p
3670: 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ointer to sqlite
3680: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e  3_exec().** is N
3690: 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c  ULL, then no cal
36a0: 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 69 6e  lback is ever in
36b0: 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 6c 74  voked and result
36c0: 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e   rows are.** ign
36d0: 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ored..**.** ^If 
36e0: 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
36f0: 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67  while evaluating
3700: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
3710: 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f 0a  nts passed into.
3720: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
3730: 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 69 6f  ), then executio
3740: 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  n of the current
3750: 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f 70 73   statement stops
3760: 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75 65   and.** subseque
3770: 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  nt statements ar
3780: 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 66 20  e skipped.  ^If 
3790: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
37a0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
37b0: 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55  c().** is not NU
37c0: 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 72 6f  LL then any erro
37d0: 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 72 69  r message is wri
37e0: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  tten into memory
37f0: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
3800: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
3810: 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 64 20  c()] and passed 
3820: 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65  back through the
3830: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 2e 0a   5th parameter..
3840: 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f  ** To avoid memo
3850: 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 61 70  ry leaks, the ap
3860: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
3870: 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33   invoke [sqlite3
3880: 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65  _free()].** on e
3890: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
38a0: 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 74 68  ings returned th
38b0: 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61  rough the 5th pa
38c0: 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66  rameter of.** of
38d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
38e0: 61 66 74 65 72 20 74 68 65 20 65 72 72 6f 72 20  after the error 
38f0: 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69  message string i
3900: 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64  s no longer need
3910: 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35  ed..** ^If the 5
3920: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
3930: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3940: 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e  s not NULL and n
3950: 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75  o errors.** occu
3960: 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  r, then sqlite3_
3970: 65 78 65 63 28 29 20 73 65 74 73 20 74 68 65 20  exec() sets the 
3980: 70 6f 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35  pointer in its 5
3990: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  th parameter to.
39a0: 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72  ** NULL before r
39b0: 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  eturning..**.** 
39c0: 5e 49 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65  ^If an sqlite3_e
39d0: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72  xec() callback r
39e0: 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
39f0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   the sqlite3_exe
3a00: 63 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  c().** routine r
3a10: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42  eturns SQLITE_AB
3a20: 4f 52 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f  ORT without invo
3a30: 6b 69 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63  king the callbac
3a40: 6b 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77  k again and.** w
3a50: 69 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61  ithout running a
3a60: 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 53 51  ny subsequent SQ
3a70: 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
3a80: 0a 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67  .** ^The 2nd arg
3a90: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
3aa0: 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c  ite3_exec() call
3ab0: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73  back function is
3ac0: 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
3ad0: 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
3ae0: 20 72 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33   result.  ^The 3
3af0: 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  rd argument to t
3b00: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3b10: 29 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73  ).** callback is
3b20: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
3b30: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
3b40: 20 6f 62 74 61 69 6e 65 64 20 61 73 20 69 66 20   obtained as if 
3b50: 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  from.** [sqlite3
3b60: 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c  _column_text()],
3b70: 20 6f 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f   one for each co
3b80: 6c 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c  lumn.  ^If an el
3b90: 65 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65  ement of a.** re
3ba0: 73 75 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c  sult row is NULL
3bb0: 20 74 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73   then the corres
3bc0: 70 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70  ponding string p
3bd0: 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a  ointer for the.*
3be0: 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  * sqlite3_exec()
3bf0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e   callback is a N
3c00: 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54  ULL pointer.  ^T
3c10: 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20  he 4th argument 
3c20: 74 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65  to the.** sqlite
3c30: 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63  3_exec() callbac
3c40: 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  k is an array of
3c50: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
3c60: 69 6e 67 73 20 77 68 65 72 65 20 65 61 63 68 0a  ings where each.
3c70: 2a 2a 20 65 6e 74 72 79 20 72 65 70 72 65 73 65  ** entry represe
3c80: 6e 74 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  nts the name of 
3c90: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65  corresponding re
3ca0: 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f  sult column as o
3cb0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
3cc0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
3cd0: 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  name()]..**.** ^
3ce0: 49 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  If the 2nd param
3cf0: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
3d00: 65 78 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c  exec() is a NULL
3d10: 20 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e   pointer, a poin
3d20: 74 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70  ter.** to an emp
3d30: 74 79 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20  ty string, or a 
3d40: 70 6f 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e  pointer that con
3d50: 74 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65  tains only white
3d60: 73 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a  space and/or .**
3d70: 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74   SQL comments, t
3d80: 68 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65  hen no SQL state
3d90: 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61  ments are evalua
3da0: 74 65 64 20 61 6e 64 20 74 68 65 20 64 61 74 61  ted and the data
3db0: 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63  base.** is not c
3dc0: 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65  hanged..**.** Re
3dd0: 73 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a  strictions:.**.*
3de0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  * <ul>.** <li> T
3df0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
3e00: 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 20  ust insure that 
3e10: 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65  the 1st paramete
3e20: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
3e30: 63 28 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61  c().**      is a
3e40: 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20   valid and open 
3e50: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3e60: 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54  tion]..** <li> T
3e70: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
3e80: 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 5b 64  ust not close [d
3e90: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
3ea0: 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79  on] specified by
3eb0: 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31 73 74  .**      the 1st
3ec0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3ed0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 69  lite3_exec() whi
3ee0: 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  le sqlite3_exec(
3ef0: 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  ) is running..**
3f00: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63   <li> The applic
3f10: 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d  ation must not m
3f20: 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20 73 74  odify the SQL st
3f30: 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70 61 73  atement text pas
3f40: 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20  sed into.**     
3f50: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
3f60: 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78  er of sqlite3_ex
3f70: 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74  ec() while sqlit
3f80: 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e  e3_exec() is run
3f90: 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  ning..** </ul>.*
3fa0: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  /.int sqlite3_ex
3fb0: 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  ec(.  sqlite3*, 
3fc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fe0: 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61   /* An open data
3ff0: 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  base */.  const 
4000: 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20  char *sql,      
4010: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4020: 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62       /* SQL to b
4030: 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20  e evaluated */. 
4040: 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29   int (*callback)
4050: 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a  (void*,int,char*
4060: 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43  *,char**),  /* C
4070: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
4080: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20   */.  void *,   
4090: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40b0: 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74   /* 1st argument
40c0: 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a   to callback */.
40d0: 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20    char **errmsg 
40e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
4100: 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65  Error msg writte
4110: 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a  n here */.);../*
4120: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
4130: 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45  sult Codes.** KE
4140: 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f  YWORDS: SQLITE_O
4150: 4b 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b  K {error code} {
4160: 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20  error codes}.** 
4170: 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c  KEYWORDS: {resul
4180: 74 20 63 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20  t code} {result 
4190: 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e  codes}.**.** Man
41a0: 79 20 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f  y SQLite functio
41b0: 6e 73 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74  ns return an int
41c0: 65 67 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65  eger result code
41d0: 20 66 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68   from the set sh
41e0: 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f  own.** here in o
41f0: 72 64 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65  rder to indicate
4200: 20 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c   success or fail
4210: 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65  ure..**.** New e
4220: 72 72 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62  rror codes may b
4230: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
4240: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
4250: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  Lite..**.** See 
4260: 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f  also: [SQLITE_IO
4270: 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e  ERR_READ | exten
4280: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4290: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  ],.** [sqlite3_v
42a0: 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28  tab_on_conflict(
42b0: 29 5d 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42  )] [SQLITE_ROLLB
42c0: 41 43 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64  ACK | result cod
42d0: 65 73 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  es]..*/.#define 
42e0: 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20  SQLITE_OK       
42f0: 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65      0   /* Succe
4300: 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a  ssful result */.
4310: 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d  /* beginning-of-
4320: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23  error-codes */.#
4330: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52  define SQLITE_ER
4340: 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 2f  ROR        1   /
4350: 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d  * SQL error or m
4360: 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65 20  issing database 
4370: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4380: 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32  E_INTERNAL     2
4390: 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c     /* Internal l
43a0: 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51  ogic error in SQ
43b0: 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  Lite */.#define 
43c0: 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20  SQLITE_PERM     
43d0: 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73      3   /* Acces
43e0: 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e  s permission den
43f0: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
4400: 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20  QLITE_ABORT     
4410: 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61     4   /* Callba
4420: 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65  ck routine reque
4430: 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f  sted an abort */
4440: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4450: 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20  BUSY         5  
4460: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
4470: 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20   file is locked 
4480: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4490: 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36  E_LOCKED       6
44a0: 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e     /* A table in
44b0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
44c0: 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69   locked */.#defi
44d0: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20  ne SQLITE_NOMEM 
44e0: 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20         7   /* A 
44f0: 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20  malloc() failed 
4500: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4510: 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38  E_READONLY     8
4520: 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f     /* Attempt to
4530: 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c   write a readonl
4540: 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64  y database */.#d
4550: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
4560: 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a  ERRUPT    9   /*
4570: 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69   Operation termi
4580: 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  nated by sqlite3
4590: 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23  _interrupt()*/.#
45a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
45b0: 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f  ERR       10   /
45c0: 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64  * Some kind of d
45d0: 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63  isk I/O error oc
45e0: 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e  curred */.#defin
45f0: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54  e SQLITE_CORRUPT
4600: 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65       11   /* The
4610: 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69   database disk i
4620: 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65  mage is malforme
4630: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4640: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20  ITE_NOTFOUND    
4650: 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20  12   /* Unknown 
4660: 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65  opcode in sqlite
4670: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
4680: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4690: 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31  TE_FULL        1
46a0: 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e  3   /* Insertion
46b0: 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20   failed because 
46c0: 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c  database is full
46d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
46e0: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31  TE_CANTOPEN    1
46f0: 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f  4   /* Unable to
4700: 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   open the databa
4710: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69  se file */.#defi
4720: 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43  ne SQLITE_PROTOC
4730: 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61  OL    15   /* Da
4740: 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74  tabase lock prot
4750: 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64  ocol error */.#d
4760: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50  efine SQLITE_EMP
4770: 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a  TY       16   /*
4780: 20 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70   Database is emp
4790: 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ty */.#define SQ
47a0: 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20  LITE_SCHEMA     
47b0: 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74   17   /* The dat
47c0: 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
47d0: 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nged */.#define 
47e0: 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20  SQLITE_TOOBIG   
47f0: 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e     18   /* Strin
4800: 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64  g or BLOB exceed
4810: 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a  s size limit */.
4820: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
4830: 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20  ONSTRAINT  19   
4840: 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20  /* Abort due to 
4850: 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
4860: 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  tion */.#define 
4870: 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20  SQLITE_MISMATCH 
4880: 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20     20   /* Data 
4890: 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f  type mismatch */
48a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
48b0: 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20  MISUSE      21  
48c0: 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64   /* Library used
48d0: 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a   incorrectly */.
48e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
48f0: 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20  OLFS       22   
4900: 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75  /* Uses OS featu
4910: 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65  res not supporte
4920: 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65  d on host */.#de
4930: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48  fine SQLITE_AUTH
4940: 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
4950: 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65  Authorization de
4960: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
4970: 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20  SQLITE_FORMAT   
4980: 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c     24   /* Auxil
4990: 69 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f  iary database fo
49a0: 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64  rmat error */.#d
49b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e  efine SQLITE_RAN
49c0: 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a  GE       25   /*
49d0: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
49e0: 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f  o sqlite3_bind o
49f0: 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23  ut of range */.#
4a00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
4a10: 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f  TADB      26   /
4a20: 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68  * File opened th
4a30: 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61  at is not a data
4a40: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
4a50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
4a60: 43 45 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20  CE      27   /* 
4a70: 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73 20 66 72  Notifications fr
4a80: 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  om sqlite3_log()
4a90: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4aa0: 54 45 5f 57 41 52 4e 49 4e 47 20 20 20 20 20 32  TE_WARNING     2
4ab0: 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73 20  8   /* Warnings 
4ac0: 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67  from sqlite3_log
4ad0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
4ae0: 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20  LITE_ROW        
4af0: 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33   100  /* sqlite3
4b00: 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74  _step() has anot
4b10: 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f  her row ready */
4b20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4b30: 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20  DONE        101 
4b40: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70   /* sqlite3_step
4b50: 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  () has finished 
4b60: 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20  executing */./* 
4b70: 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64  end-of-error-cod
4b80: 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  es */../*.** CAP
4b90: 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20  I3REF: Extended 
4ba0: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
4bb0: 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e  KEYWORDS: {exten
4bc0: 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 7d 20  ded error code} 
4bd0: 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  {extended error 
4be0: 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52  codes}.** KEYWOR
4bf0: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65  DS: {extended re
4c00: 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78 74 65  sult code} {exte
4c10: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4c20: 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 20  s}.**.** In its 
4c30: 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72  default configur
4c40: 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41 50  ation, SQLite AP
4c50: 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  I routines retur
4c60: 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74 65  n one of 26 inte
4c70: 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  ger.** [SQLITE_O
4c80: 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  K | result codes
4c90: 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70  ].  However, exp
4ca0: 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77  erience has show
4cb0: 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a  n that many of.*
4cc0: 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63  * these result c
4cd0: 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61  odes are too coa
4ce0: 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68  rse-grained.  Th
4cf0: 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64  ey do not provid
4d00: 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66  e as.** much inf
4d10: 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70  ormation about p
4d20: 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72  roblems as progr
4d30: 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b  ammers might lik
4d40: 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74  e.  In an effort
4d50: 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74   to.** address t
4d60: 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69  his, newer versi
4d70: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76  ons of SQLite (v
4d80: 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64  ersion 3.3.8 and
4d90: 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a   later) include.
4da0: 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61  ** support for a
4db0: 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74  dditional result
4dc0: 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76   codes that prov
4dd0: 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65  ide more detaile
4de0: 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  d information.**
4df0: 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54   about errors. T
4e00: 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  he extended resu
4e10: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e 61  lt codes are ena
4e20: 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64  bled or disabled
4e30: 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74  .** on a per dat
4e40: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
4e50: 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68 65   basis using the
4e60: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74  .** [sqlite3_ext
4e70: 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
4e80: 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a  es()] API..**.**
4e90: 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76 61   Some of the ava
4ea0: 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64 20  ilable extended 
4eb0: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4ec0: 20 6c 69 73 74 65 64 20 68 65 72 65 2e 0a 2a 2a   listed here..**
4ed0: 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 63 74 20   One may expect 
4ee0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78  the number of ex
4ef0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
4f00: 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78 70 61  des will be expa
4f10: 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65 2e  nd.** over time.
4f20: 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20    Software that 
4f30: 75 73 65 73 20 65 78 74 65 6e 64 65 64 20 72 65  uses extended re
4f40: 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f 75 6c  sult codes shoul
4f50: 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20 73  d expect.** to s
4f60: 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20 63 6f  ee new result co
4f70: 64 65 73 20 69 6e 20 66 75 74 75 72 65 20 72 65  des in future re
4f80: 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
4f90: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ..**.** The SQLI
4fa0: 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f 64  TE_OK result cod
4fb0: 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65 20  e will never be 
4fc0: 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77 69  extended.  It wi
4fd0: 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20  ll always.** be 
4fe0: 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f  exactly zero..*/
4ff0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5000: 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20 20  IOERR_READ      
5010: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5020: 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a  IOERR | (1<<8)).
5030: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5040: 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20  OERR_SHORT_READ 
5050: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5060: 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23  OERR | (2<<8)).#
5070: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5080: 45 52 52 5f 57 52 49 54 45 20 20 20 20 20 20 20  ERR_WRITE       
5090: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
50a0: 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  ERR | (3<<8)).#d
50b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
50c0: 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20  RR_FSYNC        
50d0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
50e0: 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65  RR | (4<<8)).#de
50f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5100: 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20 20  R_DIR_FSYNC     
5110: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5120: 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66  R | (5<<8)).#def
5130: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5140: 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20 20 20  _TRUNCATE       
5150: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5160: 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69   | (6<<8)).#defi
5170: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5180: 46 53 54 41 54 20 20 20 20 20 20 20 20 20 20 20  FSTAT           
5190: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
51a0: 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (7<<8)).#defin
51b0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55  e SQLITE_IOERR_U
51c0: 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  NLOCK           
51d0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
51e0: 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (8<<8)).#define
51f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44   SQLITE_IOERR_RD
5200: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20  LOCK            
5210: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5220: 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (9<<8)).#define 
5230: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c  SQLITE_IOERR_DEL
5240: 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 28  ETE            (
5250: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5260: 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  10<<8)).#define 
5270: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
5280: 43 4b 45 44 20 20 20 20 20 20 20 20 20 20 20 28  CKED           (
5290: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
52a0: 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  11<<8)).#define 
52b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d  SQLITE_IOERR_NOM
52c0: 45 4d 20 20 20 20 20 20 20 20 20 20 20 20 20 28  EM             (
52d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
52e0: 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  12<<8)).#define 
52f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 43  SQLITE_IOERR_ACC
5300: 45 53 53 20 20 20 20 20 20 20 20 20 20 20 20 28  ESS            (
5310: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5320: 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  13<<8)).#define 
5330: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48 45  SQLITE_IOERR_CHE
5340: 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b 20 28  CKRESERVEDLOCK (
5350: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5360: 31 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  14<<8)).#define 
5370: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f 43  SQLITE_IOERR_LOC
5380: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  K              (
5390: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
53a0: 31 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  15<<8)).#define 
53b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c 4f  SQLITE_IOERR_CLO
53c0: 53 45 20 20 20 20 20 20 20 20 20 20 20 20 20 28  SE             (
53d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
53e0: 31 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  16<<8)).#define 
53f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52  SQLITE_IOERR_DIR
5400: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 28  _CLOSE         (
5410: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5420: 31 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  17<<8)).#define 
5430: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
5440: 4f 50 45 4e 20 20 20 20 20 20 20 20 20 20 20 28  OPEN           (
5450: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5460: 31 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  18<<8)).#define 
5470: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
5480: 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 28  SIZE           (
5490: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
54a0: 31 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  19<<8)).#define 
54b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
54c0: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 28  LOCK           (
54d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
54e0: 32 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  20<<8)).#define 
54f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
5500: 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20 28  MAP            (
5510: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5520: 32 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  21<<8)).#define 
5530: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45 45  SQLITE_IOERR_SEE
5540: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  K              (
5550: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5560: 32 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  22<<8)).#define 
5570: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c  SQLITE_IOERR_DEL
5580: 45 54 45 5f 4e 4f 45 4e 54 20 20 20 20 20 20 28  ETE_NOENT      (
5590: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
55a0: 32 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  23<<8)).#define 
55b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4d 4d 41  SQLITE_IOERR_MMA
55c0: 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  P              (
55d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
55e0: 32 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  24<<8)).#define 
55f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 47 45 54  SQLITE_IOERR_GET
5600: 54 45 4d 50 50 41 54 48 20 20 20 20 20 20 20 28  TEMPPATH       (
5610: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5620: 32 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  25<<8)).#define 
5630: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4f 4e  SQLITE_IOERR_CON
5640: 56 50 41 54 48 20 20 20 20 20 20 20 20 20 20 28  VPATH          (
5650: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5660: 32 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  26<<8)).#define 
5670: 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48  SQLITE_LOCKED_SH
5680: 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20 28  AREDCACHE      (
5690: 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20  SQLITE_LOCKED | 
56a0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
56b0: 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 52 45 43   SQLITE_BUSY_REC
56c0: 4f 56 45 52 59 20 20 20 20 20 20 20 20 20 20 20  OVERY           
56d0: 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c  (SQLITE_BUSY   |
56e0: 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e    (1<<8)).#defin
56f0: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 53 4e  e SQLITE_BUSY_SN
5700: 41 50 53 48 4f 54 20 20 20 20 20 20 20 20 20 20  APSHOT          
5710: 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20   (SQLITE_BUSY   
5720: 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69  |  (2<<8)).#defi
5730: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
5740: 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20  EN_NOTEMPDIR    
5750: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50    (SQLITE_CANTOP
5760: 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  EN | (1<<8)).#de
5770: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54  fine SQLITE_CANT
5780: 4f 50 45 4e 5f 49 53 44 49 52 20 20 20 20 20 20  OPEN_ISDIR      
5790: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54      (SQLITE_CANT
57a0: 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29 29 0a 23  OPEN | (2<<8)).#
57b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
57c0: 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 41 54 48 20  NTOPEN_FULLPATH 
57d0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
57e0: 4e 54 4f 50 45 4e 20 7c 20 28 33 3c 3c 38 29 29  NTOPEN | (3<<8))
57f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5800: 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e 56 50 41 54  CANTOPEN_CONVPAT
5810: 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  H       (SQLITE_
5820: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 34 3c 3c 38  CANTOPEN | (4<<8
5830: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5840: 45 5f 43 4f 52 52 55 50 54 5f 56 54 41 42 20 20  E_CORRUPT_VTAB  
5850: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5860: 45 5f 43 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c  E_CORRUPT | (1<<
5870: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5880: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f  TE_READONLY_RECO
5890: 56 45 52 59 20 20 20 20 20 20 20 28 53 51 4c 49  VERY       (SQLI
58a0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31  TE_READONLY | (1
58b0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
58c0: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41  LITE_READONLY_CA
58d0: 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20 28 53 51  NTLOCK       (SQ
58e0: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20  LITE_READONLY | 
58f0: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
5900: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
5910: 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 28  ROLLBACK       (
5920: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
5930: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (3<<8)).#defin
5940: 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52  e SQLITE_ABORT_R
5950: 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 20 20  OLLBACK         
5960: 20 28 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c   (SQLITE_ABORT |
5970: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
5980: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5990: 4e 54 5f 43 48 45 43 4b 20 20 20 20 20 20 20 20  NT_CHECK        
59a0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
59b0: 4e 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  NT | (1<<8)).#de
59c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
59d0: 54 52 41 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f  TRAINT_COMMITHOO
59e0: 4b 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53  K   (SQLITE_CONS
59f0: 54 52 41 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29  TRAINT | (2<<8))
5a00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5a10: 43 4f 4e 53 54 52 41 49 4e 54 5f 46 4f 52 45 49  CONSTRAINT_FOREI
5a20: 47 4e 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f  GNKEY   (SQLITE_
5a30: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 33 3c  CONSTRAINT | (3<
5a40: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5a50: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46  ITE_CONSTRAINT_F
5a60: 55 4e 43 54 49 4f 4e 20 20 20 20 20 28 53 51 4c  UNCTION     (SQL
5a70: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5a80: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
5a90: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5aa0: 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20  NT_NOTNULL      
5ab0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5ac0: 4e 54 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65  NT | (5<<8)).#de
5ad0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5ae0: 54 52 41 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45  TRAINT_PRIMARYKE
5af0: 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53  Y   (SQLITE_CONS
5b00: 54 52 41 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29  TRAINT | (6<<8))
5b10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5b20: 43 4f 4e 53 54 52 41 49 4e 54 5f 54 52 49 47 47  CONSTRAINT_TRIGG
5b30: 45 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  ER      (SQLITE_
5b40: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 37 3c  CONSTRAINT | (7<
5b50: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5b60: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55  ITE_CONSTRAINT_U
5b70: 4e 49 51 55 45 20 20 20 20 20 20 20 28 53 51 4c  NIQUE       (SQL
5b80: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5b90: 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (8<<8)).#define
5ba0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5bb0: 4e 54 5f 56 54 41 42 20 20 20 20 20 20 20 20 20  NT_VTAB         
5bc0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5bd0: 4e 54 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65  NT | (9<<8)).#de
5be0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5bf0: 54 52 41 49 4e 54 5f 52 4f 57 49 44 20 20 20 20  TRAINT_ROWID    
5c00: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5c10: 54 52 41 49 4e 54 20 7c 28 31 30 3c 3c 38 29 29  TRAINT |(10<<8))
5c20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5c30: 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 57  NOTICE_RECOVER_W
5c40: 41 4c 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  AL      (SQLITE_
5c50: 4e 4f 54 49 43 45 20 7c 20 28 31 3c 3c 38 29 29  NOTICE | (1<<8))
5c60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5c70: 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 52  NOTICE_RECOVER_R
5c80: 4f 4c 4c 42 41 43 4b 20 28 53 51 4c 49 54 45 5f  OLLBACK (SQLITE_
5c90: 4e 4f 54 49 43 45 20 7c 20 28 32 3c 3c 38 29 29  NOTICE | (2<<8))
5ca0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5cb0: 57 41 52 4e 49 4e 47 5f 41 55 54 4f 49 4e 44 45  WARNING_AUTOINDE
5cc0: 58 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  X       (SQLITE_
5cd0: 57 41 52 4e 49 4e 47 20 7c 20 28 31 3c 3c 38 29  WARNING | (1<<8)
5ce0: 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  )../*.** CAPI3RE
5cf0: 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c  F: Flags For Fil
5d00: 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e  e Open Operation
5d10: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69  s.**.** These bi
5d20: 74 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74  t values are int
5d30: 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
5d40: 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61   the.** 3rd para
5d50: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  meter to the [sq
5d60: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
5d70: 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a   interface and.*
5d80: 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 72  * in the 4th par
5d90: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ameter to the [s
5da0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
5db0: 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65  ] method..*/.#de
5dc0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5dd0: 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20  _READONLY       
5de0: 20 20 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a    0x00000001  /*
5df0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5e00: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5e10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5e20: 5f 52 45 41 44 57 52 49 54 45 20 20 20 20 20 20  _READWRITE      
5e30: 20 20 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a    0x00000002  /*
5e40: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5e50: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5e60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5e70: 5f 43 52 45 41 54 45 20 20 20 20 20 20 20 20 20  _CREATE         
5e80: 20 20 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a    0x00000004  /*
5e90: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5ea0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5eb0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5ec0: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20  _DELETEONCLOSE  
5ed0: 20 20 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a    0x00000008  /*
5ee0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
5ef0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5f00: 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 20  _EXCLUSIVE      
5f10: 20 20 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a    0x00000010  /*
5f20: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
5f30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5f40: 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20  _AUTOPROXY      
5f50: 20 20 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a    0x00000020  /*
5f60: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
5f70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5f80: 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 20 20  _URI            
5f90: 20 20 30 78 30 30 30 30 30 30 34 30 20 20 2f 2a    0x00000040  /*
5fa0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5fb0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5fc0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5fd0: 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20 20 20 20  _MEMORY         
5fe0: 20 20 30 78 30 30 30 30 30 30 38 30 20 20 2f 2a    0x00000080  /*
5ff0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6000: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6010: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6020: 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20  _MAIN_DB        
6030: 20 20 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a    0x00000100  /*
6040: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6050: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6060: 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20  _TEMP_DB        
6070: 20 20 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a    0x00000200  /*
6080: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6090: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
60a0: 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20  _TRANSIENT_DB   
60b0: 20 20 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a    0x00000400  /*
60c0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
60d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
60e0: 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20  _MAIN_JOURNAL   
60f0: 20 20 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a    0x00000800  /*
6100: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6110: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6120: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20  _TEMP_JOURNAL   
6130: 20 20 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a    0x00001000  /*
6140: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6150: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6160: 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20  _SUBJOURNAL     
6170: 20 20 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a    0x00002000  /*
6180: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6190: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
61a0: 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20  _MASTER_JOURNAL 
61b0: 20 20 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a    0x00004000  /*
61c0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
61d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
61e0: 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20  _NOMUTEX        
61f0: 20 20 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a    0x00008000  /*
6200: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6210: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6220: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6230: 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20  _FULLMUTEX      
6240: 20 20 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a    0x00010000  /*
6250: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6260: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6270: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6280: 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20  _SHAREDCACHE    
6290: 20 20 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a    0x00020000  /*
62a0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
62b0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
62c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
62d0: 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 20 20  _PRIVATECACHE   
62e0: 20 20 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a    0x00040000  /*
62f0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6300: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6310: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6320: 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20  _WAL            
6330: 20 20 30 78 30 30 30 38 30 30 30 30 20 20 2f 2a    0x00080000  /*
6340: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a   VFS only */../*
6350: 20 52 65 73 65 72 76 65 64 3a 20 20 20 20 20 20   Reserved:      
6360: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6370: 20 20 20 30 78 30 30 46 30 30 30 30 30 20 2a 2f     0x00F00000 */
6380: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
6390: 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74  : Device Charact
63a0: 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54  eristics.**.** T
63b0: 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63  he xDeviceCharac
63c0: 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64  teristics method
63d0: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
63e0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  _io_methods].** 
63f0: 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61  object returns a
6400: 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
6410: 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74  is a vector of t
6420: 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75  hese.** bit valu
6430: 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f  es expressing I/
6440: 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 69 63  O characteristic
6450: 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74  s of the mass st
6460: 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20  orage.** device 
6470: 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66  that holds the f
6480: 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73 71  ile that the [sq
6490: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
64a0: 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a  ].** refers to..
64b0: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  **.** The SQLITE
64c0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72  _IOCAP_ATOMIC pr
64d0: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
64e0: 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a  t all writes of.
64f0: 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20  ** any size are 
6500: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
6510: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6520: 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65  nnn values.** me
6530: 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f  an that writes o
6540: 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72  f blocks that ar
6550: 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73  e nnn bytes in s
6560: 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61  ize and.** are a
6570: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64  ligned to an add
6580: 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e  ress which is an
6590: 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c   integer multipl
65a0: 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20  e of.** nnn are 
65b0: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
65c0: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
65d0: 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e  PPEND value mean
65e0: 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64  s.** that when d
65f0: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20  ata is appended 
6600: 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64  to a file, the d
6610: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a  ata is appended.
6620: 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68  ** first then th
6630: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69  e size of the fi
6640: 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20  le is extended, 
6650: 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a  never the other.
6660: 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20  ** way around.  
6670: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
6680: 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70  _SEQUENTIAL prop
6690: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
66a0: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
66b0: 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73  s written to dis
66c0: 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72  k in the same or
66d0: 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20  der as calls.** 
66e0: 74 6f 20 78 57 72 69 74 65 28 29 2e 20 20 54 68  to xWrite().  Th
66f0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50  e SQLITE_IOCAP_P
6700: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
6710: 54 45 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  TE property mean
6720: 73 20 74 68 61 74 0a 2a 2a 20 61 66 74 65 72 20  s that.** after 
6730: 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e 67  reboot following
6740: 20 61 20 63 72 61 73 68 20 6f 72 20 70 6f 77 65   a crash or powe
6750: 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f 6e 6c 79  r loss, the only
6760: 20 62 79 74 65 73 20 69 6e 20 61 0a 2a 2a 20 66   bytes in a.** f
6770: 69 6c 65 20 74 68 61 74 20 77 65 72 65 20 77 72  ile that were wr
6780: 69 74 74 65 6e 20 61 74 20 74 68 65 20 61 70 70  itten at the app
6790: 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65 6c 20 6d  lication level m
67a0: 69 67 68 74 20 68 61 76 65 20 63 68 61 6e 67 65  ight have change
67b0: 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 61 64  d.** and that ad
67c0: 6a 61 63 65 6e 74 20 62 79 74 65 73 2c 20 65 76  jacent bytes, ev
67d0: 65 6e 20 62 79 74 65 73 20 77 69 74 68 69 6e 20  en bytes within 
67e0: 74 68 65 20 73 61 6d 65 20 73 65 63 74 6f 72 20  the same sector 
67f0: 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65  are.** guarantee
6800: 64 20 74 6f 20 62 65 20 75 6e 63 68 61 6e 67 65  d to be unchange
6810: 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  d..*/.#define SQ
6820: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6830: 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  C               
6840: 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 65    0x00000001.#de
6850: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6860: 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20  P_ATOMIC512     
6870: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6880: 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  002.#define SQLI
6890: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
68a0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
68b0: 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69  0x00000004.#defi
68c0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
68d0: 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20  ATOMIC2K        
68e0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
68f0: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
6900: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20  _IOCAP_ATOMIC4K 
6910: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6920: 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65  00000010.#define
6930: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6940: 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 20 20  OMIC8K          
6950: 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30 0a       0x00000020.
6960: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6970: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20  OCAP_ATOMIC16K  
6980: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6990: 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53  000040.#define S
69a0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
69b0: 49 43 33 32 4b 20 20 20 20 20 20 20 20 20 20 20  IC32K           
69c0: 20 20 20 30 78 30 30 30 30 30 30 38 30 0a 23 64     0x00000080.#d
69d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
69e0: 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20  AP_ATOMIC64K    
69f0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6a00: 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0100.#define SQL
6a10: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
6a20: 50 50 45 4e 44 20 20 20 20 20 20 20 20 20 20 20  PPEND           
6a30: 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66   0x00000200.#def
6a40: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6a50: 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20  _SEQUENTIAL     
6a60: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 34          0x000004
6a70: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
6a80: 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41  E_IOCAP_UNDELETA
6a90: 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30  BLE_WHEN_OPEN  0
6aa0: 78 30 30 30 30 30 38 30 30 0a 23 64 65 66 69 6e  x00000800.#defin
6ab0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50  e SQLITE_IOCAP_P
6ac0: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
6ad0: 54 45 20 20 20 20 30 78 30 30 30 30 31 30 30 30  TE    0x00001000
6ae0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
6af0: 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c  : File Locking L
6b00: 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  evels.**.** SQLi
6b10: 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20 74  te uses one of t
6b20: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c  hese integer val
6b30: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ues as the secon
6b40: 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f  d.** argument to
6b50: 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20   calls it makes 
6b60: 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20 61  to the xLock() a
6b70: 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74  nd xUnlock() met
6b80: 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73  hods.** of an [s
6b90: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
6ba0: 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64  s] object..*/.#d
6bb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
6bc0: 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20 20  K_NONE          
6bd0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6be0: 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20 20  _LOCK_SHARED    
6bf0: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
6c00: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
6c10: 45 44 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e  ED      2.#defin
6c20: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45  e SQLITE_LOCK_PE
6c30: 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23 64  NDING       3.#d
6c40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
6c50: 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20  K_EXCLUSIVE     
6c60: 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  4../*.** CAPI3RE
6c70: 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69  F: Synchronizati
6c80: 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a  on Type Flags.**
6c90: 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 20  .** When SQLite 
6ca0: 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 79 6e  invokes the xSyn
6cb0: 63 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e  c() method of an
6cc0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  .** [sqlite3_io_
6cd0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
6ce0: 69 74 20 75 73 65 73 20 61 20 63 6f 6d 62 69 6e  it uses a combin
6cf0: 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73  ation of.** thes
6d00: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
6d10: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   as the second a
6d20: 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57  rgument..**.** W
6d30: 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 53  hen the SQLITE_S
6d40: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61  YNC_DATAONLY fla
6d50: 67 20 69 73 20 75 73 65 64 2c 20 69 74 20 6d 65  g is used, it me
6d60: 61 6e 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ans that the.** 
6d70: 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f  sync operation o
6d80: 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 66 6c 75  nly needs to flu
6d90: 73 68 20 64 61 74 61 20 74 6f 20 6d 61 73 73 20  sh data to mass 
6da0: 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a  storage.  Inode.
6db0: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e  ** information n
6dc0: 65 65 64 20 6e 6f 74 20 62 65 20 66 6c 75 73 68  eed not be flush
6dd0: 65 64 2e 20 49 66 20 74 68 65 20 6c 6f 77 65 72  ed. If the lower
6de0: 20 66 6f 75 72 20 62 69 74 73 20 6f 66 20 74 68   four bits of th
6df0: 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20  e flag.** equal 
6e00: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
6e10: 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  AL, that means t
6e20: 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79  o use normal fsy
6e30: 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a  nc() semantics..
6e40: 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20  ** If the lower 
6e50: 66 6f 75 72 20 62 69 74 73 20 65 71 75 61 6c 20  four bits equal 
6e60: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
6e70: 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20  , that means.** 
6e80: 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 20 58 20  to use Mac OS X 
6e90: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69  style fullsync i
6ea0: 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28  nstead of fsync(
6eb0: 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20  )..**.** Do not 
6ec0: 63 6f 6e 66 75 73 65 20 74 68 65 20 53 51 4c 49  confuse the SQLI
6ed0: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61  TE_SYNC_NORMAL a
6ee0: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  nd SQLITE_SYNC_F
6ef0: 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74  ULL flags.** wit
6f00: 68 20 74 68 65 20 5b 50 52 41 47 4d 41 20 73 79  h the [PRAGMA sy
6f10: 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41  nchronous]=NORMA
6f20: 4c 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 73 79  L and [PRAGMA sy
6f30: 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a  nchronous]=FULL.
6f40: 2a 2a 20 73 65 74 74 69 6e 67 73 2e 20 20 54 68  ** settings.  Th
6f50: 65 20 5b 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70  e [synchronous p
6f60: 72 61 67 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65  ragma] determine
6f70: 73 20 77 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20  s when calls to 
6f80: 74 68 65 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53  the.** xSync VFS
6f90: 20 6d 65 74 68 6f 64 20 6f 63 63 75 72 20 61 6e   method occur an
6fa0: 64 20 61 70 70 6c 69 65 73 20 75 6e 69 66 6f 72  d applies unifor
6fb0: 6d 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c 20 70  mly across all p
6fc0: 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65  latforms..** The
6fd0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52   SQLITE_SYNC_NOR
6fe0: 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53  MAL and SQLITE_S
6ff0: 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64  YNC_FULL flags d
7000: 65 74 65 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20  etermine how.** 
7010: 65 6e 65 72 67 65 74 69 63 20 6f 72 20 72 69 67  energetic or rig
7020: 6f 72 6f 75 73 20 6f 72 20 66 6f 72 63 65 66 75  orous or forcefu
7030: 6c 20 74 68 65 20 73 79 6e 63 20 6f 70 65 72 61  l the sync opera
7040: 74 69 6f 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a  tions are and.**
7050: 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 20 64 69 66   only make a dif
7060: 66 65 72 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f  ference on Mac O
7070: 53 58 20 66 6f 72 20 74 68 65 20 64 65 66 61 75  SX for the defau
7080: 6c 74 20 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a  lt SQLite code..
7090: 2a 2a 20 28 54 68 69 72 64 2d 70 61 72 74 79 20  ** (Third-party 
70a0: 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
70b0: 6f 6e 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d  ons might also m
70c0: 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74  ake the distinct
70d0: 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53  ion.** between S
70e0: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
70f0: 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e  L and SQLITE_SYN
7100: 43 5f 46 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e  C_FULL, but amon
7110: 67 20 74 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69  g the.** operati
7120: 6e 67 20 73 79 73 74 65 6d 73 20 6e 61 74 69 76  ng systems nativ
7130: 65 6c 79 20 73 75 70 70 6f 72 74 65 64 20 62 79  ely supported by
7140: 20 53 51 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61   SQLite, only Ma
7150: 63 20 4f 53 58 0a 2a 2a 20 63 61 72 65 73 20 61  c OSX.** cares a
7160: 62 6f 75 74 20 74 68 65 20 64 69 66 66 65 72 65  bout the differe
7170: 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65  nce.).*/.#define
7180: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52   SQLITE_SYNC_NOR
7190: 4d 41 4c 20 20 20 20 20 20 20 20 30 78 30 30 30  MAL        0x000
71a0: 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  02.#define SQLIT
71b0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20  E_SYNC_FULL     
71c0: 20 20 20 20 20 30 78 30 30 30 30 33 0a 23 64 65       0x00003.#de
71d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
71e0: 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30  _DATAONLY      0
71f0: 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  x00010../*.** CA
7200: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
7210: 66 61 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48  face Open File H
7220: 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b  andle.**.** An [
7230: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
7240: 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20  ject represents 
7250: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20  an open file in 
7260: 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  the .** [sqlite3
7270: 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74 65 72 66  _vfs | OS interf
7280: 61 63 65 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64  ace layer].  Ind
7290: 69 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72  ividual OS inter
72a0: 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  face.** implemen
72b0: 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20  tations will.** 
72c0: 77 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73  want to subclass
72d0: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20   this object by 
72e0: 61 70 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69  appending additi
72f0: 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66  onal fields.** f
7300: 6f 72 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65  or their own use
7310: 2e 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20  .  The pMethods 
7320: 65 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74  entry is a point
7330: 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c  er to an.** [sql
7340: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
7350: 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66   object that def
7360: 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72  ines methods for
7370: 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49   performing.** I
7380: 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e  /O operations on
7390: 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a   the open file..
73a0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
73b0: 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73  t sqlite3_file s
73c0: 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72  qlite3_file;.str
73d0: 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  uct sqlite3_file
73e0: 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63   {.  const struc
73f0: 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  t sqlite3_io_met
7400: 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20  hods *pMethods; 
7410: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20   /* Methods for 
7420: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a  an open file */.
7430: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
7440: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65  EF: OS Interface
7450: 20 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65   File Virtual Me
7460: 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a  thods Object.**.
7470: 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70  ** Every file op
7480: 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  ened by the [sql
7490: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
74a0: 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 73  method populates
74b0: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
74c0: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72  file] object (or
74d0: 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c  , more commonly,
74e0: 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74   a subclass of t
74f0: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  he.** [sqlite3_f
7500: 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 74  ile] object) wit
7510: 68 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  h a pointer to a
7520: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
7530: 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68  is object..** Th
7540: 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  is object define
7550: 73 20 74 68 65 20 6d 65 74 68 6f 64 73 20 75 73  s the methods us
7560: 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61  ed to perform va
7570: 72 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73  rious operations
7580: 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 65 20  .** against the 
7590: 6f 70 65 6e 20 66 69 6c 65 20 72 65 70 72 65 73  open file repres
75a0: 65 6e 74 65 64 20 62 79 20 74 68 65 20 5b 73 71  ented by the [sq
75b0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
75c0: 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ct..**.** If the
75d0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
75e0: 70 65 6e 5d 20 6d 65 74 68 6f 64 20 73 65 74 73  pen] method sets
75f0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
7600: 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65  e.pMethods eleme
7610: 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d  nt .** to a non-
7620: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68  NULL pointer, th
7630: 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  en the sqlite3_i
7640: 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65  o_methods.xClose
7650: 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62   method.** may b
7660: 65 20 69 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69  e invoked even i
7670: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  f the [sqlite3_v
7680: 66 73 2e 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74  fs.xOpen] report
7690: 65 64 20 74 68 61 74 20 69 74 20 66 61 69 6c 65  ed that it faile
76a0: 64 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20  d.  The.** only 
76b0: 77 61 79 20 74 6f 20 70 72 65 76 65 6e 74 20 61  way to prevent a
76c0: 20 63 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20   call to xClose 
76d0: 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c  following a fail
76e0: 65 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  ed [sqlite3_vfs.
76f0: 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72  xOpen].** is for
7700: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
7710: 73 2e 78 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20  s.xOpen] to set 
7720: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  the sqlite3_file
7730: 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e  .pMethods elemen
7740: 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a  t.** to NULL..**
7750: 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72  .** The flags ar
7760: 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20  gument to xSync 
7770: 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53  may be one of [S
7780: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
7790: 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  L] or.** [SQLITE
77a0: 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68  _SYNC_FULL].  Th
77b0: 65 20 66 69 72 73 74 20 63 68 6f 69 63 65 20 69  e first choice i
77c0: 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79  s the normal fsy
77d0: 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63  nc()..** The sec
77e0: 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61 20  ond choice is a 
77f0: 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66  Mac OS X style f
7800: 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b 53  ullsync.  The [S
7810: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
7820: 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79  NLY].** flag may
7830: 20 62 65 20 4f 52 65 64 20 69 6e 20 74 6f 20 69   be ORed in to i
7840: 6e 64 69 63 61 74 65 20 74 68 61 74 20 6f 6e 6c  ndicate that onl
7850: 79 20 74 68 65 20 64 61 74 61 20 6f 66 20 74 68  y the data of th
7860: 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f  e file.** and no
7870: 74 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64  t its inode need
7880: 73 20 74 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a  s to be synced..
7890: 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65  **.** The intege
78a0: 72 20 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63  r values to xLoc
78b0: 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28  k() and xUnlock(
78c0: 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20  ) are one of.** 
78d0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
78e0: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c  LITE_LOCK_NONE],
78f0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7900: 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a  _LOCK_SHARED],.*
7910: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
7920: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a  OCK_RESERVED],.*
7930: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
7940: 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72  OCK_PENDING], or
7950: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7960: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d  _LOCK_EXCLUSIVE]
7970: 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c  ..** </ul>.** xL
7980: 6f 63 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20  ock() increases 
7990: 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63  the lock. xUnloc
79a0: 6b 28 29 20 64 65 63 72 65 61 73 65 73 20 74 68  k() decreases th
79b0: 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78  e lock..** The x
79c0: 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63  CheckReservedLoc
79d0: 6b 28 29 20 6d 65 74 68 6f 64 20 63 68 65 63 6b  k() method check
79e0: 73 20 77 68 65 74 68 65 72 20 61 6e 79 20 64 61  s whether any da
79f0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
7a00: 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e 20  n,.** either in 
7a10: 74 68 69 73 20 70 72 6f 63 65 73 73 20 6f 72 20  this process or 
7a20: 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72  in some other pr
7a30: 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e  ocess, is holdin
7a40: 67 20 61 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a  g a RESERVED,.**
7a50: 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43   PENDING, or EXC
7a60: 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74  LUSIVE lock on t
7a70: 68 65 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74  he file.  It ret
7a80: 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20  urns true.** if 
7a90: 73 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73  such a lock exis
7aa0: 74 73 20 61 6e 64 20 66 61 6c 73 65 20 6f 74 68  ts and false oth
7ab0: 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  erwise..**.** Th
7ac0: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29  e xFileControl()
7ad0: 20 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e   method is a gen
7ae0: 65 72 69 63 20 69 6e 74 65 72 66 61 63 65 20 74  eric interface t
7af0: 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f  hat allows custo
7b00: 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65  m.** VFS impleme
7b10: 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65  ntations to dire
7b20: 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20  ctly control an 
7b30: 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20  open file using 
7b40: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
7b50: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
7b60: 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20  interface.  The 
7b70: 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75  second "op" argu
7b80: 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e  ment is an.** in
7b90: 74 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 54  teger opcode.  T
7ba0: 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
7bb0: 74 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 70  t is a generic p
7bc0: 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64 65 64 20  ointer intended 
7bd0: 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61  to.** point to a
7be0: 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20   structure that 
7bf0: 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75  may contain argu
7c00: 6d 65 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69  ments or space i
7c10: 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72  n which to.** wr
7c20: 69 74 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  ite return value
7c30: 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73  s.  Potential us
7c40: 65 73 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74  es for xFileCont
7c50: 72 6f 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 2a  rol() might be.*
7c60: 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65  * functions to e
7c70: 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c  nable blocking l
7c80: 6f 63 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75  ocks with timeou
7c90: 74 73 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68  ts, to change th
7ca0: 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72  e.** locking str
7cb0: 61 74 65 67 79 20 28 66 6f 72 20 65 78 61 6d 70  ategy (for examp
7cc0: 6c 65 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 69  le to use dot-fi
7cd0: 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e  le locks), to in
7ce0: 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74  quire.** about t
7cf0: 68 65 20 73 74 61 74 75 73 20 6f 66 20 61 20 6c  he status of a l
7d00: 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b  ock, or to break
7d10: 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54   stale locks.  T
7d20: 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72  he SQLite.** cor
7d30: 65 20 72 65 73 65 72 76 65 73 20 61 6c 6c 20 6f  e reserves all o
7d40: 70 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e  pcodes less than
7d50: 20 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e   100 for its own
7d60: 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49   use..** A [SQLI
7d70: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
7d80: 54 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63  TE | list of opc
7d90: 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61 6e 20  odes] less than 
7da0: 31 30 30 20 69 73 20 61 76 61 69 6c 61 62 6c 65  100 is available
7db0: 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  ..** Application
7dc0: 73 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 20  s that define a 
7dd0: 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74  custom xFileCont
7de0: 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c  rol method shoul
7df0: 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a  d use opcodes.**
7e00: 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 30   greater than 10
7e10: 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c  0 to avoid confl
7e20: 69 63 74 73 2e 20 20 56 46 53 20 69 6d 70 6c 65  icts.  VFS imple
7e30: 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c  mentations shoul
7e40: 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  d.** return [SQL
7e50: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f  ITE_NOTFOUND] fo
7e60: 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f  r file control o
7e70: 70 63 6f 64 65 73 20 74 68 61 74 20 74 68 65 79  pcodes that they
7e80: 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67   do not.** recog
7e90: 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nize..**.** The 
7ea0: 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20 6d 65  xSectorSize() me
7eb0: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74 68 65  thod returns the
7ec0: 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f 66 20   sector size of 
7ed0: 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68  the.** device th
7ee0: 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74 68 65  at underlies the
7ef0: 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65 63 74   file.  The sect
7f00: 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65 0a 2a  or size is the.*
7f10: 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65 20  * minimum write 
7f20: 74 68 61 74 20 63 61 6e 20 62 65 20 70 65 72 66  that can be perf
7f30: 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20 64 69  ormed without di
7f40: 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65  sturbing.** othe
7f50: 72 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66  r bytes in the f
7f60: 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76 69 63  ile.  The xDevic
7f70: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
7f80: 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74  ().** method ret
7f90: 75 72 6e 73 20 61 20 62 69 74 20 76 65 63 74 6f  urns a bit vecto
7fa0: 72 20 64 65 73 63 72 69 62 69 6e 67 20 62 65 68  r describing beh
7fb0: 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a  aviors of the.**
7fc0: 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 76 69   underlying devi
7fd0: 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ce:.**.** <ul>.*
7fe0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
7ff0: 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20  OCAP_ATOMIC].** 
8000: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
8010: 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a  AP_ATOMIC512].**
8020: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
8030: 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a  CAP_ATOMIC1K].**
8040: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
8050: 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a  CAP_ATOMIC2K].**
8060: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
8070: 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a  CAP_ATOMIC4K].**
8080: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
8090: 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a  CAP_ATOMIC8K].**
80a0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
80b0: 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a  CAP_ATOMIC16K].*
80c0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
80d0: 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a  OCAP_ATOMIC32K].
80e0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
80f0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d  IOCAP_ATOMIC64K]
8100: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8110: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
8120: 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ND].** <li> [SQL
8130: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
8140: 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  TIAL].** </ul>.*
8150: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  *.** The SQLITE_
8160: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f  IOCAP_ATOMIC pro
8170: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
8180: 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a   all writes of.*
8190: 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61  * any size are a
81a0: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
81b0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e  TE_IOCAP_ATOMICn
81c0: 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61  nn values.** mea
81d0: 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66  n that writes of
81e0: 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65   blocks that are
81f0: 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69   nnn bytes in si
8200: 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c  ze and.** are al
8210: 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72  igned to an addr
8220: 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20  ess which is an 
8230: 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65  integer multiple
8240: 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61   of.** nnn are a
8250: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
8260: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
8270: 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73  PEND value means
8280: 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61  .** that when da
8290: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74  ta is appended t
82a0: 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61  o a file, the da
82b0: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a  ta is appended.*
82c0: 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65  * first then the
82d0: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c   size of the fil
82e0: 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e  e is extended, n
82f0: 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a  ever the other.*
8300: 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54  * way around.  T
8310: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
8320: 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65  SEQUENTIAL prope
8330: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a  rty means that.*
8340: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
8350: 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b   written to disk
8360: 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64   in the same ord
8370: 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74  er as calls.** t
8380: 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a  o xWrite()..**.*
8390: 2a 20 49 66 20 78 52 65 61 64 28 29 20 72 65 74  * If xRead() ret
83a0: 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52  urns SQLITE_IOER
83b0: 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20  R_SHORT_READ it 
83c0: 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a  must also fill.*
83d0: 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20  * in the unread 
83e0: 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  portions of the 
83f0: 62 75 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f  buffer with zero
8400: 73 2e 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a  s.  A VFS that.*
8410: 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d  * fails to zero-
8420: 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73  fill short reads
8430: 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77   might seem to w
8440: 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a  ork.  However,.*
8450: 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72  * failure to zer
8460: 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61  o-fill short rea
8470: 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c  ds will eventual
8480: 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61  ly lead to.** da
8490: 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f  tabase corruptio
84a0: 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  n..*/.typedef st
84b0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
84c0: 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f  methods sqlite3_
84d0: 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75  io_methods;.stru
84e0: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ct sqlite3_io_me
84f0: 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56  thods {.  int iV
8500: 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a  ersion;.  int (*
8510: 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  xClose)(sqlite3_
8520: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
8530: 78 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66  xRead)(sqlite3_f
8540: 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74  ile*, void*, int
8550: 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69   iAmt, sqlite3_i
8560: 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69  nt64 iOfst);.  i
8570: 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c  nt (*xWrite)(sql
8580: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73  ite3_file*, cons
8590: 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  t void*, int iAm
85a0: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
85b0: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
85c0: 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69  *xTruncate)(sqli
85d0: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
85e0: 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a  e3_int64 size);.
85f0: 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73    int (*xSync)(s
8600: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8610: 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20  t flags);.  int 
8620: 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c  (*xFileSize)(sql
8630: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
8640: 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65  te3_int64 *pSize
8650: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b  );.  int (*xLock
8660: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8670: 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78   int);.  int (*x
8680: 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  Unlock)(sqlite3_
8690: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  file*, int);.  i
86a0: 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72  nt (*xCheckReser
86b0: 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33  vedLock)(sqlite3
86c0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65  _file*, int *pRe
86d0: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sOut);.  int (*x
86e0: 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c  FileControl)(sql
86f0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
8700: 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b  op, void *pArg);
8710: 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72  .  int (*xSector
8720: 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69  Size)(sqlite3_fi
8730: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44  le*);.  int (*xD
8740: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
8750: 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69  tics)(sqlite3_fi
8760: 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f  le*);.  /* Metho
8770: 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c  ds above are val
8780: 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 31  id for version 1
8790: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d   */.  int (*xShm
87a0: 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  Map)(sqlite3_fil
87b0: 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e 74  e*, int iPg, int
87c0: 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64   pgsz, int, void
87d0: 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20   volatile**);.  
87e0: 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28  int (*xShmLock)(
87f0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8800: 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e  nt offset, int n
8810: 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20  , int flags);.  
8820: 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 72 69  void (*xShmBarri
8830: 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  er)(sqlite3_file
8840: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d  *);.  int (*xShm
8850: 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 5f 66  Unmap)(sqlite3_f
8860: 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65  ile*, int delete
8870: 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68  Flag);.  /* Meth
8880: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61  ods above are va
8890: 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20  lid for version 
88a0: 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 46 65  2 */.  int (*xFe
88b0: 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  tch)(sqlite3_fil
88c0: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
88d0: 34 20 69 4f 66 73 74 2c 20 69 6e 74 20 69 41 6d  4 iOfst, int iAm
88e0: 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29 3b 0a 20  t, void **pp);. 
88f0: 20 69 6e 74 20 28 2a 78 55 6e 66 65 74 63 68 29   int (*xUnfetch)
8900: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8910: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f  sqlite3_int64 iO
8920: 66 73 74 2c 20 76 6f 69 64 20 2a 70 29 3b 0a 20  fst, void *p);. 
8930: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76   /* Methods abov
8940: 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20  e are valid for 
8950: 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a 20 20 2f  version 3 */.  /
8960: 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74  * Additional met
8970: 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65  hods may be adde
8980: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
8990: 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  ases */.};../*.*
89a0: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e  * CAPI3REF: Stan
89b0: 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f  dard File Contro
89c0: 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  l Opcodes.**.** 
89d0: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  These integer co
89e0: 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f  nstants are opco
89f0: 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c  des for the xFil
8a00: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a  eControl method.
8a10: 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
8a20: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
8a30: 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68  bject and for th
8a40: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  e [sqlite3_file_
8a50: 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e  control()].** in
8a60: 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54  terface..**.** T
8a70: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
8a80: 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f  _LOCKSTATE] opco
8a90: 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64  de is used for d
8aa0: 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a  ebugging.  This.
8ab0: 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73  ** opcode causes
8ac0: 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   the xFileContro
8ad0: 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74  l method to writ
8ae0: 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74  e the current st
8af0: 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f  ate of.** the lo
8b00: 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49  ck (one of [SQLI
8b10: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b  TE_LOCK_NONE], [
8b20: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
8b30: 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ED],.** [SQLITE_
8b40: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20  LOCK_RESERVED], 
8b50: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e  [SQLITE_LOCK_PEN
8b60: 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  DING], or [SQLIT
8b70: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45  E_LOCK_EXCLUSIVE
8b80: 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e  ]).** into an in
8b90: 74 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70  teger that the p
8ba0: 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  Arg argument poi
8bb0: 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70  nts to. This cap
8bc0: 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73  ability.** is us
8bd0: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
8be0: 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73  g and only needs
8bf0: 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
8c00: 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53   when SQLITE_TES
8c10: 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e  T.** is defined.
8c20: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
8c30: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  [[SQLITE_FCNTL_S
8c40: 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68  IZE_HINT]].** Th
8c50: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
8c60: 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64  SIZE_HINT] opcod
8c70: 65 20 69 73 20 75 73 65 64 20 62 79 20 53 51 4c  e is used by SQL
8c80: 69 74 65 20 74 6f 20 67 69 76 65 20 74 68 65 20  ite to give the 
8c90: 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68  VFS.** layer a h
8ca0: 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65  int of how large
8cb0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
8cc0: 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20  le will grow to 
8cd0: 62 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a  be during the.**
8ce0: 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63   current transac
8cf0: 74 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74  tion.  This hint
8d00: 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65   is not guarante
8d10: 65 64 20 74 6f 20 62 65 20 61 63 63 75 72 61 74  ed to be accurat
8d20: 65 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f  e but it.** is o
8d30: 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65  ften close.  The
8d40: 20 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20   underlying VFS 
8d50: 6d 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20  might choose to 
8d60: 70 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61  preallocate data
8d70: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61  base.** file spa
8d80: 63 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73  ce based on this
8d90: 20 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74   hint in order t
8da0: 6f 20 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f  o help writes to
8db0: 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
8dc0: 20 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72   file run faster
8dd0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
8de0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b  LITE_FCNTL_CHUNK
8df0: 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  _SIZE]].** The [
8e00: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55  SQLITE_FCNTL_CHU
8e10: 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20  NK_SIZE] opcode 
8e20: 69 73 20 75 73 65 64 20 74 6f 20 72 65 71 75 65  is used to reque
8e30: 73 74 20 74 68 61 74 20 74 68 65 20 56 46 53 0a  st that the VFS.
8e40: 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74  ** extends and t
8e50: 72 75 6e 63 61 74 65 73 20 74 68 65 20 64 61 74  runcates the dat
8e60: 61 62 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68  abase file in ch
8e70: 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73  unks of a size s
8e80: 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74  pecified.** by t
8e90: 68 65 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75  he user. The fou
8ea0: 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rth argument to 
8eb0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
8ec0: 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20  ntrol()] should 
8ed0: 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20  .** point to an 
8ee0: 69 6e 74 65 67 65 72 20 28 74 79 70 65 20 69 6e  integer (type in
8ef0: 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  t) containing th
8f00: 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65  e new chunk-size
8f10: 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74   to use.** for t
8f20: 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74  he nominated dat
8f30: 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e  abase. Allocatin
8f40: 67 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  g database file 
8f50: 73 70 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a  space in large.*
8f60: 2a 20 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d  * chunks (say 1M
8f70: 42 20 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61  B at a time), ma
8f80: 79 20 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79  y reduce file-sy
8f90: 73 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69  stem fragmentati
8fa0: 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76  on and.** improv
8fb0: 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e  e performance on
8fc0: 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a   some systems..*
8fd0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
8fe0: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49  E_FCNTL_FILE_POI
8ff0: 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  NTER]].** The [S
9000: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45  QLITE_FCNTL_FILE
9010: 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65  _POINTER] opcode
9020: 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61   is used to obta
9030: 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  in a pointer.** 
9040: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
9050: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73  file] object ass
9060: 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 70  ociated with a p
9070: 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61  articular databa
9080: 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
9090: 2e 20 20 53 65 65 20 74 68 65 20 5b 73 71 6c 69  .  See the [sqli
90a0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
90b0: 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  ()] documentatio
90c0: 6e 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f  n for.** additio
90d0: 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
90e0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
90f0: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f  ITE_FCNTL_SYNC_O
9100: 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 5e 28 54 68  MITTED]].** ^(Th
9110: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
9120: 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 20 6f 70  SYNC_OMITTED] op
9130: 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 65  code is generate
9140: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 0a  d internally by.
9150: 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 73 65  ** SQLite and se
9160: 6e 74 20 74 6f 20 61 6c 6c 20 56 46 53 65 73 20  nt to all VFSes 
9170: 69 6e 20 70 6c 61 63 65 20 6f 66 20 61 20 63 61  in place of a ca
9180: 6c 6c 20 74 6f 20 74 68 65 20 78 53 79 6e 63 20  ll to the xSync 
9190: 6d 65 74 68 6f 64 0a 2a 2a 20 77 68 65 6e 20 74  method.** when t
91a0: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
91b0: 65 63 74 69 6f 6e 20 68 61 73 20 5b 50 52 41 47  ection has [PRAG
91c0: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 20  MA synchronous] 
91d0: 73 65 74 20 74 6f 20 4f 46 46 2e 29 5e 0a 2a 2a  set to OFF.)^.**
91e0: 20 53 6f 6d 65 20 73 70 65 63 69 61 6c 69 7a 65   Some specialize
91f0: 64 20 56 46 53 65 73 20 6e 65 65 64 20 74 68 69  d VFSes need thi
9200: 73 20 73 69 67 6e 61 6c 20 69 6e 20 6f 72 64 65  s signal in orde
9210: 72 20 74 6f 20 6f 70 65 72 61 74 65 20 63 6f 72  r to operate cor
9220: 72 65 63 74 6c 79 0a 2a 2a 20 77 68 65 6e 20 5b  rectly.** when [
9230: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
9240: 75 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63  us | PRAGMA sync
9250: 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 73 20  hronous=OFF] is 
9260: 73 65 74 2c 20 62 75 74 20 6d 6f 73 74 20 0a 2a  set, but most .*
9270: 2a 20 56 46 53 65 73 20 64 6f 20 6e 6f 74 20 6e  * VFSes do not n
9280: 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20  eed this signal 
9290: 61 6e 64 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e  and should silen
92a0: 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20  tly ignore this 
92b0: 6f 70 63 6f 64 65 2e 0a 2a 2a 20 41 70 70 6c 69  opcode..** Appli
92c0: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e  cations should n
92d0: 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33  ot call [sqlite3
92e0: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
92f0: 20 77 69 74 68 20 74 68 69 73 0a 2a 2a 20 6f 70   with this.** op
9300: 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f  code as doing so
9310: 20 6d 61 79 20 64 69 73 72 75 70 74 20 74 68 65   may disrupt the
9320: 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68   operation of th
9330: 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46  e specialized VF
9340: 53 65 73 0a 2a 2a 20 74 68 61 74 20 64 6f 20 72  Ses.** that do r
9350: 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a  equire it.  .**.
9360: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9370: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52  FCNTL_WIN32_AV_R
9380: 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  ETRY]].** ^The [
9390: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
93a0: 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63  32_AV_RETRY] opc
93b0: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63  ode is used to c
93c0: 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74  onfigure automat
93d0: 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e  ic.** retry coun
93e0: 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73  ts and intervals
93f0: 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73   for certain dis
9400: 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73  k I/O operations
9410: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64   for the.** wind
9420: 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64  ows [VFS] in ord
9430: 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f  er to provide ro
9440: 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20  bustness in the 
9450: 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61  presence of.** a
9460: 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61  nti-virus progra
9470: 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c  ms.  By default,
9480: 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53   the windows VFS
9490: 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65   will retry file
94a0: 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77   read,.** file w
94b0: 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64  rite, and file d
94c0: 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73  elete operations
94d0: 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c   up to 10 times,
94e0: 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a   with a delay.**
94f0: 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f   of 25 milliseco
9500: 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66  nds before the f
9510: 69 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77  irst retry and w
9520: 69 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e  ith the delay in
9530: 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61  creasing.** by a
9540: 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20  n additional 25 
9550: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74  milliseconds wit
9560: 68 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e  h each subsequen
9570: 74 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a  t retry.  This.*
9580: 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20  * opcode allows 
9590: 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73  these two values
95a0: 20 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64   (10 retries and
95b0: 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   25 milliseconds
95c0: 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f   of delay).** to
95d0: 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54   be adjusted.  T
95e0: 68 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68  he values are ch
95f0: 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61  anged for all da
9600: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
9610: 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65  ns.** within the
9620: 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20   same process.  
9630: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
9640: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
9650: 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20  array of two.** 
9660: 69 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74  integers where t
9670: 68 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72  he first integer
9680: 20 69 20 74 68 65 20 6e 65 77 20 72 65 74 72 79   i the new retry
9690: 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73   count and the s
96a0: 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72  econd.** integer
96b0: 20 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20   is the delay.  
96c0: 49 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65  If either intege
96d0: 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  r is negative, t
96e0: 68 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a  hen the setting.
96f0: 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65  ** is not change
9700: 64 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68  d but instead th
9710: 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66  e prior value of
9720: 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73   that setting is
9730: 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f   written.** into
9740: 20 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79   the array entry
9750: 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63  , allowing the c
9760: 75 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74  urrent retry set
9770: 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69  tings to be.** i
9780: 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68  nterrogated.  Th
9790: 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65  e zDbName parame
97a0: 74 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a  ter is ignored..
97b0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
97c0: 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54  TE_FCNTL_PERSIST
97d0: 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  _WAL]].** ^The [
97e0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52  SQLITE_FCNTL_PER
97f0: 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65  SIST_WAL] opcode
9800: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20   is used to set 
9810: 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20  or query the.** 
9820: 70 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20  persistent [WAL 
9830: 7c 20 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f  | Write Ahead Lo
9840: 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20  g] setting.  By 
9850: 64 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78  default, the aux
9860: 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20  iliary.** write 
9870: 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68  ahead log and sh
9880: 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65  ared memory file
9890: 73 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73  s used for trans
98a0: 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a  action control.*
98b0: 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61  * are automatica
98c0: 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e  lly deleted when
98d0: 20 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e   the latest conn
98e0: 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61  ection to the da
98f0: 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73  tabase.** closes
9900: 2e 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69  .  Setting persi
9910: 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63  stent WAL mode c
9920: 61 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65  auses those file
9930: 73 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74  s to persist aft
9940: 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65  er.** close.  Pe
9950: 72 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c  rsisting the fil
9960: 65 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65  es is useful whe
9970: 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65  n other processe
9980: 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a  s that do not.**
9990: 20 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d   have write perm
99a0: 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69  ission on the di
99b0: 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69  rectory containi
99c0: 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ng the database 
99d0: 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20  file want.** to 
99e0: 72 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73  read the databas
99f0: 65 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57  e file, as the W
9a00: 41 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65  AL and shared me
9a10: 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20  mory files must 
9a20: 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65  exist.** in orde
9a30: 72 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61  r for the databa
9a40: 73 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c  se to be readabl
9a50: 65 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70  e.  The fourth p
9a60: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b  arameter to.** [
9a70: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
9a80: 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73  trol()] for this
9a90: 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62   opcode should b
9aa0: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
9ab0: 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68  n integer..** Th
9ac0: 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20  at integer is 0 
9ad0: 74 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69  to disable persi
9ae0: 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f  stent WAL mode o
9af0: 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65  r 1 to enable pe
9b00: 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20  rsistent.** WAL 
9b10: 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e  mode.  If the in
9b20: 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65  teger is -1, the
9b30: 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74  n it is overwrit
9b40: 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72  ten with the cur
9b50: 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73  rent.** WAL pers
9b60: 69 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e  istence setting.
9b70: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9b80: 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53  ITE_FCNTL_POWERS
9b90: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a  AFE_OVERWRITE]].
9ba0: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
9bb0: 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f  FCNTL_POWERSAFE_
9bc0: 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64  OVERWRITE] opcod
9bd0: 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74  e is used to set
9be0: 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a   or query the.**
9bf0: 20 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77   persistent "pow
9c00: 65 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65  ersafe-overwrite
9c10: 22 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74  " or "PSOW" sett
9c20: 69 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73  ing.  The PSOW s
9c30: 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d  etting.** determ
9c40: 69 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45  ines the [SQLITE
9c50: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45  _IOCAP_POWERSAFE
9c60: 5f 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 20  _OVERWRITE] bit 
9c70: 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63  of the.** xDevic
9c80: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
9c90: 20 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f   methods. The fo
9ca0: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
9cb0: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  o.** [sqlite3_fi
9cc0: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f  le_control()] fo
9cd0: 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68  r this opcode sh
9ce0: 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65  ould be a pointe
9cf0: 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e  r to an integer.
9d00: 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72  .** That integer
9d10: 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
9d20: 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64   zero-damage mod
9d30: 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65  e or 1 to enable
9d40: 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20   zero-damage.** 
9d50: 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e  mode.  If the in
9d60: 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65  teger is -1, the
9d70: 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74  n it is overwrit
9d80: 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72  ten with the cur
9d90: 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d  rent.** zero-dam
9da0: 61 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67  age mode setting
9db0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
9dc0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57  LITE_FCNTL_OVERW
9dd0: 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  RITE]].** ^The [
9de0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45  SQLITE_FCNTL_OVE
9df0: 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69  RWRITE] opcode i
9e00: 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c  s invoked by SQL
9e10: 69 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e  ite after openin
9e20: 67 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61  g.** a write tra
9e30: 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69  nsaction to indi
9e40: 63 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73  cate that, unles
9e50: 73 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62  s it is rolled b
9e60: 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20  ack for some.** 
9e70: 72 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69  reason, the enti
9e80: 72 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  re database file
9e90: 20 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69   will be overwri
9ea0: 74 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 72  tten by the curr
9eb0: 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74  ent .** transact
9ec0: 69 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65  ion. This is use
9ed0: 64 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72  d by VACUUM oper
9ee0: 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ations..**.** <l
9ef0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9f00: 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54  _VFSNAME]].** ^T
9f10: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
9f20: 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65  _VFSNAME] opcode
9f30: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
9f40: 6f 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73  obtain the names
9f50: 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65   of.** all [VFSe
9f60: 73 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 74  s] in the VFS st
9f70: 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20  ack.  The names 
9f80: 61 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73  are of all VFS s
9f90: 68 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20  hims and the.** 
9fa0: 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76  final bottom-lev
9fb0: 65 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 74  el VFS are writt
9fc0: 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  en into memory o
9fd0: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a  btained from .**
9fe0: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
9ff0: 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75  ()] and the resu
a000: 6c 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20  lt is stored in 
a010: 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62  the char* variab
a020: 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66  le.** that the f
a030: 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
a040: 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  of [sqlite3_file
a050: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e  _control()] poin
a060: 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61  ts to..** The ca
a070: 6c 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69  ller is responsi
a080: 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20  ble for freeing 
a090: 74 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20  the memory when 
a0a0: 64 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a  done.  As with.*
a0b0: 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72  * all file-contr
a0c0: 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72  ol actions, ther
a0d0: 65 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65  e is no guarante
a0e0: 65 20 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c  e that this will
a0f0: 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20   actually.** do 
a100: 61 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65  anything.  Calle
a110: 72 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61  rs should initia
a120: 6c 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76  lize the char* v
a130: 61 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c  ariable to a NUL
a140: 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20  L.** pointer in 
a150: 63 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63  case this file-c
a160: 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d  ontrol is not im
a170: 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73  plemented.  This
a180: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a   file-control.**
a190: 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72   is intended for
a1a0: 20 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20   diagnostic use 
a1b0: 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  only..**.** <li>
a1c0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  [[SQLITE_FCNTL_P
a1d0: 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e  RAGMA]].** ^When
a1e0: 65 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20  ever a [PRAGMA] 
a1f0: 73 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72  statement is par
a200: 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f  sed, an [SQLITE_
a210: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a  FCNTL_PRAGMA] .*
a220: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  * file control i
a230: 73 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70  s sent to the op
a240: 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  en [sqlite3_file
a250: 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70  ] object corresp
a260: 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65  onding.** to the
a270: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74   database file t
a280: 6f 20 77 68 69 63 68 20 74 68 65 20 70 72 61 67  o which the prag
a290: 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66  ma statement ref
a2a0: 65 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65  ers. ^The argume
a2b0: 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51  nt.** to the [SQ
a2c0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
a2d0: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
a2e0: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a  is an array of.*
a2f0: 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74  * pointers to st
a300: 72 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69  rings (char**) i
a310: 6e 20 77 68 69 63 68 20 74 68 65 20 73 65 63 6f  n which the seco
a320: 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68  nd element of th
a330: 65 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68  e array.** is th
a340: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72  e name of the pr
a350: 61 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69  agma and the thi
a360: 72 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68  rd element is th
a370: 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  e argument to th
a380: 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e  e.** pragma or N
a390: 55 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d  ULL if the pragm
a3a0: 61 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e  a has no argumen
a3b0: 74 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72  t.  ^The handler
a3c0: 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49   for an.** [SQLI
a3d0: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
a3e0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61   file control ca
a3f0: 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b  n optionally mak
a400: 65 20 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d  e the first elem
a410: 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68  ent.** of the ch
a420: 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f  ar** argument po
a430: 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20  int to a string 
a440: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
a450: 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
a460: 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69  ].** or the equi
a470: 76 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20  valent and that 
a480: 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f  string will beco
a490: 6d 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  me the result of
a4a0: 20 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a   the pragma or.*
a4b0: 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  * the error mess
a4c0: 61 67 65 20 69 66 20 74 68 65 20 70 72 61 67 6d  age if the pragm
a4d0: 61 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65  a fails. ^If the
a4e0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  .** [SQLITE_FCNT
a4f0: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63  L_PRAGMA] file c
a500: 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b  ontrol returns [
a510: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d  SQLITE_NOTFOUND]
a520: 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a  , then normal .*
a530: 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65  * [PRAGMA] proce
a540: 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e  ssing continues.
a550: 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54    ^If the [SQLIT
a560: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a  E_FCNTL_PRAGMA].
a570: 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  ** file control 
a580: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
a590: 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61  OK], then the pa
a5a0: 72 73 65 72 20 61 73 73 75 6d 65 73 20 74 68 61  rser assumes tha
a5b0: 74 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73  t the.** VFS has
a5c0: 20 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41   handled the PRA
a5d0: 47 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74  GMA itself and t
a5e0: 68 65 20 70 61 72 73 65 72 20 67 65 6e 65 72 61  he parser genera
a5f0: 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70  tes a no-op.** p
a600: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
a610: 74 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  t.  ^If the [SQL
a620: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
a630: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  ] file control r
a640: 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65  eturns.** any re
a650: 73 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20  sult code other 
a660: 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  than [SQLITE_OK]
a670: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46   or [SQLITE_NOTF
a680: 4f 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e  OUND], that mean
a690: 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46  s.** that the VF
a6a0: 53 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e  S encountered an
a6b0: 20 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e   error while han
a6c0: 64 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d  dling the [PRAGM
a6d0: 41 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f  A] and the.** co
a6e0: 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65  mpilation of the
a6f0: 20 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69   PRAGMA fails wi
a700: 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54  th an error.  ^T
a710: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
a720: 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65  _PRAGMA].** file
a730: 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20   control occurs 
a740: 61 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  at the beginning
a750: 20 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74 65   of pragma state
a760: 6d 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e  ment analysis an
a770: 64 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62  d so.** it is ab
a780: 6c 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62  le to override b
a790: 75 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d  uilt-in [PRAGMA]
a7a0: 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
a7b0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
a7c0: 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45  FCNTL_BUSYHANDLE
a7d0: 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  R]].** ^The [SQL
a7e0: 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41  ITE_FCNTL_BUSYHA
a7f0: 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63  NDLER].** file-c
a800: 6f 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e  ontrol may be in
a810: 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20  voked by SQLite 
a820: 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  on the database 
a830: 66 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73  file handle.** s
a840: 68 6f 72 74 6c 79 20 61 66 74 65 72 20 69 74 20  hortly after it 
a850: 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64  is opened in ord
a860: 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 61 20  er to provide a 
a870: 63 75 73 74 6f 6d 20 56 46 53 20 77 69 74 68 20  custom VFS with 
a880: 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65  access.** to the
a890: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73   connections bus
a8a0: 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y-handler callba
a8b0: 63 6b 2e 20 54 68 65 20 61 72 67 75 6d 65 6e 74  ck. The argument
a8c0: 20 69 73 20 6f 66 20 74 79 70 65 20 28 76 6f 69   is of type (voi
a8d0: 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72  d **).** - an ar
a8e0: 72 61 79 20 6f 66 20 74 77 6f 20 28 76 6f 69 64  ray of two (void
a8f0: 20 2a 29 20 76 61 6c 75 65 73 2e 20 54 68 65 20   *) values. The 
a900: 66 69 72 73 74 20 28 76 6f 69 64 20 2a 29 20 61  first (void *) a
a910: 63 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a  ctually points.*
a920: 2a 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20  * to a function 
a930: 6f 66 20 74 79 70 65 20 28 69 6e 74 20 28 2a 29  of type (int (*)
a940: 28 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72  (void *)). In or
a950: 64 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68  der to invoke th
a960: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a  e connections.**
a970: 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74   busy-handler, t
a980: 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  his function sho
a990: 75 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  uld be invoked w
a9a0: 69 74 68 20 74 68 65 20 73 65 63 6f 6e 64 20 28  ith the second (
a9b0: 76 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68  void *) in.** th
a9c0: 65 20 61 72 72 61 79 20 61 73 20 74 68 65 20 6f  e array as the o
a9d0: 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 49 66  nly argument. If
a9e0: 20 69 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d   it returns non-
a9f0: 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f  zero, then the o
aa00: 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75  peration.** shou
aa10: 6c 64 20 62 65 20 72 65 74 72 69 65 64 2e 20 49  ld be retried. I
aa20: 66 20 69 74 20 72 65 74 75 72 6e 73 20 7a 65 72  f it returns zer
aa30: 6f 2c 20 74 68 65 20 63 75 73 74 6f 6d 20 56 46  o, the custom VF
aa40: 53 20 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e  S should abandon
aa50: 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20   the.** current 
aa60: 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  operation..**.**
aa70: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
aa80: 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45  NTL_TEMPFILENAME
aa90: 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69  ]].** ^Applicati
aaa0: 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68  on can invoke th
aab0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
aac0: 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69  TEMPFILENAME] fi
aad0: 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f  le-control.** to
aae0: 20 68 61 76 65 20 53 51 4c 69 74 65 20 67 65 6e   have SQLite gen
aaf0: 65 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f  erate a.** tempo
ab00: 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 20 75 73  rary filename us
ab10: 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67  ing the same alg
ab20: 6f 72 69 74 68 6d 20 74 68 61 74 20 69 73 20 66  orithm that is f
ab30: 6f 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65 72  ollowed to gener
ab40: 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79  ate.** temporary
ab50: 20 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54   filenames for T
ab60: 45 4d 50 20 74 61 62 6c 65 73 20 61 6e 64 20 6f  EMP tables and o
ab70: 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 20 75 73  ther internal us
ab80: 65 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67 75  es.  The.** argu
ab90: 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 61  ment should be a
aba0: 20 63 68 61 72 2a 2a 20 77 68 69 63 68 20 77 69   char** which wi
abb0: 6c 6c 20 62 65 20 66 69 6c 6c 65 64 20 77 69 74  ll be filled wit
abc0: 68 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a  h the filename.*
abd0: 2a 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d  * written into m
abe0: 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
abf0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
ac00: 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 63 61 6c  loc()].  The cal
ac10: 6c 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e  ler should.** in
ac20: 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72  voke [sqlite3_fr
ac30: 65 65 28 29 5d 20 6f 6e 20 74 68 65 20 72 65 73  ee()] on the res
ac40: 75 6c 74 20 74 6f 20 61 76 6f 69 64 20 61 20 6d  ult to avoid a m
ac50: 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a  emory leak..**.*
ac60: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
ac70: 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d  CNTL_MMAP_SIZE]]
ac80: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
ac90: 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d  FCNTL_MMAP_SIZE]
aca0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
acb0: 20 75 73 65 64 20 74 6f 20 71 75 65 72 79 20 6f   used to query o
acc0: 72 20 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78  r set the.** max
acd0: 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62  imum number of b
ace0: 79 74 65 73 20 74 68 61 74 20 77 69 6c 6c 20 62  ytes that will b
acf0: 65 20 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72  e used for memor
ad00: 79 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a  y-mapped I/O..**
ad10: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
ad20: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
ad30: 76 61 6c 75 65 20 6f 66 20 74 79 70 65 20 73 71  value of type sq
ad40: 6c 69 74 65 33 5f 69 6e 74 36 34 20 74 68 61 74  lite3_int64 that
ad50: 0a 2a 2a 20 69 73 20 61 6e 20 61 64 76 69 73 6f  .** is an adviso
ad60: 72 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  ry maximum numbe
ad70: 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
ad80: 65 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79  e file to memory
ad90: 20 6d 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f   map.  The.** po
ada0: 69 6e 74 65 72 20 69 73 20 6f 76 65 72 77 72 69  inter is overwri
adb0: 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 6f 6c  tten with the ol
adc0: 64 20 76 61 6c 75 65 2e 20 20 54 68 65 20 6c 69  d value.  The li
add0: 6d 69 74 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  mit is not chang
ade0: 65 64 20 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c  ed if.** the val
adf0: 75 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f  ue originally po
ae00: 69 6e 74 65 64 20 74 6f 20 69 73 20 6e 65 67 61  inted to is nega
ae10: 74 69 76 65 2c 20 61 6e 64 20 73 6f 20 74 68 65  tive, and so the
ae20: 20 63 75 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a   current limit .
ae30: 2a 2a 20 63 61 6e 20 62 65 20 71 75 65 72 69 65  ** can be querie
ae40: 64 20 62 79 20 70 61 73 73 69 6e 67 20 69 6e 20  d by passing in 
ae50: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e  a pointer to a n
ae60: 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2e 20  egative number. 
ae70: 20 54 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f   This.** file-co
ae80: 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 69 6e  ntrol is used in
ae90: 74 65 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c  ternally to impl
aea0: 65 6d 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d  ement [PRAGMA mm
aeb0: 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20  ap_size]..**.** 
aec0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
aed0: 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68  TL_TRACE]].** Th
aee0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
aef0: 54 52 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74  TRACE] file cont
af00: 72 6f 6c 20 70 72 6f 76 69 64 65 73 20 61 64 76  rol provides adv
af10: 69 73 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f  isory informatio
af20: 6e 0a 2a 2a 20 74 6f 20 74 68 65 20 56 46 53 20  n.** to the VFS 
af30: 61 62 6f 75 74 20 77 68 61 74 20 74 68 65 20 68  about what the h
af40: 69 67 68 65 72 20 6c 61 79 65 72 73 20 6f 66 20  igher layers of 
af50: 74 68 65 20 53 51 4c 69 74 65 20 73 74 61 63 6b  the SQLite stack
af60: 20 61 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54   are doing..** T
af70: 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  his file control
af80: 20 69 73 20 75 73 65 64 20 62 79 20 73 6f 6d 65   is used by some
af90: 20 56 46 53 20 61 63 74 69 76 69 74 79 20 74 72   VFS activity tr
afa0: 61 63 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a  acing [shims]..*
afb0: 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69  * The argument i
afc0: 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  s a zero-termina
afd0: 74 65 64 20 73 74 72 69 6e 67 2e 20 20 48 69 67  ted string.  Hig
afe0: 68 65 72 20 6c 61 79 65 72 73 20 69 6e 20 74 68  her layers in th
aff0: 65 0a 2a 2a 20 53 51 4c 69 74 65 20 73 74 61 63  e.** SQLite stac
b000: 6b 20 6d 61 79 20 67 65 6e 65 72 61 74 65 20 69  k may generate i
b010: 6e 73 74 61 6e 63 65 73 20 6f 66 20 74 68 69 73  nstances of this
b020: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66   file control if
b030: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
b040: 55 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d  USE_FCNTL_TRACE]
b050: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
b060: 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e  tion is enabled.
b070: 0a 2a 2a 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a  .**.** </ul>.*/.
b080: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
b090: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20  CNTL_LOCKSTATE  
b0a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23               1.#
b0b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45  define SQLITE_GE
b0c0: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20  T_LOCKPROXYFILE 
b0d0: 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 64              2.#d
b0e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54  efine SQLITE_SET
b0f0: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20  _LOCKPROXYFILE  
b100: 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65             3.#de
b110: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54  fine SQLITE_LAST
b120: 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20  _ERRNO          
b130: 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66            4.#def
b140: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
b150: 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20  _SIZE_HINT      
b160: 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69           5.#defi
b170: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
b180: 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20  CHUNK_SIZE      
b190: 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e          6.#defin
b1a0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46  e SQLITE_FCNTL_F
b1b0: 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20  ILE_POINTER     
b1c0: 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65         7.#define
b1d0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59   SQLITE_FCNTL_SY
b1e0: 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 20  NC_OMITTED      
b1f0: 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20        8.#define 
b200: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
b210: 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20 20 20  32_AV_RETRY     
b220: 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53       9.#define S
b230: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
b240: 49 53 54 5f 57 41 4c 20 20 20 20 20 20 20 20 20  IST_WAL         
b250: 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51     10.#define SQ
b260: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57  LITE_FCNTL_OVERW
b270: 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20  RITE            
b280: 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c    11.#define SQL
b290: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d  ITE_FCNTL_VFSNAM
b2a0: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
b2b0: 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   12.#define SQLI
b2c0: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
b2d0: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20  FE_OVERWRITE    
b2e0: 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  13.#define SQLIT
b2f0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20  E_FCNTL_PRAGMA  
b300: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
b310: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
b320: 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c  _FCNTL_BUSYHANDL
b330: 45 52 20 20 20 20 20 20 20 20 20 20 20 20 31 35  ER            15
b340: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b350: 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41  FCNTL_TEMPFILENA
b360: 4d 45 20 20 20 20 20 20 20 20 20 20 20 31 36 0a  ME           16.
b370: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
b380: 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 20  CNTL_MMAP_SIZE  
b390: 20 20 20 20 20 20 20 20 20 20 20 20 31 38 0a 23              18.#
b3a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
b3b0: 4e 54 4c 5f 54 52 41 43 45 20 20 20 20 20 20 20  NTL_TRACE       
b3c0: 20 20 20 20 20 20 20 20 20 20 20 31 39 0a 0a 2f             19../
b3d0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
b3e0: 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a  utex Handle.**.*
b3f0: 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75  * The mutex modu
b400: 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65  le within SQLite
b410: 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65   defines [sqlite
b420: 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61  3_mutex] to be a
b430: 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79  n.** abstract ty
b440: 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f  pe for a mutex o
b450: 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69  bject.  The SQLi
b460: 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f  te core never lo
b470: 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e  oks.** at the in
b480: 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74  ternal represent
b490: 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c  ation of an [sql
b4a0: 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74  ite3_mutex].  It
b4b0: 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77   only.** deals w
b4c0: 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  ith pointers to 
b4d0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
b4e0: 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  ex] object..**.*
b4f0: 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 63 72  * Mutexes are cr
b500: 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  eated using [sql
b510: 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63  ite3_mutex_alloc
b520: 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ()]..*/.typedef 
b530: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
b540: 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74  utex sqlite3_mut
b550: 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ex;../*.** CAPI3
b560: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
b570: 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41  e Object.**.** A
b580: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
b590: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  e sqlite3_vfs ob
b5a0: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
b5b0: 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65   interface betwe
b5c0: 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65  en.** the SQLite
b5d0: 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e   core and the un
b5e0: 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69  derlying operati
b5f0: 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20  ng system.  The 
b600: 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20  "vfs".** in the 
b610: 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65  name of the obje
b620: 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76  ct stands for "v
b630: 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74  irtual file syst
b640: 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65  em".  See.** the
b650: 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f 63 75   [VFS | VFS docu
b660: 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66  mentation] for f
b670: 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61 74 69  urther informati
b680: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61  on..**.** The va
b690: 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65 72 73  lue of the iVers
b6a0: 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69  ion field is ini
b6b0: 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79  tially 1 but may
b6c0: 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a   be larger in.**
b6d0: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
b6e0: 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64   of SQLite.  Add
b6f0: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d  itional fields m
b700: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74  ay be appended t
b710: 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74  o this.** object
b720: 20 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69   when the iVersi
b730: 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72  on value is incr
b740: 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61  eased.  Note tha
b750: 74 20 74 68 65 20 73 74 72 75 63 74 75 72 65 0a  t the structure.
b760: 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ** of the sqlite
b770: 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61  3_vfs object cha
b780: 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e  nges in the tran
b790: 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a  saction between.
b7a0: 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  ** SQLite versio
b7b0: 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e  n 3.5.9 and 3.6.
b7c0: 30 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56  0 and yet the iV
b7d0: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73  ersion field was
b7e0: 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64   not.** modified
b7f0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73  ..**.** The szOs
b800: 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68  File field is th
b810: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75  e size of the su
b820: 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65  bclassed [sqlite
b830: 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63  3_file].** struc
b840: 74 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69  ture used by thi
b850: 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61  s VFS.  mxPathna
b860: 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75  me is the maximu
b870: 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61  m length of.** a
b880: 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69   pathname in thi
b890: 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67  s VFS..**.** Reg
b8a0: 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f  istered sqlite3_
b8b0: 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20  vfs objects are 
b8c0: 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64  kept on a linked
b8d0: 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a   list formed by.
b8e0: 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69  ** the pNext poi
b8f0: 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69  nter.  The [sqli
b900: 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72  te3_vfs_register
b910: 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
b920: 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74  te3_vfs_unregist
b930: 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  er()] interfaces
b940: 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73   manage this lis
b950: 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64  t.** in a thread
b960: 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20  -safe way.  The 
b970: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e  [sqlite3_vfs_fin
b980: 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a  d()] interface.*
b990: 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c  * searches the l
b9a0: 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68  ist.  Neither th
b9b0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f  e application co
b9c0: 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a  de nor the VFS.*
b9d0: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
b9e0: 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20   should use the 
b9f0: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a  pNext pointer..*
ba00: 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66  *.** The pNext f
ba10: 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79  ield is the only
ba20: 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71   field in the sq
ba30: 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72  lite3_vfs.** str
ba40: 75 63 74 75 72 65 20 74 68 61 74 20 53 51 4c 69  ucture that SQLi
ba50: 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64  te will ever mod
ba60: 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c  ify.  SQLite wil
ba70: 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a  l only access.**
ba80: 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20   or modify this 
ba90: 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64  field while hold
baa0: 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 72  ing a particular
bab0: 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a   static mutex..*
bac0: 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
bad0: 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d  n should never m
bae0: 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77  odify anything w
baf0: 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ithin the sqlite
bb00: 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20  3_vfs.** object 
bb10: 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20  once the object 
bb20: 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 65  has been registe
bb30: 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a  red..**.** The z
bb40: 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73  Name field holds
bb50: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
bb60: 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68   VFS module.  Th
bb70: 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62  e name must.** b
bb80: 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20  e unique across 
bb90: 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e  all VFS modules.
bba0: 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33  .**.** [[sqlite3
bbb0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20  _vfs.xOpen]].** 
bbc0: 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65  ^SQLite guarante
bbd0: 65 73 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c  es that the zFil
bbe0: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  ename parameter 
bbf0: 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65  to xOpen.** is e
bc00: 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69  ither a NULL poi
bc10: 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f  nter or string o
bc20: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
bc30: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20  xFullPathname() 
bc40: 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c  with an optional
bc50: 20 73 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a   suffix added..*
bc60: 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78 20 69  * ^If a suffix i
bc70: 73 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a  s added to the z
bc80: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
bc90: 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63  er, it will.** c
bca0: 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67  onsist of a sing
bcb0: 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74 65 72  le "-" character
bcc0: 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20   followed by no 
bcd0: 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20  more than.** 11 
bce0: 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64  alphanumeric and
bcf0: 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63 74 65  /or "-" characte
bd00: 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66  rs..** ^SQLite f
bd10: 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65  urther guarantee
bd20: 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74  s that.** the st
bd30: 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c  ring will be val
bd40: 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64  id and unchanged
bd50: 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20   until xClose() 
bd60: 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65  is.** called. Be
bd70: 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65  cause of the pre
bd80: 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a  vious sentence,.
bd90: 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
bda0: 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79  file] can safely
bdb0: 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72   store a pointer
bdc0: 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e   to the.** filen
bdd0: 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20  ame if it needs 
bde0: 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20  to remember the 
bdf0: 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d  filename for som
be00: 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20  e reason..** If 
be10: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
be20: 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e  rameter to xOpen
be30: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
be40: 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a  er then xOpen.**
be50: 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73   must invent its
be60: 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e   own temporary n
be70: 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65  ame for the file
be80: 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65  .  ^Whenever the
be90: 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70   .** xFilename p
bea0: 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c  arameter is NULL
beb0: 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65   it will also be
bec0: 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74   the case that t
bed0: 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61  he.** flags para
bee0: 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75  meter will inclu
bef0: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  de [SQLITE_OPEN_
bf00: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a  DELETEONCLOSE]..
bf10: 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20  **.** The flags 
bf20: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
bf30: 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c  n() includes all
bf40: 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20   bits set in.** 
bf50: 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  the flags argume
bf60: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  nt to [sqlite3_o
bf70: 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69  pen_v2()].  Or i
bf80: 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  f [sqlite3_open(
bf90: 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  )].** or [sqlite
bfa0: 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75  3_open16()] is u
bfb0: 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20  sed, then flags 
bfc0: 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73  includes at leas
bfd0: 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  t.** [SQLITE_OPE
bfe0: 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b  N_READWRITE] | [
bff0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
c000: 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65  TE]. .** If xOpe
c010: 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65  n() opens a file
c020: 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20   read-only then 
c030: 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61  it sets *pOutFla
c040: 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65  gs to.** include
c050: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
c060: 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20  ADONLY].  Other 
c070: 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61  bits in *pOutFla
c080: 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a  gs may be set..*
c090: 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69  *.** ^(SQLite wi
c0a0: 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20  ll also add one 
c0b0: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
c0c0: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f   flags to the xO
c0d0: 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64  pen().** call, d
c0e0: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
c0f0: 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65  object being ope
c100: 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ned:.**.** <ul>.
c110: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
c120: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a  _OPEN_MAIN_DB].*
c130: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
c140: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
c150: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
c160: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42  ITE_OPEN_TEMP_DB
c170: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
c180: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
c190: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
c1a0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e  SQLITE_OPEN_TRAN
c1b0: 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  SIENT_DB].** <li
c1c0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
c1d0: 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  SUBJOURNAL].** <
c1e0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
c1f0: 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c  N_MASTER_JOURNAL
c200: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
c210: 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20  TE_OPEN_WAL].** 
c220: 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  </ul>)^.**.** Th
c230: 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65  e file I/O imple
c240: 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73  mentation can us
c250: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70  e the object typ
c260: 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68  e flags to.** ch
c270: 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20  ange the way it 
c280: 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73  deals with files
c290: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  .  For example, 
c2a0: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  an application.*
c2b0: 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  * that does not 
c2c0: 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68  care about crash
c2d0: 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c   recovery or rol
c2e0: 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65  lback might make
c2f0: 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20  .** the open of 
c300: 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61  a journal file a
c310: 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20   no-op.  Writes 
c320: 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20  to this journal 
c330: 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65  would.** also be
c340: 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79   no-ops, and any
c350: 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64   attempt to read
c360: 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75   the journal wou
c370: 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c  ld return.** SQL
c380: 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74  ITE_IOERR.  Or t
c390: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
c3a0: 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a  n might recogniz
c3b0: 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73  e that a databas
c3c0: 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62  e.** file will b
c3d0: 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69  e doing page-ali
c3e0: 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64  gned sector read
c3f0: 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20  s and writes in 
c400: 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65  a random.** orde
c410: 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73  r and set up its
c420: 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61   I/O subsystem a
c430: 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a  ccordingly..**.*
c440: 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61  * SQLite might a
c450: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
c460: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
c470: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20  gs to the xOpen 
c480: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
c490: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
c4a0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
c4b0: 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  CLOSE].** <li> [
c4c0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
c4d0: 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  USIVE].** </ul>.
c4e0: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
c4f0: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
c500: 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73  LOSE] flag means
c510: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
c520: 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77   be.** deleted w
c530: 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64  hen it is closed
c540: 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  .  ^The [SQLITE_
c550: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
c560: 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73  SE].** will be s
c570: 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61  et for TEMP data
c580: 62 61 73 65 73 20 61 6e 64 20 74 68 65 69 72 20  bases and their 
c590: 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69  journals, transi
c5a0: 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73  ent.** databases
c5b0: 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c  , and subjournal
c5c0: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53  s..**.** ^The [S
c5d0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
c5e0: 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c  SIVE] flag is al
c5f0: 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e  ways used in con
c600: 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68  junction.** with
c610: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
c620: 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20  N_CREATE] flag, 
c630: 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 20 64  which are both d
c640: 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f  irectly.** analo
c650: 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58  gous to the O_EX
c660: 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66  CL and O_CREAT f
c670: 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49  lags of the POSI
c680: 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e  X open().** API.
c690: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45    The SQLITE_OPE
c6a0: 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67  N_EXCLUSIVE flag
c6b0: 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 77 69  , when paired wi
c6c0: 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54  th the .** SQLIT
c6d0: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69  E_OPEN_CREATE, i
c6e0: 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61  s used to indica
c6f0: 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f  te that file sho
c700: 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65  uld always.** be
c710: 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68   created, and th
c720: 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f  at it is an erro
c730: 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 79 20  r if it already 
c740: 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73  exists..** It is
c750: 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64   <i>not</i> used
c760: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65   to indicate the
c770: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20   file should be 
c780: 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65  opened .** for e
c790: 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e  xclusive access.
c7a0: 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74  .**.** ^At least
c7b0: 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20   szOsFile bytes 
c7c0: 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c  of memory are al
c7d0: 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74  located by SQLit
c7e0: 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65  e.** to hold the
c7f0: 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d    [sqlite3_file]
c800: 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73 65   structure passe
c810: 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a  d as the third.*
c820: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  * argument to xO
c830: 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20  pen.  The xOpen 
c840: 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20  method does not 
c850: 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63  have to.** alloc
c860: 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72  ate the structur
c870: 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73  e; it should jus
c880: 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e  t fill it in.  N
c890: 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ote that.** the 
c8a0: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73  xOpen method mus
c8b0: 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65  t set the sqlite
c8c0: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
c8d0: 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76  to either.** a v
c8e0: 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f  alid [sqlite3_io
c8f0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
c900: 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f   or to NULL.  xO
c910: 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74  pen must do.** t
c920: 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 65 20  his even if the 
c930: 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c  open fails.  SQL
c940: 69 74 65 20 65 78 70 65 63 74 73 20 74 68 61 74  ite expects that
c950: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
c960: 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c  e.pMethods.** el
c970: 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61  ement will be va
c980: 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20  lid after xOpen 
c990: 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65  returns regardle
c9a0: 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 73  ss of the succes
c9b0: 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20  s.** or failure 
c9c0: 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c  of the xOpen cal
c9d0: 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74  l..**.** [[sqlit
c9e0: 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73 5d 5d  e3_vfs.xAccess]]
c9f0: 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 61  .** ^The flags a
ca00: 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65  rgument to xAcce
ca10: 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c  ss() may be [SQL
ca20: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
ca30: 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f  S].** to test fo
ca40: 72 20 74 68 65 20 65 78 69 73 74 65 6e 63 65 20  r the existence 
ca50: 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53  of a file, or [S
ca60: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
ca70: 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65  DWRITE] to.** te
ca80: 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c  st whether a fil
ca90: 65 20 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e  e is readable an
caa0: 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b  d writable, or [
cab0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
cac0: 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77  AD].** to test w
cad0: 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73  hether a file is
cae0: 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 61 62   at least readab
caf0: 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63  le.   The file c
cb00: 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63  an be a.** direc
cb10: 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  tory..**.** ^SQL
cb20: 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ite will always 
cb30: 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73  allocate at leas
cb40: 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62  t mxPathname+1 b
cb50: 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20  ytes for the.** 
cb60: 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 78 46  output buffer xF
cb70: 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 68  ullPathname.  Th
cb80: 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20  e exact size of 
cb90: 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65  the output buffe
cba0: 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73  r.** is also pas
cbb0: 73 65 64 20 61 73 20 61 20 70 61 72 61 6d 65 74  sed as a paramet
cbc0: 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68  er to both  meth
cbd0: 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75 74 70  ods. If the outp
cbe0: 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20  ut buffer.** is 
cbf0: 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68  not large enough
cc00: 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  , [SQLITE_CANTOP
cc10: 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 65  EN] should be re
cc20: 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 68  turned. Since th
cc30: 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64  is is.** handled
cc40: 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f   as a fatal erro
cc50: 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76 66 73  r by SQLite, vfs
cc60: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
cc70: 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72   should endeavor
cc80: 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 74  .** to prevent t
cc90: 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 20 6d  his by setting m
cca0: 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73  xPathname to a s
ccb0: 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67  ufficiently larg
ccc0: 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54  e value..**.** T
ccd0: 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29  he xRandomness()
cce0: 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43 75 72  , xSleep(), xCur
ccf0: 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64 20  rentTime(), and 
cd00: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
cd10: 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  4().** interface
cd20: 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74  s are not strict
cd30: 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 68 65  ly a part of the
cd40: 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74   filesystem, but
cd50: 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63   they are.** inc
cd60: 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 46 53  luded in the VFS
cd70: 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 63   structure for c
cd80: 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20  ompleteness..** 
cd90: 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28  The xRandomness(
cda0: 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d  ) function attem
cdb0: 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42  pts to return nB
cdc0: 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66  ytes bytes.** of
cdd0: 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61   good-quality ra
cde0: 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f  ndomness into zO
cdf0: 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20  ut.  The return 
ce00: 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20  value is.** the 
ce10: 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66  actual number of
ce20: 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d   bytes of random
ce30: 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a  ness obtained..*
ce40: 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d  * The xSleep() m
ce50: 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 68 65  ethod causes the
ce60: 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20   calling thread 
ce70: 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a  to sleep for at.
ce80: 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d  ** least the num
ce90: 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f  ber of microseco
cea0: 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54 68 65  nds given.  ^The
ceb0: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a   xCurrentTime().
cec0: 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  ** method return
ced0: 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e  s a Julian Day N
cee0: 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63 75  umber for the cu
cef0: 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74  rrent date and t
cf00: 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61  ime as.** a floa
cf10: 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
cf20: 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72 72 65  ..** ^The xCurre
cf30: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65  ntTimeInt64() me
cf40: 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20 61 73  thod returns, as
cf50: 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65   an integer, the
cf60: 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e   Julian.** Day N
cf70: 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69 65 64  umber multiplied
cf80: 20 62 79 20 38 36 34 30 30 30 30 30 20 28 74 68   by 86400000 (th
cf90: 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c  e number of mill
cfa0: 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20  iseconds in .** 
cfb0: 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29 2e 20  a 24-hour day). 
cfc0: 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c   .** ^SQLite wil
cfd0: 6c 20 75 73 65 20 74 68 65 20 78 43 75 72 72 65  l use the xCurre
cfe0: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65  ntTimeInt64() me
cff0: 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68 65 20  thod to get the 
d000: 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20  current.** date 
d010: 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68 61 74  and time if that
d020: 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61 69 6c   method is avail
d030: 61 62 6c 65 20 28 69 66 20 69 56 65 72 73 69 6f  able (if iVersio
d040: 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72  n is 2 or .** gr
d050: 65 61 74 65 72 20 61 6e 64 20 74 68 65 20 66 75  eater and the fu
d060: 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69  nction pointer i
d070: 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20  s not NULL) and 
d080: 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a  will fall back.*
d090: 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54 69 6d  * to xCurrentTim
d0a0: 65 28 29 20 69 66 20 78 43 75 72 72 65 6e 74 54  e() if xCurrentT
d0b0: 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20 75 6e  imeInt64() is un
d0c0: 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a  available..**.**
d0d0: 20 5e 54 68 65 20 78 53 65 74 53 79 73 74 65 6d   ^The xSetSystem
d0e0: 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79 73 74  Call(), xGetSyst
d0f0: 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e  emCall(), and xN
d100: 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 20  estSystemCall() 
d110: 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72  interfaces.** ar
d120: 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20 74 68  e not used by th
d130: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 20  e SQLite core.  
d140: 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69  These optional i
d150: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70 72  nterfaces are pr
d160: 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d  ovided.** by som
d170: 65 20 56 46 53 65 73 20 74 6f 20 66 61 63 69 6c  e VFSes to facil
d180: 69 74 61 74 65 20 74 65 73 74 69 6e 67 20 6f 66  itate testing of
d190: 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e 20 42   the VFS code. B
d1a0: 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a  y overriding .**
d1b0: 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 77 69   system calls wi
d1c0: 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64  th functions und
d1d0: 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20  er its control, 
d1e0: 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d 20 63  a test program c
d1f0: 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66  an.** simulate f
d200: 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f 72 20  aults and error 
d210: 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61 74 20  conditions that 
d220: 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73 65 20  would otherwise 
d230: 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20  be difficult.** 
d240: 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f  or impossible to
d250: 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20 73 65   induce.  The se
d260: 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61 6c 6c  t of system call
d270: 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76  s that can be ov
d280: 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69  erridden.** vari
d290: 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20  es from one VFS 
d2a0: 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20  to another, and 
d2b0: 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e  from one version
d2c0: 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56 46 53   of the same VFS
d2d0: 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e   to the.** next.
d2e0: 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74    Applications t
d2f0: 68 61 74 20 75 73 65 20 74 68 65 73 65 20 69 6e  hat use these in
d300: 74 65 72 66 61 63 65 73 20 6d 75 73 74 20 62 65  terfaces must be
d310: 20 70 72 65 70 61 72 65 64 20 66 6f 72 20 61 6e   prepared for an
d320: 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74  y.** or all of t
d330: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
d340: 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f  to be NULL or fo
d350: 72 20 74 68 65 69 72 20 62 65 68 61 76 69 6f 72  r their behavior
d360: 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72   to change.** fr
d370: 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74  om one release t
d380: 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41 70 70  o the next.  App
d390: 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e  lications must n
d3a0: 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63  ot attempt to ac
d3b0: 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74  cess.** any of t
d3c0: 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69 66 20  hese methods if 
d3d0: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f 66 20  the iVersion of 
d3e0: 74 68 65 20 56 46 53 20 69 73 20 6c 65 73 73 20  the VFS is less 
d3f0: 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64  than 3..*/.typed
d400: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
d410: 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66  3_vfs sqlite3_vf
d420: 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20  s;.typedef void 
d430: 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c  (*sqlite3_syscal
d440: 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a 73 74  l_ptr)(void);.st
d450: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73  ruct sqlite3_vfs
d460: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
d470: 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  n;            /*
d480: 20 53 74 72 75 63 74 75 72 65 20 76 65 72 73 69   Structure versi
d490: 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 72 65  on number (curre
d4a0: 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74  ntly 3) */.  int
d4b0: 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20   szOsFile;      
d4c0: 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66        /* Size of
d4d0: 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69   subclassed sqli
d4e0: 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e  te3_file */.  in
d4f0: 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20  t mxPathname;   
d500: 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
d510: 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20  m file pathname 
d520: 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69  length */.  sqli
d530: 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20  te3_vfs *pNext; 
d540: 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67       /* Next reg
d550: 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20  istered VFS */. 
d560: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
d570: 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  me;       /* Nam
d580: 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 75 61  e of this virtua
d590: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f  l file system */
d5a0: 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74  .  void *pAppDat
d5b0: 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50  a;          /* P
d5c0: 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63  ointer to applic
d5d0: 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64  ation-specific d
d5e0: 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ata */.  int (*x
d5f0: 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66  Open)(sqlite3_vf
d600: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
d610: 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66  zName, sqlite3_f
d620: 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20  ile*,.          
d630: 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20       int flags, 
d640: 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b  int *pOutFlags);
d650: 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65  .  int (*xDelete
d660: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
d670: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
d680: 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b  e, int syncDir);
d690: 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73  .  int (*xAccess
d6a0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
d6b0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
d6c0: 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e  e, int flags, in
d6d0: 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69  t *pResOut);.  i
d6e0: 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61  nt (*xFullPathna
d6f0: 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  me)(sqlite3_vfs*
d700: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
d710: 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63  ame, int nOut, c
d720: 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f  har *zOut);.  vo
d730: 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73  id *(*xDlOpen)(s
d740: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
d750: 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61  st char *zFilena
d760: 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44  me);.  void (*xD
d770: 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f  lError)(sqlite3_
d780: 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  vfs*, int nByte,
d790: 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b   char *zErrMsg);
d7a0: 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53  .  void (*(*xDlS
d7b0: 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ym)(sqlite3_vfs*
d7c0: 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68  ,void*, const ch
d7d0: 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f  ar *zSymbol))(vo
d7e0: 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44  id);.  void (*xD
d7f0: 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  lClose)(sqlite3_
d800: 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20  vfs*, void*);.  
d810: 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73  int (*xRandomnes
d820: 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  s)(sqlite3_vfs*,
d830: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
d840: 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28   *zOut);.  int (
d850: 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33  *xSleep)(sqlite3
d860: 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f  _vfs*, int micro
d870: 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20  seconds);.  int 
d880: 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28  (*xCurrentTime)(
d890: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f  sqlite3_vfs*, do
d8a0: 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  uble*);.  int (*
d8b0: 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73  xGetLastError)(s
d8c0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
d8d0: 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a  , char *);.  /*.
d8e0: 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73    ** The methods
d8f0: 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65   above are in ve
d900: 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73  rsion 1 of the s
d910: 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74  qlite_vfs object
d920: 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e  .  ** definition
d930: 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20 66 6f  .  Those that fo
d940: 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64 20 69  llow are added i
d950: 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c  n version 2 or l
d960: 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20  ater.  */.  int 
d970: 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  (*xCurrentTimeIn
d980: 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73  t64)(sqlite3_vfs
d990: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
d9a0: 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  *);.  /*.  ** Th
d9b0: 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
d9c0: 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20  are in versions 
d9d0: 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73  1 and 2 of the s
d9e0: 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74  qlite_vfs object
d9f0: 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c  ..  ** Those bel
da00: 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72 73 69  ow are for versi
da10: 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74 65 72  on 3 and greater
da20: 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ..  */.  int (*x
da30: 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  SetSystemCall)(s
da40: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
da50: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
da60: 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f  sqlite3_syscall_
da70: 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f  ptr);.  sqlite3_
da80: 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47  syscall_ptr (*xG
da90: 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71  etSystemCall)(sq
daa0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
dab0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
dac0: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a    const char *(*
dad0: 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c 6c 29  xNextSystemCall)
dae0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
daf0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
db00: 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65  );.  /*.  ** The
db10: 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   methods above a
db20: 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31  re in versions 1
db30: 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20 74 68   through 3 of th
db40: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
db50: 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69  ect..  ** New fi
db60: 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65  elds may be appe
db70: 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65 20 76  nded in figure v
db80: 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56  ersions.  The iV
db90: 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75  ersion.  ** valu
dba0: 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74  e will increment
dbb0: 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 68   whenever this h
dbc0: 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b  appens. .  */.};
dbd0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
dbe0: 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20  : Flags for the 
dbf0: 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 68  xAccess VFS meth
dc00: 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  od.**.** These i
dc10: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
dc20: 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20   can be used as 
dc30: 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
dc40: 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41  ter to.** the xA
dc50: 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20  ccess method of 
dc60: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  an [sqlite3_vfs]
dc70: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64   object.  They d
dc80: 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74  etermine.** what
dc90: 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73   kind of permiss
dca0: 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 73  ions the xAccess
dcb0: 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69   method is looki
dcc0: 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20  ng for..** With 
dcd0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
dce0: 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 65 73  ISTS, the xAcces
dcf0: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70  s method.** simp
dd00: 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ly checks whethe
dd10: 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 74  r the file exist
dd20: 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  s..** With SQLIT
dd30: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
dd40: 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TE, the xAccess 
dd50: 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73  method.** checks
dd60: 20 77 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d   whether the nam
dd70: 65 64 20 64 69 72 65 63 74 6f 72 79 20 69 73 20  ed directory is 
dd80: 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e  both readable an
dd90: 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69  d writable.** (i
dda0: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
ddb0: 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61  f files can be a
ddc0: 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61  dded, removed, a
ddd0: 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69  nd renamed withi
dde0: 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f  n.** the directo
ddf0: 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ry)..** The SQLI
de00: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
de10: 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20  ITE constant is 
de20: 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f  currently used o
de30: 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74  nly by the.** [t
de40: 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
de50: 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f  ory pragma], tho
de60: 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63  ugh this could c
de70: 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72  hange in a futur
de80: 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20  e.** release of 
de90: 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20  SQLite..** With 
dea0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
deb0: 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  AD, the xAccess 
dec0: 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73  method.** checks
ded0: 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c   whether the fil
dee0: 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20  e is readable.  
def0: 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  The SQLITE_ACCES
df00: 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20  S_READ constant 
df10: 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20  is.** currently 
df20: 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69  unused, though i
df30: 74 20 6d 69 67 68 74 20 62 65 20 75 73 65 64 20  t might be used 
df40: 69 6e 20 61 20 66 75 74 75 72 65 20 72 65 6c 65  in a future rele
df50: 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65  ase of.** SQLite
df60: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
df70: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
df80: 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53  S    0.#define S
df90: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
dfa0: 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73  DWRITE 1   /* Us
dfb0: 65 64 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d  ed by PRAGMA tem
dfc0: 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
dfd0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
dfe0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20  ITE_ACCESS_READ 
dff0: 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73       2   /* Unus
e000: 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ed */../*.** CAP
e010: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72  I3REF: Flags for
e020: 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46   the xShmLock VF
e030: 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54  S method.**.** T
e040: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
e050: 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68  stants define th
e060: 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e  e various lockin
e070: 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20  g operations.** 
e080: 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78  allowed by the x
e090: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f  ShmLock method o
e0a0: 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  f [sqlite3_io_me
e0b0: 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20  thods].  The.** 
e0c0: 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68  following are th
e0d0: 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d  e only legal com
e0e0: 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61  binations of fla
e0f0: 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68  gs to the.** xSh
e100: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a  mLock method:.**
e110: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
e120: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43    SQLITE_SHM_LOC
e130: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53  K | SQLITE_SHM_S
e140: 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53  HARED.** <li>  S
e150: 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c  QLITE_SHM_LOCK |
e160: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c   SQLITE_SHM_EXCL
e170: 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53  USIVE.** <li>  S
e180: 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b  QLITE_SHM_UNLOCK
e190: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48   | SQLITE_SHM_SH
e1a0: 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  ARED.** <li>  SQ
e1b0: 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
e1c0: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  | SQLITE_SHM_EXC
e1d0: 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a  LUSIVE.** </ul>.
e1e0: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63  **.** When unloc
e1f0: 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53  king, the same S
e200: 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49  HARED or EXCLUSI
e210: 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20  VE flag must be 
e220: 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77  supplied as.** w
e230: 61 73 20 67 69 76 65 6e 20 6e 6f 20 74 68 65 20  as given no the 
e240: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f  corresponding lo
e250: 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ck.  .**.** The 
e260: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
e270: 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62  can transition b
e280: 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20  etween unlocked 
e290: 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a  and SHARED or.**
e2a0: 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65   between unlocke
e2b0: 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e  d and EXCLUSIVE.
e2c0: 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e    It cannot tran
e2d0: 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53  sition between S
e2e0: 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43  HARED.** and EXC
e2f0: 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69  LUSIVE..*/.#defi
e300: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e  ne SQLITE_SHM_UN
e310: 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65  LOCK       1.#de
e320: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
e330: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23  LOCK         2.#
e340: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
e350: 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 34  M_SHARED       4
e360: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
e370: 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20  SHM_EXCLUSIVE   
e380: 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   8../*.** CAPI3R
e390: 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d  EF: Maximum xShm
e3a0: 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a  Lock index.**.**
e3b0: 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65   The xShmLock me
e3c0: 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33  thod on [sqlite3
e3d0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79  _io_methods] may
e3e0: 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62   use values.** b
e3f0: 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69  etween 0 and thi
e400: 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73  s upper bound as
e410: 20 69 74 73 20 22 6f 66 66 73 65 74 22 20 61 72   its "offset" ar
e420: 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53  gument..** The S
e430: 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20  QLite core will 
e440: 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f  never attempt to
e450: 20 61 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65   acquire or rele
e460: 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75  ase a.** lock ou
e470: 74 73 69 64 65 20 6f 66 20 74 68 69 73 20 72 61  tside of this ra
e480: 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nge.*/.#define S
e490: 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20  QLITE_SHM_NLOCK 
e4a0: 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a         8.../*.**
e4b0: 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69   CAPI3REF: Initi
e4c0: 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65  alize The SQLite
e4d0: 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e   Library.**.** ^
e4e0: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
e4f0: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
e500: 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65   initializes the
e510: 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61  .** SQLite libra
e520: 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ry.  ^The sqlite
e530: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75  3_shutdown() rou
e540: 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61  tine.** dealloca
e550: 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65  tes any resource
e560: 73 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f  s that were allo
e570: 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  cated by sqlite3
e580: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a  _initialize()..*
e590: 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
e5a0: 20 61 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f   are designed to
e5b0: 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20   aid in process 
e5c0: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61  initialization a
e5d0: 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f  nd.** shutdown o
e5e0: 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73 74 65  n embedded syste
e5f0: 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e  ms.  Workstation
e600: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73   applications us
e610: 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f  ing.** SQLite no
e620: 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65  rmally do not ne
e630: 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74  ed to invoke eit
e640: 68 65 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75  her of these rou
e650: 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63  tines..**.** A c
e660: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  all to sqlite3_i
e670: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61  nitialize() is a
e680: 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61  n "effective" ca
e690: 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74  ll if it is.** t
e6a0: 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71  he first time sq
e6b0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
e6c0: 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75  () is invoked du
e6d0: 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d  ring the lifetim
e6e0: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63  e of.** the proc
e6f0: 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73  ess, or if it is
e700: 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   the first time 
e710: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
e720: 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  ze() is invoked.
e730: 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63  ** following a c
e740: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
e750: 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e  hutdown().  ^(On
e760: 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76 65 20  ly an effective 
e770: 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74  call.** of sqlit
e780: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
e790: 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c  does any initial
e7a0: 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74  ization.  All ot
e7b0: 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65  her calls.** are
e7c0: 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73   harmless no-ops
e7d0: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c  .)^.**.** A call
e7e0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
e7f0: 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66  down() is an "ef
e800: 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66  fective" call if
e810: 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74   it is the first
e820: 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  .** call to sqli
e830: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73  te3_shutdown() s
e840: 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20 73 71  ince the last sq
e850: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
e860: 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61  ().  ^(Only.** a
e870: 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c  n effective call
e880: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
e890: 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20  down() does any 
e8a0: 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  deinitialization
e8b0: 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76  ..** All other v
e8c0: 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71  alid calls to sq
e8d0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
e8e0: 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f   are harmless no
e8f0: 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  -ops.)^.**.** Th
e900: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
e910: 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65  lize() interface
e920: 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2c 20   is threadsafe, 
e930: 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74  but sqlite3_shut
e940: 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74  down().** is not
e950: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73  .  The sqlite3_s
e960: 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66  hutdown() interf
e970: 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65  ace must only be
e980: 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a   called from a.*
e990: 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e  * single thread.
e9a0: 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61    All open [data
e9b0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
e9c0: 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64  ] must be closed
e9d0: 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65   and all.** othe
e9e0: 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63  r SQLite resourc
e9f0: 65 73 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c  es must be deall
ea00: 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20  ocated prior to 
ea10: 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69  invoking.** sqli
ea20: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a  te3_shutdown()..
ea30: 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65  **.** Among othe
ea40: 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74  r things, ^sqlit
ea50: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
ea60: 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  will invoke.** s
ea70: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
ea80: 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73  .  Similarly, ^s
ea90: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
eaa0: 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  ).** will invoke
eab0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
eac0: 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )..**.** ^The sq
ead0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
eae0: 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
eaf0: 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  ns [SQLITE_OK] o
eb00: 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49  n success..** ^I
eb10: 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f  f for some reaso
eb20: 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  n, sqlite3_initi
eb30: 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c  alize() is unabl
eb40: 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a  e to initialize.
eb50: 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20 28  ** the library (
eb60: 70 65 72 68 61 70 73 20 69 74 20 69 73 20 75 6e  perhaps it is un
eb70: 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
eb80: 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72   a needed resour
eb90: 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20  ce such.** as a 
eba0: 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 72 6e  mutex) it return
ebb0: 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  s an [error code
ebc0: 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  ] other than [SQ
ebd0: 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  LITE_OK]..**.** 
ebe0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  ^The sqlite3_ini
ebf0: 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
ec00: 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65  e is called inte
ec10: 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f  rnally by many o
ec20: 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ther.** SQLite i
ec30: 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 68 61  nterfaces so tha
ec40: 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  t an application
ec50: 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f   usually does no
ec60: 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76  t need to.** inv
ec70: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  oke sqlite3_init
ec80: 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c  ialize() directl
ec90: 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  y.  For example,
eca0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
ecb0: 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74  ].** calls sqlit
ecc0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
ecd0: 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  so the SQLite li
ece0: 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75  brary will be au
ecf0: 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69  tomatically.** i
ed00: 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20  nitialized when 
ed10: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
ed20: 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74   is called if it
ed30: 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74   has not be init
ed40: 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61  ialized.** alrea
ed50: 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69  dy.  ^However, i
ed60: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
ed70: 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b 53  iled with the [S
ed80: 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49  QLITE_OMIT_AUTOI
ed90: 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d  NIT].** compile-
eda0: 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65  time option, the
edb0: 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20  n the automatic 
edc0: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
edd0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a  _initialize().**
ede0: 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64   are omitted and
edf0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
ee00: 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74   must call sqlit
ee10: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
ee20: 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f  directly.** prio
ee30: 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f  r to using any o
ee40: 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
ee50: 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69  rface.  For maxi
ee60: 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c  mum portability,
ee70: 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d  .** it is recomm
ee80: 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69  ended that appli
ee90: 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69  cations always i
eea0: 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e  nvoke sqlite3_in
eeb0: 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69  itialize().** di
eec0: 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20  rectly prior to 
eed0: 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  using any other 
eee0: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
eef0: 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65 61 73  .  Future releas
ef00: 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20  es.** of SQLite 
ef10: 6d 61 79 20 72 65 71 75 69 72 65 20 74 68 69 73  may require this
ef20: 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
ef30: 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  s, the behavior 
ef40: 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65  exhibited.** whe
ef50: 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  n SQLite is comp
ef60: 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54  iled with [SQLIT
ef70: 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d  E_OMIT_AUTOINIT]
ef80: 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68   might become th
ef90: 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68  e.** default beh
efa0: 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75  avior in some fu
efb0: 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20  ture release of 
efc0: 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  SQLite..**.** Th
efd0: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  e sqlite3_os_ini
efe0: 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73  t() routine does
eff0: 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65   operating-syste
f000: 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e  m specific.** in
f010: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20  itialization of 
f020: 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
f030: 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ry.  The sqlite3
f040: 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75  _os_end().** rou
f050: 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20  tine undoes the 
f060: 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65  effect of sqlite
f070: 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79  3_os_init().  Ty
f080: 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70  pical tasks.** p
f090: 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73  erformed by thes
f0a0: 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75  e routines inclu
f0b0: 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72  de allocation or
f0c0: 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a   deallocation.**
f0d0: 20 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f 75   of static resou
f0e0: 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61  rces, initializa
f0f0: 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76  tion of global v
f100: 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74  ariables,.** set
f110: 74 69 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c  ting up a defaul
f120: 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
f130: 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69  module, or setti
f140: 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75  ng up.** a defau
f150: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
f160: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
f170: 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a  config()]..**.**
f180: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
f190: 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e   should never in
f1a0: 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69  voke either sqli
f1b0: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a  te3_os_init().**
f1c0: 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65   or sqlite3_os_e
f1d0: 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20  nd() directly.  
f1e0: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
f1f0: 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f  should only invo
f200: 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e  ke.** sqlite3_in
f210: 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73  itialize() and s
f220: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
f230: 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  ).  The sqlite3_
f240: 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74  os_init().** int
f250: 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64  erface is called
f260: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62   automatically b
f270: 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  y sqlite3_initia
f280: 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71  lize() and.** sq
f290: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69  lite3_os_end() i
f2a0: 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69  s called by sqli
f2b0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20  te3_shutdown(). 
f2c0: 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20   Appropriate.** 
f2d0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
f2e0: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  for sqlite3_os_i
f2f0: 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65  nit() and sqlite
f300: 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72  3_os_end().** ar
f310: 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  e built into SQL
f320: 69 74 65 20 77 68 65 6e 20 69 74 20 69 73 20 63  ite when it is c
f330: 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78  ompiled for Unix
f340: 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53  , Windows, or OS
f350: 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73  /2..** When [cus
f360: 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69  tom builds | bui
f370: 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61  lt for other pla
f380: 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e  tforms].** (usin
f390: 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53  g the [SQLITE_OS
f3a0: 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c  _OTHER=1] compil
f3b0: 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e  e-time.** option
f3c0: 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  ) the applicatio
f3d0: 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20  n must supply a 
f3e0: 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65  suitable impleme
f3f0: 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73  ntation for.** s
f400: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
f410: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f   and sqlite3_os_
f420: 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69  end().  An appli
f430: 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a  cation-supplied.
f440: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
f450: 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f  n of sqlite3_os_
f460: 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65  init() or sqlite
f470: 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75  3_os_end().** mu
f480: 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  st return [SQLIT
f490: 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
f4a0: 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20   and some other 
f4b0: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f  [error code] upo
f4c0: 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f  n.** failure..*/
f4d0: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69  .int sqlite3_ini
f4e0: 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69  tialize(void);.i
f4f0: 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  nt sqlite3_shutd
f500: 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  own(void);.int s
f510: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76  qlite3_os_init(v
f520: 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  oid);.int sqlite
f530: 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a  3_os_end(void);.
f540: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
f550: 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65   Configuring The
f560: 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a   SQLite Library.
f570: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
f580: 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  3_config() inter
f590: 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
f5a0: 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66  make global conf
f5b0: 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61  iguration.** cha
f5c0: 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69  nges to SQLite i
f5d0: 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20  n order to tune 
f5e0: 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70  SQLite to the sp
f5f0: 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a  ecific needs of.
f600: 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
f610: 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74  on.  The default
f620: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69   configuration i
f630: 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  s recommended fo
f640: 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63  r most.** applic
f650: 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68  ations and so th
f660: 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73  is routine is us
f670: 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73  ually not necess
f680: 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70  ary.  It is.** p
f690: 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f  rovided to suppo
f6a0: 72 74 20 72 61 72 65 20 61 70 70 6c 69 63 61 74  rt rare applicat
f6b0: 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61  ions with unusua
f6c0: 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54  l needs..**.** T
f6d0: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  he sqlite3_confi
f6e0: 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
f6f0: 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e   not threadsafe.
f700: 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f    The applicatio
f710: 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 65  n.** must insure
f720: 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53   that no other S
f730: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
f740: 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20   are invoked by 
f750: 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73  other.** threads
f760: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63   while sqlite3_c
f770: 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69  onfig() is runni
f780: 6e 67 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65  ng.  Furthermore
f790: 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  , sqlite3_config
f7a0: 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62  ().** may only b
f7b0: 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20  e invoked prior 
f7c0: 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69  to library initi
f7d0: 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a  alization using.
f7e0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  ** [sqlite3_init
f7f0: 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74  ialize()] or aft
f800: 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b  er shutdown by [
f810: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
f820: 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ()]..** ^If sqli
f830: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
f840: 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71  called after [sq
f850: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f860: 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a  ()] and before.*
f870: 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  * [sqlite3_shutd
f880: 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77  own()] then it w
f890: 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54  ill return SQLIT
f8a0: 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74  E_MISUSE..** Not
f8b0: 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74  e, however, that
f8c0: 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   ^sqlite3_config
f8d0: 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64  () can be called
f8e0: 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a   as part of the.
f8f0: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
f900: 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74  n of an applicat
f910: 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c  ion-defined [sql
f920: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e  ite3_os_init()].
f930: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
f940: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
f950: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73  ite3_config() is
f960: 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b   an integer.** [
f970: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
f980: 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72  tion] that deter
f990: 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72  mines.** what pr
f9a0: 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65  operty of SQLite
f9b0: 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67   is to be config
f9c0: 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e  ured.  Subsequen
f9d0: 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76  t arguments.** v
f9e0: 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ary depending on
f9f0: 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74   the [configurat
fa00: 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69  ion option].** i
fa10: 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
fa20: 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65  ment..**.** ^Whe
fa30: 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  n a configuratio
fa40: 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c  n option is set,
fa50: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
fa60: 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  ) returns [SQLIT
fa70: 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68  E_OK]..** ^If th
fa80: 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e  e option is unkn
fa90: 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73  own or SQLite is
faa0: 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74   unable to set t
fab0: 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65  he option.** the
fac0: 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  n this routine r
fad0: 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72  eturns a non-zer
fae0: 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  o [error code]..
faf0: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
fb00: 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b  onfig(int, ...);
fb10: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
fb20: 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61  : Configure data
fb30: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
fb40: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
fb50: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69  e3_db_config() i
fb60: 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
fb70: 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75   to make configu
fb80: 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65  ration.** change
fb90: 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65  s to a [database
fba0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54   connection].  T
fbb0: 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  he interface is 
fbc0: 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73  similar to.** [s
fbd0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
fbe0: 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65   except that the
fbf0: 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74   changes apply t
fc00: 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64  o a single.** [d
fc10: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
fc20: 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20 69  on] (specified i
fc30: 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
fc40: 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ment)..**.** The
fc50: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
fc60: 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63   to sqlite3_db_c
fc70: 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20  onfig(D,V,...)  
fc80: 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  is the.** [SQLIT
fc90: 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
fca0: 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61  SIDE | configura
fcb0: 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20  tion verb] - an 
fcc0: 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a  integer code .**
fcd0: 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20   that indicates 
fce0: 77 68 61 74 20 61 73 70 65 63 74 20 6f 66 20 74  what aspect of t
fcf0: 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
fd00: 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e  nection] is bein
fd10: 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a  g configured..**
fd20: 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75   Subsequent argu
fd30: 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e  ments vary depen
fd40: 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66  ding on the conf
fd50: 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a  iguration verb..
fd60: 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  **.** ^Calls to 
fd70: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
fd80: 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54  g() return SQLIT
fd90: 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79  E_OK if and only
fda0: 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20   if.** the call 
fdb0: 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75  is considered su
fdc0: 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74  ccessful..*/.int
fdd0: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
fde0: 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  ig(sqlite3*, int
fdf0: 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a   op, ...);../*.*
fe00: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
fe10: 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f  ry Allocation Ro
fe20: 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20  utines.**.** An 
fe30: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
fe40: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
fe50: 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65  the interface be
fe60: 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20  tween SQLite.** 
fe70: 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65  and low-level me
fe80: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
fe90: 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
fea0: 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75  This object is u
feb0: 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20  sed in only one 
fec0: 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c  place in the SQL
fed0: 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ite interface..*
fee0: 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * A pointer to a
fef0: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
ff00: 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65  is object is the
ff10: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
ff20: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
ff30: 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66  )] when the conf
ff40: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
ff50: 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43   is.** [SQLITE_C
ff60: 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72  ONFIG_MALLOC] or
ff70: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
ff80: 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a  GETMALLOC].  .**
ff90: 20 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20   By creating an 
ffa0: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
ffb0: 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70   object.** and p
ffc0: 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71  assing it to [sq
ffd0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53  lite3_config]([S
ffe0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
fff0: 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20  LOC]).** during 
10000 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61  configuration, a
10010 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61  n application ca
10020 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74  n specify an alt
10030 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f  ernative.** memo
10040 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
10050 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51 4c 69  bsystem for SQLi
10060 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c  te to use for al
10070 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61  l of its.** dyna
10080 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73  mic memory needs
10090 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
100a0 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77  t SQLite comes w
100b0 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62 75 69  ith several [bui
100c0 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
100d0 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74  ocators].** that
100e0 20 61 72 65 20 70 65 72 66 65 63 74 6c 79 20 61   are perfectly a
100f0 64 65 71 75 61 74 65 20 66 6f 72 20 74 68 65 20  dequate for the 
10100 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a  overwhelming maj
10110 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61  ority of applica
10120 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61  tions.** and tha
10130 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73  t this object is
10140 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20   only useful to 
10150 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20  a tiny minority 
10160 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  of applications.
10170 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c 69  ** with speciali
10180 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  zed memory alloc
10190 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e  ation requiremen
101a0 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74  ts.  This object
101b0 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64   is.** also used
101c0 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20   during testing 
101d0 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64  of SQLite in ord
101e0 65 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e  er to specify an
101f0 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20   alternative.** 
10200 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
10210 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20   that simulates 
10220 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65  memory out-of-me
10230 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20  mory conditions 
10240 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76  in.** order to v
10250 65 72 69 66 79 20 74 68 61 74 20 53 51 4c 69 74  erify that SQLit
10260 65 20 72 65 63 6f 76 65 72 73 20 67 72 61 63 65  e recovers grace
10270 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a  fully from such.
10280 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a  ** conditions..*
10290 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63  *.** The xMalloc
102a0 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20  , xRealloc, and 
102b0 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d 75  xFree methods mu
102c0 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65  st work like the
102d0 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65  .** malloc(), re
102e0 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
102f0 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f  () functions fro
10300 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  m the standard C
10310 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51   library..** ^SQ
10320 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20  Lite guarantees 
10330 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20  that the second 
10340 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78  argument to.** x
10350 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79  Realloc is alway
10360 73 20 61 20 76 61 6c 75 65 20 72 65 74 75 72 6e  s a value return
10370 65 64 20 62 79 20 61 20 70 72 69 6f 72 20 63 61  ed by a prior ca
10380 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a  ll to xRoundup..
10390 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75  **.** xSize shou
103a0 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c  ld return the al
103b0 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20  located size of 
103c0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
103d0 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  ion.** previousl
103e0 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
103f0 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c  xMalloc or xReal
10400 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61  loc.  The alloca
10410 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61  ted size.** is a
10420 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61  lways at least a
10430 73 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71  s big as the req
10440 75 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20  uested size but 
10450 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a  may be larger..*
10460 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75  *.** The xRoundu
10470 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  p method returns
10480 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74   what would be t
10490 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
104a0 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79  e of.** a memory
104b0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65   allocation give
104c0 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  n a particular r
104d0 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20  equested size.  
104e0 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  Most memory.** a
104f0 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20  llocators round 
10500 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  up memory alloca
10510 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74  tions at least t
10520 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69  o the next multi
10530 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f  ple.** of 8.  So
10540 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f  me allocators ro
10550 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67  und up to a larg
10560 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74  er multiple or t
10570 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a  o a power of 2..
10580 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20  ** Every memory 
10590 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65  allocation reque
105a0 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72  st coming in thr
105b0 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61  ough [sqlite3_ma
105c0 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73  lloc()].** or [s
105d0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
105e0 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52  ] first calls xR
105f0 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75  oundup.  If xRou
10600 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20  ndup returns 0, 
10610 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73 20  .** that causes 
10620 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
10630 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  g memory allocat
10640 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a  ion to fail..**.
10650 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74  ** The xInit met
10660 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  hod initializes 
10670 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
10680 61 74 6f 72 2e 20 20 28 46 6f 72 20 65 78 61 6d  ator.  (For exam
10690 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74  ple,.** it might
106a0 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65   allocate any re
106b0 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72  quire mutexes or
106c0 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65   initialize inte
106d0 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72  rnal data.** str
106e0 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53  uctures.  The xS
106f0 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69  hutdown method i
10700 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72  s invoked (indir
10710 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71  ectly) by.** [sq
10720 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
10730 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61  ] and should dea
10740 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f  llocate any reso
10750 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a  urces acquired.*
10760 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65  * by xInit.  The
10770 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65   pAppData pointe
10780 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65  r is used as the
10790 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20   only parameter 
107a0 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20  to.** xInit and 
107b0 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a  xShutdown..**.**
107c0 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68   SQLite holds th
107d0 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  e [SQLITE_MUTEX_
107e0 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d  STATIC_MASTER] m
107f0 75 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76  utex when it inv
10800 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69  okes.** the xIni
10810 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65  t method, so the
10820 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65   xInit method ne
10830 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64  ed not be thread
10840 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53  safe.  The.** xS
10850 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69  hutdown method i
10860 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72  s only called fr
10870 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  om [sqlite3_shut
10880 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f  down()] so it do
10890 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74  es.** not need t
108a0 6f 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20  o be threadsafe 
108b0 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c  either.  For all
108c0 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20   other methods, 
108d0 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20  SQLite.** holds 
108e0 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45  the [SQLITE_MUTE
108f0 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75  X_STATIC_MEM] mu
10900 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  tex as long as t
10910 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  he.** [SQLITE_CO
10920 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20  NFIG_MEMSTATUS] 
10930 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
10940 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f  tion is turned o
10950 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69  n (which.** it i
10960 73 20 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e  s by default) an
10970 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73  d so the methods
10980 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c   are automatical
10990 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a  ly serialized..*
109a0 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53  * However, if [S
109b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
109c0 53 54 41 54 55 53 5d 20 69 73 20 64 69 73 61 62  STATUS] is disab
109d0 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74  led, then the ot
109e0 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d  her.** methods m
109f0 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66  ust be threadsaf
10a00 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74  e or else make t
10a10 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65  heir own arrange
10a20 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72  ments for.** ser
10a30 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  ialization..**.*
10a40 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65  * SQLite will ne
10a50 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74  ver invoke xInit
10a60 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63  () more than onc
10a70 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74  e without an int
10a80 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c  ervening.** call
10a90 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e   to xShutdown().
10aa0 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
10ab0 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ct sqlite3_mem_m
10ac0 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d  ethods sqlite3_m
10ad0 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75  em_methods;.stru
10ae0 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ct sqlite3_mem_m
10af0 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20  ethods {.  void 
10b00 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29  *(*xMalloc)(int)
10b10 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d  ;         /* Mem
10b20 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
10b30 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  unction */.  voi
10b40 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a  d (*xFree)(void*
10b50 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46  );          /* F
10b60 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f  ree a prior allo
10b70 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64  cation */.  void
10b80 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f   *(*xRealloc)(vo
10b90 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65  id*,int);  /* Re
10ba0 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69  size an allocati
10bb0 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53  on */.  int (*xS
10bc0 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  ize)(void*);    
10bd0 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e         /* Return
10be0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20   the size of an 
10bf0 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
10c00 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28  int (*xRoundup)(
10c10 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f  int);          /
10c20 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65  * Round up reque
10c30 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63  st size to alloc
10c40 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20  ation size */.  
10c50 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69  int (*xInit)(voi
10c60 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f  d*);           /
10c70 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  * Initialize the
10c80 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
10c90 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53  r */.  void (*xS
10ca0 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b  hutdown)(void*);
10cb0 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69        /* Deiniti
10cc0 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  alize the memory
10cd0 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20   allocator */.  
10ce0 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20  void *pAppData; 
10cf0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
10d00 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49  * Argument to xI
10d10 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 74 64  nit() and xShutd
10d20 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  own() */.};../*.
10d30 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
10d40 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f  figuration Optio
10d50 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ns.** KEYWORDS: 
10d60 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f  {configuration o
10d70 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  ption}.**.** The
10d80 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
10d90 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69   the available i
10da0 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61  nteger configura
10db0 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61  tion options tha
10dc0 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73  t.** can be pass
10dd0 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
10de0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
10df0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
10e00 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
10e10 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72  .** New configur
10e20 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61  ation options ma
10e30 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
10e40 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
10e50 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73   SQLite..** Exis
10e60 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ting configurati
10e70 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74  on options might
10e80 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64   be discontinued
10e90 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a  .  Applications.
10ea0 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20  ** should check 
10eb0 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20  the return code 
10ec0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f  from [sqlite3_co
10ed0 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20  nfig()] to make 
10ee0 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  sure that.** the
10ef0 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54   call worked.  T
10f00 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  he [sqlite3_conf
10f10 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ig()] interface 
10f20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a  will return a.**
10f30 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
10f40 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63   code] if a disc
10f50 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75  ontinued or unsu
10f60 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72  pported configur
10f70 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20  ation option.** 
10f80 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  is invoked..**.*
10f90 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49  * <dl>.** [[SQLI
10fa0 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
10fb0 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c  THREAD]] <dt>SQL
10fc0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
10fd0 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20  ETHREAD</dt>.** 
10fe0 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
10ff0 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
11000 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69  is option.  ^Thi
11010 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
11020 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20  e.** [threading 
11030 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d  mode] to Single-
11040 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65  thread.  In othe
11050 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61  r words, it disa
11060 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65  bles.** all mute
11070 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51  xing and puts SQ
11080 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65  Lite into a mode
11090 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e   where it can on
110a0 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79  ly be used.** by
110b0 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64   a single thread
110c0 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .   ^If SQLite i
110d0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
110e0 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
110f0 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
11100 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
11110 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
11120 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
11130 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
11140 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b 74  to change the [t
11150 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66  hreading mode] f
11160 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74 0a  rom its default.
11170 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e 67  ** value of Sing
11180 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73 6f  le-thread and so
11190 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
111a0 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
111b0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  .** [SQLITE_ERRO
111c0 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
111d0 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  h the SQLITE_CON
111e0 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
111f0 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  .** configuratio
11200 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  n option.</dd>.*
11210 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
11220 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
11230 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
11240 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
11250 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
11260 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
11270 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
11280 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
11290 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
112a0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
112b0 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20  o Multi-thread. 
112c0 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
112d0 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20   it disables.** 
112e0 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74  mutexing on [dat
112f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
11300 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
11310 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63  statement] objec
11320 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  ts..** The appli
11330 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e  cation is respon
11340 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c  sible for serial
11350 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a  izing access to.
11360 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
11370 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70  nections] and [p
11380 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
11390 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20  ts].  But other 
113a0 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65  mutexes.** are e
113b0 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53  nabled so that S
113c0 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61  QLite will be sa
113d0 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d  fe to use in a m
113e0 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a  ulti-threaded.**
113f0 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20   environment as 
11400 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74  long as no two t
11410 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 20 74  hreads attempt t
11420 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a  o use the same.*
11430 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
11440 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73  ection] at the s
11450 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53  ame time.  ^If S
11460 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
11470 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
11480 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
11490 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
114a0 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
114b0 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
114c0 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
114d0 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68  ssible to set th
114e0 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b  e Multi-thread [
114f0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
11500 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
11510 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72  config()] will r
11520 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
11530 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77  ROR] if called w
11540 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54  ith the.** SQLIT
11550 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
11560 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69  READ configurati
11570 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a  on option.</dd>.
11580 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
11590 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
115a0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
115b0 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c  NFIG_SERIALIZED<
115c0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
115d0 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
115e0 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
115f0 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  n.  ^This option
11600 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68   sets the.** [th
11610 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
11620 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20   Serialized. In 
11630 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69  other words, thi
11640 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73  s option enables
11650 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20  .** all mutexes 
11660 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65  including the re
11670 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78  cursive.** mutex
11680 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  es on [database 
11690 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20  connection] and 
116a0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
116b0 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  ent] objects..**
116c0 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77   In this mode (w
116d0 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66 61  hich is the defa
116e0 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20  ult when SQLite 
116f0 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
11700 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  .** [SQLITE_THRE
11710 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53  ADSAFE=1]) the S
11720 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69  QLite library wi
11730 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c  ll itself serial
11740 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ize access.** to
11750 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
11760 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65  ctions] and [pre
11770 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
11780 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a  ] so that the.**
11790 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20   application is 
117a0 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65 20  free to use the 
117b0 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63  same [database c
117c0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68  onnection] or th
117d0 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61  e.** same [prepa
117e0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
117f0 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  n different thre
11800 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20  ads at the same 
11810 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c  time..** ^If SQL
11820 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
11830 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
11840 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
11850 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
11860 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
11870 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
11880 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73  * it is not poss
11890 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20  ible to set the 
118a0 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65  Serialized [thre
118b0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a  ading mode] and.
118c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
118d0 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ig()] will retur
118e0 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
118f0 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20   if called with 
11900 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f  the.** SQLITE_CO
11910 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20  NFIG_SERIALIZED 
11920 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
11930 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
11940 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
11950 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51  _MALLOC]] <dt>SQ
11960 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
11970 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OC</dt>.** <dd> 
11980 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
11990 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
119a0 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
119b0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
119c0 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  * instance of th
119d0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
119e0 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
119f0 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74  e.  The argument
11a00 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c   specifies.** al
11a10 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65  ternative low-le
11a20 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  vel memory alloc
11a30 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74  ation routines t
11a40 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61  o be used in pla
11a50 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d  ce of.** the mem
11a60 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
11a70 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e  outines built in
11a80 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51  to SQLite.)^ ^SQ
11a90 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74  Lite makes.** it
11aa0 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
11ab0 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e  py of the conten
11ac0 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  t of the [sqlite
11ad0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
11ae0 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f  tructure.** befo
11af0 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  re the [sqlite3_
11b00 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72  config()] call r
11b10 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a  eturns.</dd>.**.
11b20 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
11b30 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c  IG_GETMALLOC]] <
11b40 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
11b50 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a  _GETMALLOC</dt>.
11b60 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
11b70 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
11b80 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
11b90 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
11ba0 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e   to an.** instan
11bb0 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
11bc0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
11bd0 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20  structure.  The 
11be0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
11bf0 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75  hods].** structu
11c00 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  re is filled wit
11c10 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20  h the currently 
11c20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61  defined memory a
11c30 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
11c40 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70  es.)^.** This op
11c50 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64  tion can be used
11c60 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65   to overload the
11c70 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20   default memory 
11c80 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f  allocation.** ro
11c90 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72  utines with a wr
11ca0 61 70 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c  apper that simul
11cb0 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c  ations memory al
11cc0 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65  location failure
11cd0 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65   or.** tracks me
11ce0 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20  mory usage, for 
11cf0 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a  example. </dd>.*
11d00 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
11d10 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d  NFIG_MEMSTATUS]]
11d20 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
11d30 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74  IG_MEMSTATUS</dt
11d40 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
11d50 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e  option takes sin
11d60 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  gle argument of 
11d70 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 70  type int, interp
11d80 72 65 74 65 64 20 61 73 20 61 20 0a 2a 2a 20 62  reted as a .** b
11d90 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e  oolean, which en
11da0 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
11db0 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e  s the collection
11dc0 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63   of memory alloc
11dd0 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73  ation .** statis
11de0 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d  tics. ^(When mem
11df0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
11e00 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69  tatistics are di
11e10 73 61 62 6c 65 64 2c 20 74 68 65 20 0a 2a 2a 20  sabled, the .** 
11e20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65  following SQLite
11e30 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f   interfaces beco
11e40 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e  me non-operation
11e50 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a  al:.**   <ul>.**
11e60 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
11e70 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a  _memory_used()].
11e80 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
11e90 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
11ea0 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  ter()].**   <li>
11eb0 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68   [sqlite3_soft_h
11ec0 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a  eap_limit64()].*
11ed0 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
11ee0 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20  3_status()].**  
11ef0 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d   </ul>)^.** ^Mem
11f00 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
11f10 74 61 74 69 73 74 69 63 73 20 61 72 65 20 65 6e  tatistics are en
11f20 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
11f30 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69   unless SQLite i
11f40 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69  s.** compiled wi
11f50 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55  th [SQLITE_DEFAU
11f60 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20  LT_MEMSTATUS]=0 
11f70 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d 65  in which case me
11f80 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69  mory.** allocati
11f90 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72  on statistics ar
11fa0 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  e disabled by de
11fb0 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a  fault..** </dd>.
11fc0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
11fd0 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 5d 20  ONFIG_SCRATCH]] 
11fe0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
11ff0 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a  G_SCRATCH</dt>.*
12000 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
12010 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
12020 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75  static memory bu
12030 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  ffer that SQLite
12040 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20   can use for.** 
12050 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20  scratch memory. 
12060 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65   There are three
12070 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41 20 70   arguments:  A p
12080 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65  ointer an 8-byte
12090 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f  .** aligned memo
120a0 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77  ry buffer from w
120b0 68 69 63 68 20 74 68 65 20 73 63 72 61 74 63 68  hich the scratch
120c0 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c   allocations wil
120d0 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74  l be.** drawn, t
120e0 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  he size of each 
120f0 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69  scratch allocati
12100 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20  on (sz),.** and 
12110 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  the maximum numb
12120 65 72 20 6f 66 20 73 63 72 61 74 63 68 20 61 6c  er of scratch al
12130 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 20 20  locations (N).  
12140 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d 65  The sz.** argume
12150 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d 75 6c  nt must be a mul
12160 74 69 70 6c 65 20 6f 66 20 31 36 2e 0a 2a 2a 20  tiple of 16..** 
12170 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
12180 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69  nt must be a poi
12190 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74  nter to an 8-byt
121a0 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72  e aligned buffer
121b0 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20  .** of at least 
121c0 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65  sz*N bytes of me
121d0 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  mory..** ^SQLite
121e0 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72   will use no mor
121f0 65 20 74 68 61 6e 20 74 77 6f 20 73 63 72 61 74  e than two scrat
12200 63 68 20 62 75 66 66 65 72 73 20 70 65 72 20 74  ch buffers per t
12210 68 72 65 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e 20  hread.  So.** N 
12220 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20 74 6f  should be set to
12230 20 74 77 69 63 65 20 74 68 65 20 65 78 70 65 63   twice the expec
12240 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  ted maximum numb
12250 65 72 20 6f 66 20 74 68 72 65 61 64 73 2e 0a 2a  er of threads..*
12260 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e  * ^SQLite will n
12270 65 76 65 72 20 72 65 71 75 69 72 65 20 61 20 73  ever require a s
12280 63 72 61 74 63 68 20 62 75 66 66 65 72 20 74 68  cratch buffer th
12290 61 74 20 69 73 20 6d 6f 72 65 20 74 68 61 6e 20  at is more than 
122a0 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65 20 64  6.** times the d
122b0 61 74 61 62 61 73 65 20 70 61 67 65 20 73 69 7a  atabase page siz
122c0 65 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 6e 65  e. ^If SQLite ne
122d0 65 64 73 20 6e 65 65 64 73 20 61 64 64 69 74 69  eds needs additi
122e0 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20  onal.** scratch 
122f0 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68  memory beyond wh
12300 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62  at is provided b
12310 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61  y this configura
12320 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65  tion option, the
12330 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  n .** [sqlite3_m
12340 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65  alloc()] will be
12350 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20   used to obtain 
12360 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65  the memory neede
12370 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  d.</dd>.**.** [[
12380 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
12390 47 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51  GECACHE]] <dt>SQ
123a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
123b0 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  CACHE</dt>.** <d
123c0 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
123d0 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
123e0 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
123f0 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e   that SQLite can
12400 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20   use for.** the 
12410 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63 61  database page ca
12420 63 68 65 20 77 69 74 68 20 74 68 65 20 64 65 66  che with the def
12430 61 75 6c 74 20 70 61 67 65 20 63 61 63 68 65 20  ault page cache 
12440 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20  implementation. 
12450 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67   .** This config
12460 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e  uration should n
12470 6f 74 20 62 65 20 75 73 65 64 20 69 66 20 61 6e  ot be used if an
12480 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
12490 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68  ine page.** cach
124a0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
124b0 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67   is loaded using
124c0 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
124d0 49 47 5f 50 43 41 43 48 45 32 20 6f 70 74 69 6f  IG_PCACHE2 optio
124e0 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  n..** There are 
124f0 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20  three arguments 
12500 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a 20  to this option: 
12510 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 38 2d 62  A pointer to 8-b
12520 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d  yte aligned.** m
12530 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a 65 20  emory, the size 
12540 6f 66 20 65 61 63 68 20 70 61 67 65 20 62 75 66  of each page buf
12550 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68  fer (sz), and th
12560 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65  e number of page
12570 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a  s (N)..** The sz
12580 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
12590 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20   be the size of 
125a0 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 74 61  the largest data
125b0 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 20  base page.** (a 
125c0 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74  power of two bet
125d0 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33 32 37  ween 512 and 327
125e0 36 38 29 20 70 6c 75 73 20 61 20 6c 69 74 74 6c  68) plus a littl
125f0 65 20 65 78 74 72 61 20 66 6f 72 20 65 61 63 68  e extra for each
12600 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e  .** page header.
12610 20 20 5e 54 68 65 20 70 61 67 65 20 68 65 61 64    ^The page head
12620 65 72 20 73 69 7a 65 20 69 73 20 32 30 20 74 6f  er size is 20 to
12630 20 34 30 20 62 79 74 65 73 20 64 65 70 65 6e 64   40 bytes depend
12640 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f  ing on.** the ho
12650 73 74 20 61 72 63 68 69 74 65 63 74 75 72 65 2e  st architecture.
12660 20 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73    ^It is harmles
12670 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68  s, apart from th
12680 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c  e wasted memory,
12690 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 7a 20 61  .** to make sz a
126a0 20 6c 69 74 74 6c 65 20 74 6f 6f 20 6c 61 72 67   little too larg
126b0 65 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a  e.  The first.**
126c0 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
126d0 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c   point to an all
126e0 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65  ocation of at le
126f0 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f  ast sz*N bytes o
12700 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51  f memory..** ^SQ
12710 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68  Lite will use th
12720 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65  e memory provide
12730 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 61  d by the first a
12740 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73  rgument to satis
12750 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79  fy its.** memory
12760 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20 66   needs for the f
12770 69 72 73 74 20 4e 20 70 61 67 65 73 20 74 68 61  irst N pages tha
12780 74 20 69 74 20 61 64 64 73 20 74 6f 20 63 61 63  t it adds to cac
12790 68 65 2e 20 20 5e 49 66 20 61 64 64 69 74 69 6f  he.  ^If additio
127a0 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68  nal.** page cach
127b0 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64  e memory is need
127c0 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69  ed beyond what i
127d0 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  s provided by th
127e0 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a  is option, then.
127f0 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74  ** SQLite goes t
12800 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  o [sqlite3_mallo
12810 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64  c()] for the add
12820 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20  itional storage 
12830 73 70 61 63 65 2e 0a 2a 2a 20 54 68 65 20 70 6f  space..** The po
12840 69 6e 74 65 72 20 69 6e 20 74 68 65 20 66 69 72  inter in the fir
12850 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  st argument must
12860 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65 64 20 74  .** be aligned t
12870 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e  o an 8-byte boun
12880 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65  dary or subseque
12890 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53  nt behavior of S
128a0 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 62 65  QLite.** will be
128b0 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e   undefined.</dd>
128c0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
128d0 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64  CONFIG_HEAP]] <d
128e0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
128f0 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  HEAP</dt>.** <dd
12900 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73  > ^This option s
12910 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69  pecifies a stati
12920 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  c memory buffer 
12930 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
12940 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20   use.** for all 
12950 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d  of its dynamic m
12960 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12970 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74 68   needs beyond th
12980 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20  ose provided.** 
12990 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43  for by [SQLITE_C
129a0 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61  ONFIG_SCRATCH] a
129b0 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  nd [SQLITE_CONFI
129c0 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a  G_PAGECACHE]..**
129d0 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65   There are three
129e0 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20 38   arguments: An 8
129f0 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f  -byte aligned po
12a00 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d  inter to the mem
12a10 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  ory,.** the numb
12a20 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
12a30 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  he memory buffer
12a40 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75  , and the minimu
12a50 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  m allocation siz
12a60 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  e..** ^If the fi
12a70 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65  rst pointer (the
12a80 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29   memory pointer)
12a90 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53   is NULL, then S
12aa0 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a  QLite reverts.**
12ab0 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65   to using its de
12ac0 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c  fault memory all
12ad0 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73 74  ocator (the syst
12ae0 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c  em malloc() impl
12af0 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20  ementation),.** 
12b00 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f  undoing any prio
12b10 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  r invocation of 
12b20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
12b30 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65  ALLOC].  ^If the
12b40 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  .** memory point
12b50 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61  er is not NULL a
12b60 6e 64 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  nd either [SQLIT
12b70 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33  E_ENABLE_MEMSYS3
12b80 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
12b90 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20  ENABLE_MEMSYS5] 
12ba0 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68 65  are defined, the
12bb0 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76  n the alternativ
12bc0 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
12bd0 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64  cator is engaged
12be0 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f   to handle all o
12bf0 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79  f SQLites memory
12c00 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
12c10 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  s..** The first 
12c20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d  pointer (the mem
12c30 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73  ory pointer) mus
12c40 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20  t be aligned to 
12c50 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75  an 8-byte.** bou
12c60 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75  ndary or subsequ
12c70 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20  ent behavior of 
12c80 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75  SQLite will be u
12c90 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  ndefined..** The
12ca0 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74   minimum allocat
12cb0 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70  ion size is capp
12cc0 65 64 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 61  ed at 2**12. Rea
12cd0 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a  sonable values.*
12ce0 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75  * for the minimu
12cf0 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  m allocation siz
12d00 65 20 61 72 65 20 32 2a 2a 35 20 74 68 72 6f 75  e are 2**5 throu
12d10 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a  gh 2**8.</dd>.**
12d20 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
12d30 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e  FIG_MUTEX]] <dt>
12d40 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
12d50 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TEX</dt>.** <dd>
12d60 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
12d70 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
12d80 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
12d90 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
12da0 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
12db0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
12dc0 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
12dd0 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d  ture.  The argum
12de0 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  ent specifies.**
12df0 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77   alternative low
12e00 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75  -level mutex rou
12e10 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64  tines to be used
12e20 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65   in place.** the
12e30 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20   mutex routines 
12e40 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
12e50 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61  e.)^  ^SQLite ma
12e60 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
12e70 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 6f 66 20  e.** content of 
12e80 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
12e90 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
12ea0 63 74 75 72 65 20 62 65 66 6f 72 65 20 74 68 65  cture before the
12eb0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
12ec0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72  ite3_config()] r
12ed0 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69  eturns. ^If SQLi
12ee0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
12ef0 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
12f00 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
12f10 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
12f20 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
12f30 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
12f40 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65   the entire mute
12f50 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69  xing subsystem i
12f60 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  s omitted from t
12f70 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e  he build and hen
12f80 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b  ce calls to.** [
12f90 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
12fa0 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54  ] with the SQLIT
12fb0 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63  E_CONFIG_MUTEX c
12fc0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
12fd0 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75  ion will.** retu
12fe0 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
12ff0 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ].</dd>.**.** [[
13000 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
13010 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c  TMUTEX]] <dt>SQL
13020 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
13030 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TEX</dt>.** <dd>
13040 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
13050 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
13060 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
13070 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
13080 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
13090 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
130a0 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
130b0 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73  ture.  The.** [s
130c0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
130d0 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75  hods].** structu
130e0 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  re is filled wit
130f0 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20  h the currently 
13100 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f  defined mutex ro
13110 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69  utines.)^.** Thi
13120 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  s option can be 
13130 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64  used to overload
13140 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74   the default mut
13150 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ex allocation.**
13160 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61   routines with a
13170 20 77 72 61 70 70 65 72 20 75 73 65 64 20 74 6f   wrapper used to
13180 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61   track mutex usa
13190 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e  ge for performan
131a0 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20  ce.** profiling 
131b0 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20  or testing, for 
131c0 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53  example.   ^If S
131d0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
131e0 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
131f0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
13200 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
13210 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
13220 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
13230 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d  .** the entire m
13240 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65  utexing subsyste
13250 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  m is omitted fro
13260 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20  m the build and 
13270 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a  hence calls to.*
13280 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
13290 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51  g()] with the SQ
132a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
132b0 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69  UTEX configurati
132c0 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a  on option will.*
132d0 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
132e0 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a  _ERROR].</dd>.**
132f0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
13300 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20  FIG_LOOKASIDE]] 
13310 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
13320 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e  G_LOOKASIDE</dt>
13330 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
13340 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f  option takes two
13350 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
13360 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 65  determine the de
13370 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20  fault.** memory 
13380 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 74  allocation for t
13390 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  he lookaside mem
133a0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 6e  ory allocator on
133b0 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61   each.** [databa
133c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
133d0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
133e0 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69  ent is the.** si
133f0 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61  ze of each looka
13400 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74  side buffer slot
13410 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
13420 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
13430 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61  .** slots alloca
13440 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 61  ted to each data
13450 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
13460 29 5e 20 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  )^  ^(This optio
13470 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 3c 69  n sets the.** <i
13480 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f  >default</i> loo
13490 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65  kaside size. The
134a0 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49   [SQLITE_DBCONFI
134b0 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20  G_LOOKASIDE].** 
134c0 76 65 72 62 20 74 6f 20 5b 73 71 6c 69 74 65 33  verb to [sqlite3
134d0 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61  _db_config()] ca
134e0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 68 61  n be used to cha
134f0 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64  nge the lookasid
13500 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  e.** configurati
13510 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c  on on individual
13520 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20   connections.)^ 
13530 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
13540 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
13550 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  HE2]] <dt>SQLITE
13560 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 3c  _CONFIG_PCACHE2<
13570 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
13580 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
13590 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
135a0 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
135b0 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b  inter to.** an [
135c0 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
135d0 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e  ethods2] object.
135e0 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70    This object sp
135f0 65 63 69 66 69 65 73 20 74 68 65 20 69 6e 74 65  ecifies the inte
13600 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63 75  rface.** to a cu
13610 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20  stom page cache 
13620 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29  implementation.)
13630 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  ^  ^SQLite makes
13640 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
13650 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20 75 73 65  * object and use
13660 73 20 69 74 20 66 6f 72 20 70 61 67 65 20 63 61  s it for page ca
13670 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  che memory alloc
13680 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a  ations.</dd>.**.
13690 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
136a0 49 47 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20  IG_GETPCACHE2]] 
136b0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
136c0 47 5f 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74  G_GETPCACHE2</dt
136d0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
136e0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
136f0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
13700 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
13710 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c  er to an.** [sql
13720 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
13730 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53  ods2] object.  S
13740 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66 20  QLite copies of 
13750 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 70  the current.** p
13760 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  age cache implem
13770 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68  entation into th
13780 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64  at object.)^ </d
13790 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
137a0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c  E_CONFIG_LOG]] <
137b0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
137c0 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  _LOG</dt>.** <dd
137d0 3e 20 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  > The SQLITE_CON
137e0 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 69  FIG_LOG option i
137f0 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67  s used to config
13800 75 72 65 20 74 68 65 20 53 51 4c 69 74 65 0a 2a  ure the SQLite.*
13810 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 72 6f 72 20  * global [error 
13820 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20 53  log]..** (^The S
13830 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
13840 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77   option takes tw
13850 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20 70  o arguments: a p
13860 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66  ointer to a.** f
13870 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 63  unction with a c
13880 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f 66  all signature of
13890 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69   void(*)(void*,i
138a0 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  nt,const char*),
138b0 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74   .** and a point
138c0 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20  er to void. ^If 
138d0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69  the function poi
138e0 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  nter is not NULL
138f0 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b  , it is.** invok
13900 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  ed by [sqlite3_l
13910 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73 73  og()] to process
13920 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65 76   each logging ev
13930 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  ent.  ^If the.**
13940 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65   function pointe
13950 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b  r is NULL, the [
13960 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69  sqlite3_log()] i
13970 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65 73  nterface becomes
13980 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68   a no-op..** ^Th
13990 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 74  e void pointer t
139a0 68 61 74 20 69 73 20 74 68 65 20 73 65 63 6f 6e  hat is the secon
139b0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53 51  d argument to SQ
139c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
139d0 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 72  is.** passed thr
139e0 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73  ough as the firs
139f0 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
13a00 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
13a10 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a  efined logger.**
13a20 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76   function whenev
13a30 65 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e  er that function
13a40 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54   is invoked.  ^T
13a50 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
13a60 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f  ter to.** the lo
13a70 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69 73  gger function is
13a80 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66   a copy of the f
13a90 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
13aa0 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  o the correspond
13ab0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
13ac0 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20  log()] call and 
13ad0 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 62  is intended to b
13ae0 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  e a [result code
13af0 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65  ] or an.** [exte
13b00 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
13b10 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 70  ].  ^The third p
13b20 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 20  arameter passed 
13b30 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69 73  to the logger is
13b40 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65 20  .** log message 
13b50 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e 67  after formatting
13b60 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e   via [sqlite3_sn
13b70 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68  printf()]..** Th
13b80 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67  e SQLite logging
13b90 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f   interface is no
13ba0 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68 65  t reentrant; the
13bb0 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e   logger function
13bc0 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79 20  .** supplied by 
13bd0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
13be0 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20  must not invoke 
13bf0 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72  any SQLite inter
13c00 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75  face..** In a mu
13c10 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61 70 70  lti-threaded app
13c20 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61 70  lication, the ap
13c30 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
13c40 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63  d logger.** func
13c50 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68 72  tion must be thr
13c60 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a  eadsafe. </dd>.*
13c70 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
13c80 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e 53  NFIG_URI]] <dt>S
13c90 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
13ca0 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 69 73 20 6f  .** <dd>^(This o
13cb0 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
13cc0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66  ngle argument of
13cd0 20 74 79 70 65 20 69 6e 74 2e 20 49 66 20 6e 6f   type int. If no
13ce0 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 0a 2a 2a 20  n-zero, then.** 
13cf0 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20  URI handling is 
13d00 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64  globally enabled
13d10 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d 65 74  . If the paramet
13d20 65 72 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e  er is zero, then
13d30 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 0a 2a 2a   URI handling.**
13d40 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73   is globally dis
13d50 61 62 6c 65 64 2e 29 5e 20 5e 49 66 20 55 52 49  abled.)^ ^If URI
13d60 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f   handling is glo
13d70 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2c 20 61  bally enabled, a
13d80 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a 2a 20  ll filenames.** 
13d90 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74  passed to [sqlit
13da0 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
13db0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
13dc0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
13dd0 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66  ()] or.** specif
13de0 69 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 5b  ied as part of [
13df0 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73  ATTACH] commands
13e00 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
13e10 20 61 73 20 55 52 49 73 2c 20 72 65 67 61 72 64   as URIs, regard
13e20 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68  less.** of wheth
13e30 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53  er or not the [S
13e40 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
13e50 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e  flag is set when
13e60 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
13e70 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
13e80 70 65 6e 65 64 2e 20 5e 49 66 20 69 74 20 69 73  pened. ^If it is
13e90 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c   globally disabl
13ea0 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61 72  ed, filenames ar
13eb0 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70  e.** only interp
13ec0 72 65 74 65 64 20 61 73 20 55 52 49 73 20 69 66  reted as URIs if
13ed0 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e   the SQLITE_OPEN
13ee0 5f 55 52 49 20 66 6c 61 67 20 69 73 20 73 65 74  _URI flag is set
13ef0 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74   when the.** dat
13f00 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
13f10 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 28 42 79   is opened. ^(By
13f20 20 64 65 66 61 75 6c 74 2c 20 55 52 49 20 68 61   default, URI ha
13f30 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c  ndling is global
13f40 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20  ly.** disabled. 
13f50 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75  The default valu
13f60 65 20 6d 61 79 20 62 65 20 63 68 61 6e 67 65 64  e may be changed
13f70 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69   by compiling wi
13f80 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  th the.** [SQLIT
13f90 45 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f  E_USE_URI] symbo
13fa0 6c 20 64 65 66 69 6e 65 64 2e 29 5e 0a 2a 2a 0a  l defined.)^.**.
13fb0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
13fc0 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  IG_COVERING_INDE
13fd0 58 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c  X_SCAN]] <dt>SQL
13fe0 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52  ITE_CONFIG_COVER
13ff0 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 0a 2a  ING_INDEX_SCAN.*
14000 2a 20 3c 64 64 3e 5e 54 68 69 73 20 6f 70 74 69  * <dd>^This opti
14010 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
14020 65 20 69 6e 74 65 67 65 72 20 61 72 67 75 6d 65  e integer argume
14030 6e 74 20 77 68 69 63 68 20 69 73 20 69 6e 74 65  nt which is inte
14040 72 70 72 65 74 65 64 20 61 73 0a 2a 2a 20 61 20  rpreted as.** a 
14050 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72 64 65 72  boolean in order
14060 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69   to enable or di
14070 73 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66  sable the use of
14080 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65   covering indice
14090 73 20 66 6f 72 0a 2a 2a 20 66 75 6c 6c 20 74 61  s for.** full ta
140a0 62 6c 65 20 73 63 61 6e 73 20 69 6e 20 74 68 65  ble scans in the
140b0 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a 65 72   query optimizer
140c0 2e 20 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  .  ^The default 
140d0 73 65 74 74 69 6e 67 20 69 73 20 64 65 74 65 72  setting is deter
140e0 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65 20  mined.** by the 
140f0 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f  [SQLITE_ALLOW_CO
14100 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
14110 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  N] compile-time 
14120 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f  option, or is "o
14130 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74 20 63 6f  n".** if that co
14140 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
14150 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a  n is omitted..**
14160 20 54 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20   The ability to 
14170 64 69 73 61 62 6c 65 20 74 68 65 20 75 73 65 20  disable the use 
14180 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69  of covering indi
14190 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62  ces for full tab
141a0 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62  le scans.** is b
141b0 65 63 61 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f  ecause some inco
141c0 72 72 65 63 74 6c 79 20 63 6f 64 65 64 20 6c 65  rrectly coded le
141d0 67 61 63 79 20 61 70 70 6c 69 63 61 74 69 6f 6e  gacy application
141e0 73 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63 74  s might malfunct
141f0 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20  ion.** when the 
14200 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20  optimization is 
14210 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76 69 64  enabled.  Provid
14220 69 6e 67 20 74 68 65 20 61 62 69 6c 69 74 79 20  ing the ability 
14230 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74 68  to.** disable th
14240 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61  e optimization a
14250 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65 72 2c  llows the older,
14260 20 62 75 67 67 79 20 61 70 70 6c 69 63 61 74 69   buggy applicati
14270 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a  on code to work.
14280 2a 2a 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67  ** without chang
14290 65 20 65 76 65 6e 20 77 69 74 68 20 6e 65 77 65  e even with newe
142a0 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  r versions of SQ
142b0 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  Lite..**.** [[SQ
142c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
142d0 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  HE]] [[SQLITE_CO
142e0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d  NFIG_GETPCACHE]]
142f0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
14300 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61 6e 64  ONFIG_PCACHE and
14310 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
14320 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e  ETPCACHE.** <dd>
14330 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 73 20 61   These options a
14340 72 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20  re obsolete and 
14350 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73  should not be us
14360 65 64 20 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a  ed by new code..
14370 2a 2a 20 54 68 65 79 20 61 72 65 20 72 65 74 61  ** They are reta
14380 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  ined for backwar
14390 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
143a0 20 62 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d   but are now no-
143b0 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ops..** </dd>.**
143c0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
143d0 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20  FIG_SQLLOG]].** 
143e0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
143f0 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e  G_SQLLOG.** <dd>
14400 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f  This option is o
14410 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
14420 20 73 71 6c 69 74 65 20 69 73 20 63 6f 6d 70 69   sqlite is compi
14430 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
14440 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53  [SQLITE_ENABLE_S
14450 51 4c 4c 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65  QLLOG] pre-proce
14460 73 73 6f 72 20 6d 61 63 72 6f 20 64 65 66 69 6e  ssor macro defin
14470 65 64 2e 20 54 68 65 20 66 69 72 73 74 20 61 72  ed. The first ar
14480 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a  gument should.**
14490 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   be a pointer to
144a0 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74   a function of t
144b0 79 70 65 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  ype void(*)(void
144c0 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74  *,sqlite3*,const
144d0 20 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a   char*, int)..**
144e0 20 54 68 65 20 73 65 63 6f 6e 64 20 73 68 6f 75   The second shou
144f0 6c 64 20 62 65 20 6f 66 20 74 79 70 65 20 28 76  ld be of type (v
14500 6f 69 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62  oid*). The callb
14510 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 62  ack is invoked b
14520 79 20 74 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a  y the library.**
14530 20 69 6e 20 74 68 72 65 65 20 73 65 70 61 72 61   in three separa
14540 74 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73  te circumstances
14550 2c 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20  , identified by 
14560 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64  the value passed
14570 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74   as the.** fourt
14580 68 20 70 61 72 61 6d 65 74 65 72 2e 20 49 66 20  h parameter. If 
14590 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
145a0 65 74 65 72 20 69 73 20 30 2c 20 74 68 65 6e 20  eter is 0, then 
145b0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
145c0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65  nection.** passe
145d0 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
145e0 61 72 67 75 6d 65 6e 74 20 68 61 73 20 6a 75 73  argument has jus
145f0 74 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54  t been opened. T
14600 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
14610 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61  t.** points to a
14620 20 62 75 66 66 65 72 20 63 6f 6e 74 61 69 6e 69   buffer containi
14630 6e 67 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ng the name of t
14640 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65  he main database
14650 20 66 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a   file. If the.**
14660 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
14670 72 20 69 73 20 31 2c 20 74 68 65 6e 20 74 68 65  r is 1, then the
14680 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
14690 68 61 74 20 74 68 65 20 74 68 69 72 64 20 70 61  hat the third pa
146a0 72 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74  rameter.** point
146b0 73 20 74 6f 20 68 61 73 20 6a 75 73 74 20 62 65  s to has just be
146c0 65 6e 20 65 78 65 63 75 74 65 64 2e 20 4f 72 2c  en executed. Or,
146d0 20 69 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   if the fourth p
146e0 61 72 61 6d 65 74 65 72 20 69 73 20 32 2c 20 74  arameter is 2, t
146f0 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65  hen.** the conne
14700 63 74 69 6f 6e 20 62 65 69 6e 67 20 70 61 73 73  ction being pass
14710 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
14720 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 62 65   parameter is be
14730 69 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a  ing closed. The.
14740 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  ** third paramet
14750 65 72 20 69 73 20 70 61 73 73 65 64 20 4e 55 4c  er is passed NUL
14760 4c 20 49 6e 20 74 68 69 73 20 63 61 73 65 2e 20  L In this case. 
14770 20 41 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 75   An example of u
14780 73 69 6e 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e  sing this.** con
14790 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
147a0 6e 20 63 61 6e 20 62 65 20 73 65 65 6e 20 69 6e  n can be seen in
147b0 20 74 68 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f   the "test_sqllo
147c0 67 2e 63 22 20 73 6f 75 72 63 65 20 66 69 6c 65  g.c" source file
147d0 20 69 6e 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e   in.** the canon
147e0 69 63 61 6c 20 53 51 4c 69 74 65 20 73 6f 75 72  ical SQLite sour
147f0 63 65 20 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a  ce tree.</dd>.**
14800 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
14810 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a  FIG_MMAP_SIZE]].
14820 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
14830 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a  NFIG_MMAP_SIZE.*
14840 2a 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f  * <dd>^SQLITE_CO
14850 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74  NFIG_MMAP_SIZE t
14860 61 6b 65 73 20 74 77 6f 20 36 34 2d 62 69 74 20  akes two 64-bit 
14870 69 6e 74 65 67 65 72 20 28 73 71 6c 69 74 65 33  integer (sqlite3
14880 5f 69 6e 74 36 34 29 20 76 61 6c 75 65 73 0a 2a  _int64) values.*
14890 2a 20 74 68 61 74 20 61 72 65 20 74 68 65 20 64  * that are the d
148a0 65 66 61 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65  efault mmap size
148b0 20 6c 69 6d 69 74 20 28 74 68 65 20 64 65 66 61   limit (the defa
148c0 75 6c 74 20 73 65 74 74 69 6e 67 20 66 6f 72 0a  ult setting for.
148d0 2a 2a 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f  ** [PRAGMA mmap_
148e0 73 69 7a 65 5d 29 20 61 6e 64 20 74 68 65 20 6d  size]) and the m
148f0 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d  aximum allowed m
14900 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a  map size limit..
14910 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
14920 73 65 74 74 69 6e 67 20 63 61 6e 20 62 65 20 6f  setting can be o
14930 76 65 72 72 69 64 64 65 6e 20 62 79 20 65 61 63  verridden by eac
14940 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  h database conne
14950 63 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65  ction using.** e
14960 69 74 68 65 72 20 74 68 65 20 5b 50 52 41 47 4d  ither the [PRAGM
14970 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d  A mmap_size] com
14980 6d 61 6e 64 2c 20 6f 72 20 62 79 20 75 73 69 6e  mand, or by usin
14990 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  g the.** [SQLITE
149a0 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45  _FCNTL_MMAP_SIZE
149b0 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20  ] file control. 
149c0 20 5e 28 54 68 65 20 6d 61 78 69 6d 75 6d 20 61   ^(The maximum a
149d0 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65  llowed mmap size
149e0 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20 63 68  .** cannot be ch
149f0 61 6e 67 65 64 20 61 74 20 72 75 6e 2d 74 69 6d  anged at run-tim
14a00 65 2e 20 20 4e 6f 72 20 6d 61 79 20 74 68 65 20  e.  Nor may the 
14a10 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20  maximum allowed 
14a20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 65 78 63  mmap size.** exc
14a30 65 65 64 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d  eed the compile-
14a40 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d 6d 61  time maximum mma
14a50 70 20 73 69 7a 65 20 73 65 74 20 62 79 20 74 68  p size set by th
14a60 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58  e.** [SQLITE_MAX
14a70 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f 6d 70  _MMAP_SIZE] comp
14a80 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e  ile-time option.
14a90 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68 65 72  )^.** ^If either
14aa0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69   argument to thi
14ab0 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67 61  s option is nega
14ac0 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61 74 20  tive, then that 
14ad0 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 63  argument is.** c
14ae0 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20 63 6f  hanged to its co
14af0 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66 61 75  mpile-time defau
14b00 6c 74 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  lt..** </dl>.*/.
14b10 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
14b20 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
14b30 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f  AD  1  /* nil */
14b40 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
14b50 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
14b60 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a  AD   2  /* nil *
14b70 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
14b80 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
14b90 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20  ED    3  /* nil 
14ba0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
14bb0 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20  E_CONFIG_MALLOC 
14bc0 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c         4  /* sql
14bd0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
14be0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
14bf0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
14c00 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73  LLOC     5  /* s
14c10 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
14c20 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
14c30 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
14c40 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a  ATCH       6  /*
14c50 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20   void*, int sz, 
14c60 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65  int N */.#define
14c70 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
14c80 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20 20  AGECACHE     7  
14c90 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a  /* void*, int sz
14ca0 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69  , int N */.#defi
14cb0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
14cc0 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20 38  _HEAP          8
14cd0 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
14ce0 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a  nByte, int min *
14cf0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
14d00 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
14d10 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c  S     9  /* bool
14d20 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ean */.#define S
14d30 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
14d40 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a  EX        10  /*
14d50 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
14d60 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
14d70 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
14d80 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 31  _GETMUTEX     11
14d90 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74    /* sqlite3_mut
14da0 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f  ex_methods* */./
14db0 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c  * previously SQL
14dc0 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b  ITE_CONFIG_CHUNK
14dd0 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69  ALLOC 12 which i
14de0 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f  s now unused. */
14df0 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45   .#define SQLITE
14e00 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
14e10 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20  E    13  /* int 
14e20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
14e30 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
14e40 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a  CHE       14  /*
14e50 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e   no-op */.#defin
14e60 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14e70 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20  GETPCACHE    15 
14e80 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65   /* no-op */.#de
14e90 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
14ea0 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20  IG_LOG          
14eb0 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f  16  /* xFunc, vo
14ec0 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  id* */.#define S
14ed0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
14ee0 20 20 20 20 20 20 20 20 20 20 31 37 20 20 2f 2a            17  /*
14ef0 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
14f00 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
14f10 41 43 48 45 32 20 20 20 20 20 20 31 38 20 20 2f  ACHE2      18  /
14f20 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65  * sqlite3_pcache
14f30 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64  _methods2* */.#d
14f40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
14f50 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 20  FIG_GETPCACHE2  
14f60 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   19  /* sqlite3_
14f70 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a  pcache_methods2*
14f80 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
14f90 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49  TE_CONFIG_COVERI
14fa0 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32 30  NG_INDEX_SCAN 20
14fb0 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66    /* int */.#def
14fc0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
14fd0 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20 32  G_SQLLOG       2
14fe0 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76  1  /* xSqllog, v
14ff0 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  oid* */.#define 
15000 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d  SQLITE_CONFIG_MM
15010 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20 2f  AP_SIZE    22  /
15020 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c  * sqlite3_int64,
15030 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a   sqlite3_int64 *
15040 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
15050 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  F: Database Conn
15060 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61  ection Configura
15070 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a  tion Options.**.
15080 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
15090 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c  ts are the avail
150a0 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  able integer con
150b0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
150c0 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62  ns that.** can b
150d0 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
150e0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
150f0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
15100 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  db_config()] int
15110 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65  erface..**.** Ne
15120 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  w configuration 
15130 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61  options may be a
15140 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
15150 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
15160 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63  e..** Existing c
15170 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
15180 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69  ions might be di
15190 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70  scontinued.  App
151a0 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f  lications.** sho
151b0 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65  uld check the re
151c0 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b  turn code from [
151d0 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
151e0 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72  g()] to make sur
151f0 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61  e that.** the ca
15200 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65  ll worked.  ^The
15210 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
15220 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
15230 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a   will return a.*
15240 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  * non-zero [erro
15250 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73  r code] if a dis
15260 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73  continued or uns
15270 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75  upported configu
15280 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a  ration option.**
15290 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
152a0 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53  ** <dl>.** <dt>S
152b0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
152c0 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a  OOKASIDE</dt>.**
152d0 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
152e0 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 61  on takes three a
152f0 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
15300 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69  nts that determi
15310 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b  ne the .** [look
15320 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  aside memory all
15330 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72  ocator] configur
15340 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64  ation for the [d
15350 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
15360 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72  on]..** ^The fir
15370 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65  st argument (the
15380 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
15390 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f   to [sqlite3_db_
153a0 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a  config()] is a.*
153b0 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d  * pointer to a m
153c0 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20  emory buffer to 
153d0 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64  use for lookasid
153e0 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68  e memory..** ^Th
153f0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
15400 20 61 66 74 65 72 20 74 68 65 20 53 51 4c 49 54   after the SQLIT
15410 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
15420 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79  SIDE verb.** may
15430 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63   be NULL in whic
15440 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69  h case SQLite wi
15450 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a  ll allocate the.
15460 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ** lookaside buf
15470 66 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67  fer itself using
15480 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
15490 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ()]. ^The second
154a0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
154b0 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68  .** size of each
154c0 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
154d0 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68  r slot.  ^The th
154e0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
154f0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
15500 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a   slots.  The siz
15510 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20  e of the buffer 
15520 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
15530 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72  ument must be gr
15540 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72  eater than.** or
15550 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72   equal to the pr
15560 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63  oduct of the sec
15570 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72  ond and third ar
15580 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75  guments.  The bu
15590 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20  ffer.** must be 
155a0 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
155b0 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20  byte boundary.  
155c0 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61  ^If the second a
155d0 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51  rgument to.** SQ
155e0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
155f0 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61  OKASIDE is not a
15600 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20   multiple of 8, 
15610 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79  it is internally
15620 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e  .** rounded down
15630 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61   to the next sma
15640 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66  ller multiple of
15650 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61   8.  ^(The looka
15660 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63  side memory.** c
15670 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72  onfiguration for
15680 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
15690 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20  ection can only 
156a0 62 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20  be changed when 
156b0 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  that.** connecti
156c0 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e  on is not curren
156d0 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73  tly using lookas
156e0 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69  ide memory, or i
156f0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a  n other words.**
15700 20 77 68 65 6e 20 74 68 65 20 22 63 75 72 72 65   when the "curre
15710 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e  nt value" return
15720 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
15730 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b  3_db_status](D,[
15740 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
15750 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73  OKASIDE],...) is
15760 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74   zero..** Any at
15770 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20  tempt to change 
15780 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  the lookaside me
15790 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69  mory configurati
157a0 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64  on when lookasid
157b0 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69  e.** memory is i
157c0 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74 68 65  n use leaves the
157d0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75   configuration u
157e0 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74  nchanged and ret
157f0 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  urns .** [SQLITE
15800 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a  _BUSY].)^</dd>.*
15810 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
15820 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
15830 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  FKEY</dt>.** <dd
15840 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69  > ^This option i
15850 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65  s used to enable
15860 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20   or disable the 
15870 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a  enforcement of.*
15880 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63  * [foreign key c
15890 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68  onstraints].  Th
158a0 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77  ere should be tw
158b0 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  o additional arg
158c0 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66  uments..** The f
158d0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
158e0 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
158f0 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  h is 0 to disabl
15900 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
15910 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f  ,.** positive to
15920 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72   enable FK enfor
15930 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69  cement or negati
15940 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65  ve to leave FK e
15950 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e  nforcement.** un
15960 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65  changed.  The se
15970 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
15980 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
15990 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77  n integer into w
159a0 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74  hich.** is writt
159b0 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64  en 0 or 1 to ind
159c0 69 63 61 74 65 20 77 68 65 74 68 65 72 20 46 4b  icate whether FK
159d0 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20   enforcement is 
159e0 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c  off or on.** fol
159f0 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c  lowing this call
15a00 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
15a10 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61  rameter may be a
15a20 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69   NULL pointer, i
15a30 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20  n.** which case 
15a40 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  the FK enforceme
15a50 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f  nt setting is no
15a60 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e  t reported back.
15a70 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74   </dd>.**.** <dt
15a80 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
15a90 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c  _ENABLE_TRIGGER<
15aa0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
15ab0 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  is option is use
15ac0 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64  d to enable or d
15ad0 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54  isable [CREATE T
15ae0 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72  RIGGER | trigger
15af0 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f  s]..** There sho
15b00 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74  uld be two addit
15b10 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e  ional arguments.
15b20 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
15b30 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74  gument is an int
15b40 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20  eger which is 0 
15b50 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67 67  to disable trigg
15b60 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65  ers,.** positive
15b70 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67   to enable trigg
15b80 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ers or negative 
15b90 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74  to leave the set
15ba0 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a  ting unchanged..
15bb0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  ** The second pa
15bc0 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
15bd0 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
15be0 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
15bf0 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
15c00 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
15c10 68 65 74 68 65 72 20 74 72 69 67 67 65 72 73 20  hether triggers 
15c20 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20  are disabled or 
15c30 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f  enabled.** follo
15c40 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20  wing this call. 
15c50 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
15c60 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e  meter may be a N
15c70 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a  ULL pointer, in.
15c80 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68  ** which case th
15c90 65 20 74 72 69 67 67 65 72 20 73 65 74 74 69 6e  e trigger settin
15ca0 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65  g is not reporte
15cb0 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a  d back. </dd>.**
15cc0 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
15cd0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
15ce0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20  NFIG_LOOKASIDE  
15cf0 20 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f       1001  /* vo
15d00 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23  id* int int */.#
15d10 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
15d20 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b  CONFIG_ENABLE_FK
15d30 45 59 20 20 20 20 20 31 30 30 32 20 20 2f 2a 20  EY     1002  /* 
15d40 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66  int int* */.#def
15d50 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
15d60 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47  FIG_ENABLE_TRIGG
15d70 45 52 20 20 31 30 30 33 20 20 2f 2a 20 69 6e 74  ER  1003  /* int
15d80 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a   int* */.../*.**
15d90 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c   CAPI3REF: Enabl
15da0 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74  e Or Disable Ext
15db0 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64  ended Result Cod
15dc0 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  es.**.** ^The sq
15dd0 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
15de0 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f  esult_codes() ro
15df0 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72  utine enables or
15e00 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a   disables the.**
15e10 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
15e20 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65  t codes] feature
15e30 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65   of SQLite. ^The
15e40 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
15e50 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69  .** codes are di
15e60 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
15e70 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c  t for historical
15e80 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
15e90 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
15ea0 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
15eb0 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69  odes(sqlite3*, i
15ec0 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a  nt onoff);../*.*
15ed0 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74  * CAPI3REF: Last
15ee0 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a   Insert Rowid.**
15ef0 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20  .** ^Each entry 
15f00 69 6e 20 61 6e 20 53 51 4c 69 74 65 20 74 61 62  in an SQLite tab
15f10 6c 65 20 68 61 73 20 61 20 75 6e 69 71 75 65 20  le has a unique 
15f20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a  64-bit signed.**
15f30 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c   integer key cal
15f40 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c  led the [ROWID |
15f50 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20   "rowid"]. ^The 
15f60 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20  rowid is always 
15f70 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20  available.** as 
15f80 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f  an undeclared co
15f90 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44  lumn named ROWID
15fa0 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44  , OID, or _ROWID
15fb0 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f  _ as long as tho
15fc0 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20  se.** names are 
15fd0 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79  not also used by
15fe0 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c   explicitly decl
15ff0 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49  ared columns. ^I
16000 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68  f.** the table h
16010 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  as a column of t
16020 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49  ype [INTEGER PRI
16030 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74  MARY KEY] then t
16040 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  hat column.** is
16050 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66   another alias f
16060 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a  or the rowid..**
16070 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
16080 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72  e returns the [r
16090 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73  owid] of the mos
160a0 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63  t recent.** succ
160b0 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20  essful [INSERT] 
160c0 69 6e 74 6f 20 61 20 72 6f 77 69 64 20 74 61 62  into a rowid tab
160d0 6c 65 20 66 72 6f 6d 20 74 68 65 20 5b 64 61 74  le from the [dat
160e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
160f0 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73  ].** in the firs
16100 74 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 41 73  t argument.  ^As
16110 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69   of SQLite versi
16120 6f 6e 20 33 2e 37 2e 37 2c 20 74 68 69 73 20 72  on 3.7.7, this r
16130 6f 75 74 69 6e 65 73 0a 2a 2a 20 72 65 63 6f 72  outines.** recor
16140 64 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65  ds the last inse
16150 72 74 20 72 6f 77 69 64 20 6f 66 20 62 6f 74 68  rt rowid of both
16160 20 6f 72 64 69 6e 61 72 79 20 74 61 62 6c 65 73   ordinary tables
16170 20 61 6e 64 20 5b 76 69 72 74 75 61 6c 20 74 61   and [virtual ta
16180 62 6c 65 73 5d 2e 0a 2a 2a 20 5e 49 6e 73 65 72  bles]..** ^Inser
16190 74 73 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54  ts into [WITHOUT
161a0 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 20 61   ROWID] tables a
161b0 72 65 20 6e 6f 74 20 72 65 63 6f 72 64 65 64 2e  re not recorded.
161c0 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63 65  .** ^If no succe
161d0 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20  ssful [INSERT]s 
161e0 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65  into rowid table
161f0 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f  s.** have ever o
16200 63 63 75 72 72 65 64 20 6f 6e 20 74 68 65 20 64  ccurred on the d
16210 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
16220 6f 6e 20 44 2c 20 0a 2a 2a 20 74 68 65 6e 20 73  on D, .** then s
16230 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
16240 72 74 5f 72 6f 77 69 64 28 44 29 20 72 65 74 75  rt_rowid(D) retu
16250 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20  rns zero..**.** 
16260 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d  ^(If an [INSERT]
16270 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
16280 20 74 72 69 67 67 65 72 20 6f 72 20 77 69 74 68   trigger or with
16290 69 6e 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61  in a [virtual ta
162a0 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20  ble].** method, 
162b0 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e  then this routin
162c0 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68  e will return th
162d0 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65  e [rowid] of the
162e0 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77   inserted.** row
162f0 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20   as long as the 
16300 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75  trigger or virtu
16310 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20  al table method 
16320 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42  is running..** B
16330 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67  ut once the trig
16340 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74  ger or virtual t
16350 61 62 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64 73  able method ends
16360 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  , the value retu
16370 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73  rned .** by this
16380 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73   routine reverts
16390 20 74 6f 20 77 68 61 74 20 69 74 20 77 61 73 20   to what it was 
163a0 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67  before the trigg
163b0 65 72 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a  er or virtual.**
163c0 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 62 65   table method be
163d0 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e  gan.)^.**.** ^An
163e0 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66   [INSERT] that f
163f0 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f  ails due to a co
16400 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
16410 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73  on is not a.** s
16420 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
16430 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20  T] and does not 
16440 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
16450 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
16460 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e  s.** routine.  ^
16470 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46  Thus INSERT OR F
16480 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49  AIL, INSERT OR I
16490 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52  GNORE, INSERT OR
164a0 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e   ROLLBACK,.** an
164b0 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52  d INSERT OR ABOR
164c0 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65  T make no change
164d0 73 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20  s to the return 
164e0 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a  value of this.**
164f0 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68   routine when th
16500 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61  eir insertion fa
16510 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53  ils.  ^(When INS
16520 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a  ERT OR REPLACE.*
16530 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63  * encounters a c
16540 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
16550 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74  ion, it does not
16560 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49   fail.  The.** I
16570 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20  NSERT continues 
16580 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66  to completion af
16590 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77  ter deleting row
165a0 73 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a  s that caused.**
165b0 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20   the constraint 
165c0 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52  problem so INSER
165d0 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c  T OR REPLACE wil
165e0 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a  l always change.
165f0 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ** the return va
16600 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65  lue of this inte
16610 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  rface.)^.**.** ^
16620 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73  For the purposes
16630 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
16640 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73  , an [INSERT] is
16650 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a   considered to.*
16660 2a 20 62 65 20 73 75 63 63 65 73 73 66 75 6c 20  * be successful 
16670 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 73 75  even if it is su
16680 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65  bsequently rolle
16690 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68  d back..**.** Th
166a0 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61  is function is a
166b0 63 63 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c  ccessible to SQL
166c0 20 73 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20   statements via 
166d0 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73  the.** [last_ins
166e0 65 72 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20  ert_rowid() SQL 
166f0 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
16700 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
16710 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61  hread performs a
16720 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e   new [INSERT] on
16730 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74   the same.** dat
16740 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
16750 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69   while the [sqli
16760 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
16770 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63  rowid()].** func
16780 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20  tion is running 
16790 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 73  and thus changes
167a0 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74   the last insert
167b0 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65   [rowid],.** the
167c0 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
167d0 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
167e0 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
167f0 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72  id()] is.** unpr
16800 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69  edictable and mi
16810 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69  ght not equal ei
16820 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20  ther the old or 
16830 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20  the new.** last 
16840 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a  insert [rowid]..
16850 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  */.sqlite3_int64
16860 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e   sqlite3_last_in
16870 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74  sert_rowid(sqlit
16880 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
16890 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65  I3REF: Count The
168a0 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20   Number Of Rows 
168b0 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e  Modified.**.** ^
168c0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
168d0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
168e0 20 6f 66 20 64 61 74 61 62 61 73 65 20 72 6f 77   of database row
168f0 73 20 74 68 61 74 20 77 65 72 65 20 63 68 61 6e  s that were chan
16900 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74  ged.** or insert
16910 65 64 20 6f 72 20 64 65 6c 65 74 65 64 20 62 79  ed or deleted by
16920 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
16930 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c  ly completed SQL
16940 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e   statement.** on
16950 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
16960 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69  onnection] speci
16970 66 69 65 64 20 62 79 20 74 68 65 20 66 69 72 73  fied by the firs
16980 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  t parameter..** 
16990 5e 28 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 74  ^(Only changes t
169a0 68 61 74 20 61 72 65 20 64 69 72 65 63 74 6c 79  hat are directly
169b0 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
169c0 65 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44  e [INSERT], [UPD
169d0 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c  ATE],.** or [DEL
169e0 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 20 61  ETE] statement a
169f0 72 65 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78  re counted.  Aux
16a00 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20 63  iliary changes c
16a10 61 75 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67  aused by.** trig
16a20 67 65 72 73 20 6f 72 20 5b 66 6f 72 65 69 67 6e  gers or [foreign
16a30 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72   key actions] ar
16a40 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 29 5e  e not counted.)^
16a50 20 55 73 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   Use the.** [sql
16a60 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
16a70 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 74  es()] function t
16a80 6f 20 66 69 6e 64 20 74 68 65 20 74 6f 74 61 6c  o find the total
16a90 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67   number of chang
16aa0 65 73 0a 2a 2a 20 69 6e 63 6c 75 64 69 6e 67 20  es.** including 
16ab0 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
16ac0 79 20 74 72 69 67 67 65 72 73 20 61 6e 64 20 66  y triggers and f
16ad0 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f  oreign key actio
16ae0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68 61 6e 67  ns..**.** ^Chang
16af0 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 61  es to a view tha
16b00 74 20 61 72 65 20 73 69 6d 75 6c 61 74 65 64 20  t are simulated 
16b10 62 79 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f  by an [INSTEAD O
16b20 46 20 74 72 69 67 67 65 72 5d 0a 2a 2a 20 61 72  F trigger].** ar
16b30 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 20  e not counted.  
16b40 4f 6e 6c 79 20 72 65 61 6c 20 74 61 62 6c 65 20  Only real table 
16b50 63 68 61 6e 67 65 73 20 61 72 65 20 63 6f 75 6e  changes are coun
16b60 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 20 22  ted..**.** ^(A "
16b70 72 6f 77 20 63 68 61 6e 67 65 22 20 69 73 20 61  row change" is a
16b80 20 63 68 61 6e 67 65 20 74 6f 20 61 20 73 69 6e   change to a sin
16b90 67 6c 65 20 72 6f 77 20 6f 66 20 61 20 73 69 6e  gle row of a sin
16ba0 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75  gle table.** cau
16bb0 73 65 64 20 62 79 20 61 6e 20 49 4e 53 45 52 54  sed by an INSERT
16bc0 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20 55 50 44  , DELETE, or UPD
16bd0 41 54 45 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  ATE statement.  
16be0 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20 61 72 65  Rows that.** are
16bf0 20 63 68 61 6e 67 65 64 20 61 73 20 73 69 64 65   changed as side
16c00 20 65 66 66 65 63 74 73 20 6f 66 20 5b 52 45 50   effects of [REP
16c10 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74  LACE] constraint
16c20 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20   resolution,.** 
16c30 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54 20  rollback, ABORT 
16c40 70 72 6f 63 65 73 73 69 6e 67 2c 20 5b 44 52 4f  processing, [DRO
16c50 50 20 54 41 42 4c 45 5d 2c 20 6f 72 20 62 79 20  P TABLE], or by 
16c60 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63  any other.** mec
16c70 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63  hanisms do not c
16c80 6f 75 6e 74 20 61 73 20 64 69 72 65 63 74 20 72  ount as direct r
16c90 6f 77 20 63 68 61 6e 67 65 73 2e 29 5e 0a 2a 2a  ow changes.)^.**
16ca0 0a 2a 2a 20 41 20 22 74 72 69 67 67 65 72 20 63  .** A "trigger c
16cb0 6f 6e 74 65 78 74 22 20 69 73 20 61 20 73 63 6f  ontext" is a sco
16cc0 70 65 20 6f 66 20 65 78 65 63 75 74 69 6f 6e 20  pe of execution 
16cd0 74 68 61 74 20 62 65 67 69 6e 73 20 61 6e 64 0a  that begins and.
16ce0 2a 2a 20 65 6e 64 73 20 77 69 74 68 20 74 68 65  ** ends with the
16cf0 20 73 63 72 69 70 74 20 6f 66 20 61 20 5b 43 52   script of a [CR
16d00 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74  EATE TRIGGER | t
16d10 72 69 67 67 65 72 5d 2e 20 0a 2a 2a 20 4d 6f 73  rigger]. .** Mos
16d20 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  t SQL statements
16d30 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75 61 74 65   are.** evaluate
16d40 64 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 79  d outside of any
16d50 20 74 72 69 67 67 65 72 2e 20 20 54 68 69 73 20   trigger.  This 
16d60 69 73 20 74 68 65 20 22 74 6f 70 20 6c 65 76 65  is the "top leve
16d70 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f  l".** trigger co
16d80 6e 74 65 78 74 2e 20 20 49 66 20 61 20 74 72 69  ntext.  If a tri
16d90 67 67 65 72 20 66 69 72 65 73 20 66 72 6f 6d 20  gger fires from 
16da0 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 61  the top level, a
16db0 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67 65 72 20  .** new trigger 
16dc0 63 6f 6e 74 65 78 74 20 69 73 20 65 6e 74 65 72  context is enter
16dd0 65 64 20 66 6f 72 20 74 68 65 20 64 75 72 61 74  ed for the durat
16de0 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f 6e 65 0a  ion of that one.
16df0 2a 2a 20 74 72 69 67 67 65 72 2e 20 20 53 75 62  ** trigger.  Sub
16e00 74 72 69 67 67 65 72 73 20 63 72 65 61 74 65 20  triggers create 
16e10 73 75 62 63 6f 6e 74 65 78 74 73 20 66 6f 72 20  subcontexts for 
16e20 74 68 65 69 72 20 64 75 72 61 74 69 6f 6e 2e 0a  their duration..
16e30 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 5b  **.** ^Calling [
16e40 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
16e50 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  or [sqlite3_step
16e60 28 29 5d 20 72 65 63 75 72 73 69 76 65 6c 79 20  ()] recursively 
16e70 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61  does.** not crea
16e80 74 65 20 61 20 6e 65 77 20 74 72 69 67 67 65 72  te a new trigger
16e90 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20   context..**.** 
16ea0 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72  ^This function r
16eb0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
16ec0 72 20 6f 66 20 64 69 72 65 63 74 20 72 6f 77 20  r of direct row 
16ed0 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a  changes in the.*
16ee0 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e  * most recent IN
16ef0 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
16f00 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
16f10 74 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  t within the sam
16f20 65 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e  e.** trigger con
16f30 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 75  text..**.** ^Thu
16f40 73 2c 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66  s, when called f
16f50 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65  rom the top leve
16f60 6c 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  l, this function
16f70 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20   returns the.** 
16f80 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65  number of change
16f90 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65  s in the most re
16fa0 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44  cent INSERT, UPD
16fb0 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a  ATE, or DELETE.*
16fc0 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f 63 63 75  * that also occu
16fd0 72 72 65 64 20 61 74 20 74 68 65 20 74 6f 70 20  rred at the top 
16fe0 6c 65 76 65 6c 2e 20 20 5e 28 57 69 74 68 69 6e  level.  ^(Within
16ff0 20 74 68 65 20 62 6f 64 79 20 6f 66 20 61 20 74   the body of a t
17000 72 69 67 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73  rigger,.** the s
17010 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
17020 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
17030 65 20 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64  e called to find
17040 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
17050 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65  * changes in the
17060 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63   most recently c
17070 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c  ompleted INSERT,
17080 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
17090 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  TE.** statement 
170a0 77 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20  within the body 
170b0 6f 66 20 74 68 65 20 73 61 6d 65 20 74 72 69 67  of the same trig
170c0 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c  ger..** However,
170d0 20 74 68 65 20 6e 75 6d 62 65 72 20 72 65 74 75   the number retu
170e0 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e  rned does not in
170f0 63 6c 75 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a  clude changes.**
17100 20 63 61 75 73 65 64 20 62 79 20 73 75 62 74 72   caused by subtr
17110 69 67 67 65 72 73 20 73 69 6e 63 65 20 74 68 6f  iggers since tho
17120 73 65 20 68 61 76 65 20 74 68 65 69 72 20 6f 77  se have their ow
17130 6e 20 63 6f 6e 74 65 78 74 2e 29 5e 0a 2a 2a 0a  n context.)^.**.
17140 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20  ** See also the 
17150 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
17160 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66  hanges()] interf
17170 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75  ace, the.** [cou
17180 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d  nt_changes pragm
17190 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63 68 61  a], and the [cha
171a0 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74  nges() SQL funct
171b0 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  ion]..**.** If a
171c0 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
171d0 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f   makes changes o
171e0 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  n the same datab
171f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
17200 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  * while [sqlite3
17210 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72  _changes()] is r
17220 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20  unning then the 
17230 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a  value returned.*
17240 2a 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62  * is unpredictab
17250 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69  le and not meani
17260 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ngful..*/.int sq
17270 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71  lite3_changes(sq
17280 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
17290 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20  CAPI3REF: Total 
172a0 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d  Number Of Rows M
172b0 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54  odified.**.** ^T
172c0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
172d0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
172e0 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63  of row changes c
172f0 61 75 73 65 64 20 62 79 20 5b 49 4e 53 45 52 54  aused by [INSERT
17300 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 20 6f  ],.** [UPDATE] o
17310 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65  r [DELETE] state
17320 6d 65 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20  ments since the 
17330 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
17340 74 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64  tion] was opened
17350 2e 0a 2a 2a 20 5e 28 54 68 65 20 63 6f 75 6e 74  ..** ^(The count
17360 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
17370 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
17380 65 73 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c  es() includes al
17390 6c 20 63 68 61 6e 67 65 73 0a 2a 2a 20 66 72 6f  l changes.** fro
173a0 6d 20 61 6c 6c 20 5b 43 52 45 41 54 45 20 54 52  m all [CREATE TR
173b0 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d  IGGER | trigger]
173c0 20 63 6f 6e 74 65 78 74 73 20 61 6e 64 20 63 68   contexts and ch
173d0 61 6e 67 65 73 20 6d 61 64 65 20 62 79 0a 2a 2a  anges made by.**
173e0 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63   [foreign key ac
173f0 74 69 6f 6e 73 5d 2e 20 48 6f 77 65 76 65 72 2c  tions]. However,
17400 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74 20 64 6f  .** the count do
17410 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63  es not include c
17420 68 61 6e 67 65 73 20 75 73 65 64 20 74 6f 20 69  hanges used to i
17430 6d 70 6c 65 6d 65 6e 74 20 5b 52 45 50 4c 41 43  mplement [REPLAC
17440 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a  E] constraints,.
17450 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20  ** do rollbacks 
17460 6f 72 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73  or ABORT process
17470 69 6e 67 2c 20 6f 72 20 5b 44 52 4f 50 20 54 41  ing, or [DROP TA
17480 42 4c 45 5d 20 70 72 6f 63 65 73 73 69 6e 67 2e  BLE] processing.
17490 20 20 54 68 65 0a 2a 2a 20 63 6f 75 6e 74 20 64    The.** count d
174a0 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
174b0 72 6f 77 73 20 6f 66 20 76 69 65 77 73 20 74 68  rows of views th
174c0 61 74 20 66 69 72 65 20 61 6e 20 5b 49 4e 53 54  at fire an [INST
174d0 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 2c  EAD OF trigger],
174e0 0a 2a 2a 20 74 68 6f 75 67 68 20 69 66 20 74 68  .** though if th
174f0 65 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69  e INSTEAD OF tri
17500 67 67 65 72 20 6d 61 6b 65 73 20 63 68 61 6e 67  gger makes chang
17510 65 73 20 6f 66 20 69 74 73 20 6f 77 6e 2c 20 74  es of its own, t
17520 68 6f 73 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a  hose changes .**
17530 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 29 5e 0a   are counted.)^.
17540 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
17550 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20  total_changes() 
17560 66 75 6e 63 74 69 6f 6e 20 63 6f 75 6e 74 73 20  function counts 
17570 74 68 65 20 63 68 61 6e 67 65 73 20 61 73 20 73  the changes as s
17580 6f 6f 6e 20 61 73 0a 2a 2a 20 74 68 65 20 73 74  oon as.** the st
17590 61 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b  atement that mak
175a0 65 73 20 74 68 65 6d 20 69 73 20 63 6f 6d 70 6c  es them is compl
175b0 65 74 65 64 20 28 77 68 65 6e 20 74 68 65 20 73  eted (when the s
175c0 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 0a  tatement handle.
175d0 2a 2a 20 69 73 20 70 61 73 73 65 64 20 74 6f 20  ** is passed to 
175e0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
175f0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
17600 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a  nalize()])..**.*
17610 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
17620 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
17630 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  )] interface, th
17640 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e  e.** [count_chan
17650 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64  ges pragma], and
17660 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e   the [total_chan
17670 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69  ges() SQL functi
17680 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  on]..**.** If a 
17690 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
176a0 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e  makes changes on
176b0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
176c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
176d0 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f   while [sqlite3_
176e0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
176f0 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
17700 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65   the value.** re
17710 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64  turned is unpred
17720 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20  ictable and not 
17730 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69  meaningful..*/.i
17740 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  nt sqlite3_total
17750 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33  _changes(sqlite3
17760 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
17770 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41  REF: Interrupt A
17780 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75   Long-Running Qu
17790 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ery.**.** ^This 
177a0 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20  function causes 
177b0 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61  any pending data
177c0 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74  base operation t
177d0 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72  o abort and.** r
177e0 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72  eturn at its ear
177f0 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74  liest opportunit
17800 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  y. This routine 
17810 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20  is typically.** 
17820 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e  called in respon
17830 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74  se to a user act
17840 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73  ion such as pres
17850 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a  sing "Cancel".**
17860 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65   or Ctrl-C where
17870 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20   the user wants 
17880 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65  a long query ope
17890 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a  ration to halt.*
178a0 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a  * immediately..*
178b0 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65  *.** ^It is safe
178c0 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
178d0 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72  utine from a thr
178e0 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72  ead different fr
178f0 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64  om the.** thread
17900 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74   that is current
17910 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64  ly running the d
17920 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f  atabase operatio
17930 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73  n.  But it.** is
17940 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c   not safe to cal
17950 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  l this routine w
17960 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20  ith a [database 
17970 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74  connection] that
17980 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72  .** is closed or
17990 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66   might close bef
179a0 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  ore sqlite3_inte
179b0 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e  rrupt() returns.
179c0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51  .**.** ^If an SQ
179d0 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76  L operation is v
179e0 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73  ery nearly finis
179f0 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20  hed at the time 
17a00 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  when.** sqlite3_
17a10 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63  interrupt() is c
17a20 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d  alled, then it m
17a30 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e  ight not have an
17a40 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20   opportunity.** 
17a50 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65  to be interrupte
17a60 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74  d and might cont
17a70 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69  inue to completi
17a80 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51  on..**.** ^An SQ
17a90 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74  L operation that
17aa0 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20   is interrupted 
17ab0 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
17ac0 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a  ITE_INTERRUPT]..
17ad0 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72  ** ^If the inter
17ae0 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61  rupted SQL opera
17af0 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52  tion is an INSER
17b00 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
17b10 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20  LETE.** that is 
17b20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63  inside an explic
17b30 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20  it transaction, 
17b40 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20  then the entire 
17b50 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77  transaction.** w
17b60 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61  ill be rolled ba
17b70 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ck automatically
17b80 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
17b90 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44  ite3_interrupt(D
17ba0 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66  ) call is in eff
17bb0 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75  ect until all cu
17bc0 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a  rrently running.
17bd0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
17be0 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  s on [database c
17bf0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d  onnection] D com
17c00 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77  plete.  ^Any new
17c10 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
17c20 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
17c30 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71  ted after the sq
17c40 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
17c50 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72  ) call and befor
17c60 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e  e the .** runnin
17c70 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61  g statements rea
17c80 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e  ches zero are in
17c90 74 65 72 72 75 70 74 65 64 20 61 73 20 69 66 20  terrupted as if 
17ca0 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a  they had been.**
17cb0 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74   running prior t
17cc0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  o the sqlite3_in
17cd0 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20  terrupt() call. 
17ce0 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d   ^New SQL statem
17cf0 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
17d00 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
17d10 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65  he running state
17d20 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68  ment count reach
17d30 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e  es zero are.** n
17d40 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 20 74  ot effected by t
17d50 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
17d60 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61  rupt()..** ^A ca
17d70 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ll to sqlite3_in
17d80 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74 20  terrupt(D) that 
17d90 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 72  occurs when ther
17da0 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67  e are no running
17db0 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
17dc0 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e  ts is a no-op an
17dd0 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20  d has no effect 
17de0 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  on SQL statement
17df0 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
17e00 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
17e10 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
17e20 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73  t() call returns
17e30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64  ..**.** If the d
17e40 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
17e50 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20  on closes while 
17e60 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75  [sqlite3_interru
17e70 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e  pt()].** is runn
17e80 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 69  ing then bad thi
17e90 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20  ngs will likely 
17ea0 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20  happen..*/.void 
17eb0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
17ec0 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  t(sqlite3*);../*
17ed0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
17ee0 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51  termine If An SQ
17ef0 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43  L Statement Is C
17f00 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68  omplete.**.** Th
17f10 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
17f20 20 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63   useful during c
17f30 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75  ommand-line inpu
17f40 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69  t to determine i
17f50 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  f the.** current
17f60 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20  ly entered text 
17f70 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20  seems to form a 
17f80 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61  complete SQL sta
17f90 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20  tement or.** if 
17fa0 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74  additional input
17fb0 20 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72   is needed befor
17fc0 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65  e sending the te
17fd0 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74  xt into.** SQLit
17fe0 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20  e for parsing.  
17ff0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
18000 72 65 74 75 72 6e 20 31 20 69 66 20 74 68 65 20  return 1 if the 
18010 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20  input string.** 
18020 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 20  appears to be a 
18030 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61  complete SQL sta
18040 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74  tement.  ^A stat
18050 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20  ement is judged 
18060 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  to be.** complet
18070 65 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74  e if it ends wit
18080 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f  h a semicolon to
18090 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ken and is not a
180a0 20 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20   prefix of a.** 
180b0 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41  well-formed CREA
180c0 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74 65  TE TRIGGER state
180d0 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f  ment.  ^Semicolo
180e0 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65  ns that are embe
180f0 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73  dded within.** s
18100 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f  tring literals o
18110 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66  r quoted identif
18120 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d  ier names or com
18130 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a  ments are not.**
18140 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b   independent tok
18150 65 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61  ens (they are pa
18160 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20  rt of the token 
18170 69 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72  in which they ar
18180 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61  e.** embedded) a
18190 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63  nd thus do not c
181a0 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d  ount as a statem
181b0 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ent terminator. 
181c0 20 5e 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20   ^Whitespace.** 
181d0 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61  and comments tha
181e0 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e  t follow the fin
181f0 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65  al semicolon are
18200 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20   ignored..**.** 
18210 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
18220 72 65 74 75 72 6e 20 30 20 69 66 20 74 68 65 20  return 0 if the 
18230 73 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63  statement is inc
18240 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a  omplete.  ^If a.
18250 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
18260 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e  tion fails, then
18270 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73   SQLITE_NOMEM is
18280 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
18290 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
182a0 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68   do not parse th
182b0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
182c0 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f   thus.** will no
182d0 74 20 64 65 74 65 63 74 20 73 79 6e 74 61 63 74  t detect syntact
182e0 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74  ically incorrect
182f0 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66   SQL..**.** ^(If
18300 20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20   SQLite has not 
18310 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64  been initialized
18320 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
18330 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72  initialize()] pr
18340 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b  ior .** to invok
18350 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  ing sqlite3_comp
18360 6c 65 74 65 31 36 28 29 20 74 68 65 6e 20 73 71  lete16() then sq
18370 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
18380 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
18390 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62   automatically b
183a0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  y sqlite3_comple
183b0 74 65 31 36 28 29 2e 20 20 49 66 20 74 68 61 74  te16().  If that
183c0 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
183d0 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74  fails,.** then t
183e0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
183f0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d  from sqlite3_com
18400 70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62  plete16() will b
18410 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65  e non-zero.** re
18420 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
18430 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69  her or not the i
18440 6e 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70  nput SQL is comp
18450 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  lete.)^.**.** Th
18460 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  e input to [sqli
18470 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20  te3_complete()] 
18480 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74  must be a zero-t
18490 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
184a0 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  -8 string..**.**
184b0 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73   The input to [s
184c0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
184d0 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a  6()] must be a z
184e0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
184f0 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  * UTF-16 string 
18500 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  in native byte o
18510 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  rder..*/.int sql
18520 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f  ite3_complete(co
18530 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a  nst char *sql);.
18540 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
18550 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69  lete16(const voi
18560 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  d *sql);../*.** 
18570 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74  CAPI3REF: Regist
18580 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f  er A Callback To
18590 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42   Handle SQLITE_B
185a0 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a 2a  USY Errors.**.**
185b0 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73   ^This routine s
185c0 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  ets a callback f
185d0 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d 69 67  unction that mig
185e0 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68  ht be invoked wh
185f0 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74  enever.** an att
18600 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20  empt is made to 
18610 6f 70 65 6e 20 61 20 64 61 74 61 62 61 73 65 20  open a database 
18620 74 61 62 6c 65 20 74 68 61 74 20 61 6e 6f 74 68  table that anoth
18630 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20  er thread.** or 
18640 70 72 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 6b  process has lock
18650 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
18660 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  e busy callback 
18670 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53  is NULL, then [S
18680 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b  QLITE_BUSY] or [
18690 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
186a0 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75  CKED].** is retu
186b0 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  rned immediately
186c0 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69   upon encounteri
186d0 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49  ng the lock.  ^I
186e0 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62  f the busy callb
186f0 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55  ack.** is not NU
18700 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c  LL, then the cal
18710 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20 69  lback might be i
18720 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20  nvoked with two 
18730 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  arguments..**.**
18740 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
18750 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73 79  ment to the busy
18760 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f   handler is a co
18770 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20  py of the void* 
18780 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a  pointer which.**
18790 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61 72   is the third ar
187a0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
187b0 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
187c0 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  .  ^The second a
187d0 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68  rgument to.** th
187e0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63  e busy handler c
187f0 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e  allback is the n
18800 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74  umber of times t
18810 68 61 74 20 74 68 65 20 62 75 73 79 20 68 61 6e  hat the busy han
18820 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e  dler has.** been
18830 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 69   invoked for thi
18840 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e  s locking event.
18850 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73    ^If the.** bus
18860 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  y callback retur
18870 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64  ns 0, then no ad
18880 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74  ditional attempt
18890 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a  s are made to.**
188a0 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61   access the data
188b0 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45  base and [SQLITE
188c0 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54  _BUSY] or [SQLIT
188d0 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
188e0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
188f0 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
18900 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  k returns non-ze
18910 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72  ro, then another
18920 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d   attempt.** is m
18930 61 64 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20  ade to open the 
18940 64 61 74 61 62 61 73 65 20 66 6f 72 20 72 65 61  database for rea
18950 64 69 6e 67 20 61 6e 64 20 74 68 65 20 63 79 63  ding and the cyc
18960 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a  le repeats..**.*
18970 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f  * The presence o
18980 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72  f a busy handler
18990 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e   does not guaran
189a0 74 65 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c  tee that it will
189b0 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77   be invoked.** w
189c0 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63  hen there is loc
189d0 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49  k contention. ^I
189e0 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69  f SQLite determi
189f0 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e  nes that invokin
18a00 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61  g the busy.** ha
18a10 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75  ndler could resu
18a20 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b  lt in a deadlock
18a30 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65  , it will go ahe
18a40 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53  ad and return [S
18a50 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f  QLITE_BUSY].** o
18a60 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
18a70 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61 64  BLOCKED] instead
18a80 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65   of invoking the
18a90 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a   busy handler..*
18aa0 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65  * Consider a sce
18ab0 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20  nario where one 
18ac0 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69  process is holdi
18ad0 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74  ng a read lock t
18ae0 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79  hat.** it is try
18af0 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  ing to promote t
18b00 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63  o a reserved loc
18b10 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e  k and.** a secon
18b20 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c  d process is hol
18b30 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20  ding a reserved 
18b40 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20  lock that it is 
18b50 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f  trying.** to pro
18b60 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75  mote to an exclu
18b70 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20  sive lock.  The 
18b80 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61  first process ca
18b90 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20  nnot proceed.** 
18ba0 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c  because it is bl
18bb0 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63  ocked by the sec
18bc0 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f  ond and the seco
18bd0 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f  nd process canno
18be0 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63  t.** proceed bec
18bf0 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b  ause it is block
18c00 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e  ed by the first.
18c10 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73    If both proces
18c20 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68  ses.** invoke th
18c30 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c  e busy handlers,
18c40 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61   neither will ma
18c50 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e  ke any progress.
18c60 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20    Therefore,.** 
18c70 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b  SQLite returns [
18c80 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72  SQLITE_BUSY] for
18c90 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   the first proce
18ca0 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20  ss, hoping that 
18cb0 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64  this.** will ind
18cc0 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72  uce the first pr
18cd0 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65  ocess to release
18ce0 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61   its read lock a
18cf0 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20  nd allow.** the 
18d00 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74  second process t
18d10 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a  o proceed..**.**
18d20 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 75   ^The default bu
18d30 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e  sy callback is N
18d40 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ULL..**.** ^The 
18d50 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 72  [SQLITE_BUSY] er
18d60 72 6f 72 20 69 73 20 63 6f 6e 76 65 72 74 65 64  ror is converted
18d70 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   to [SQLITE_IOER
18d80 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68  R_BLOCKED].** wh
18d90 65 6e 20 53 51 4c 69 74 65 20 69 73 20 69 6e 20  en SQLite is in 
18da0 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 61 20  the middle of a 
18db0 6c 61 72 67 65 20 74 72 61 6e 73 61 63 74 69 6f  large transactio
18dc0 6e 20 77 68 65 72 65 20 61 6c 6c 20 74 68 65 0a  n where all the.
18dd0 2a 2a 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20  ** changes will 
18de0 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20 74 68 65  not fit into the
18df0 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65   in-memory cache
18e00 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a  .  SQLite will.*
18e10 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c 64 20 61  * already hold a
18e20 20 52 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f   RESERVED lock o
18e30 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
18e40 69 6c 65 2c 20 62 75 74 20 69 74 20 6e 65 65 64  ile, but it need
18e50 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20  s.** to promote 
18e60 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43  this lock to EXC
18e70 4c 55 53 49 56 45 20 73 6f 20 74 68 61 74 20 69  LUSIVE so that i
18e80 74 20 63 61 6e 20 73 70 69 6c 6c 20 63 61 63 68  t can spill cach
18e90 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f 20  e.** pages into 
18ea0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
18eb0 65 20 77 69 74 68 6f 75 74 20 68 61 72 6d 20 74  e without harm t
18ec0 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20  o concurrent.** 
18ed0 72 65 61 64 65 72 73 2e 20 20 5e 49 66 20 69 74  readers.  ^If it
18ee0 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 70 72   is unable to pr
18ef0 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20  omote the lock, 
18f00 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f  then the in-memo
18f10 72 79 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c  ry.** cache will
18f20 20 62 65 20 6c 65 66 74 20 69 6e 20 61 6e 20 69   be left in an i
18f30 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73 74 61 74  nconsistent stat
18f40 65 20 61 6e 64 20 73 6f 20 74 68 65 20 65 72 72  e and so the err
18f50 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70 72  or.** code is pr
18f60 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68 65 20  omoted from the 
18f70 72 65 6c 61 74 69 76 65 6c 79 20 62 65 6e 69 67  relatively benig
18f80 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
18f90 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73  to.** the more s
18fa0 65 76 65 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f  evere [SQLITE_IO
18fb0 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 5e  ERR_BLOCKED].  ^
18fc0 54 68 69 73 20 65 72 72 6f 72 20 63 6f 64 65 20  This error code 
18fd0 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72  promotion.** for
18fe0 63 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 63  ces an automatic
18ff0 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65   rollback of the
19000 20 63 68 61 6e 67 65 73 2e 20 20 53 65 65 20 74   changes.  See t
19010 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f  he.** <a href="/
19020 63 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43  cvstrac/wiki?p=C
19030 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69  orruptionFollowi
19040 6e 67 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a  ngBusyError">.**
19050 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f   CorruptionFollo
19060 77 69 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f 61  wingBusyError</a
19070 3e 20 77 69 6b 69 20 70 61 67 65 20 66 6f 72 20  > wiki page for 
19080 61 20 64 69 73 63 75 73 73 69 6f 6e 20 6f 66 20  a discussion of 
19090 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 20 69  why.** this is i
190a0 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20  mportant..**.** 
190b0 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79  ^(There can only
190c0 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73   be a single bus
190d0 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65  y handler define
190e0 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64  d for each.** [d
190f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
19100 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20  on].  Setting a 
19110 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72  new busy handler
19120 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70   clears any.** p
19130 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61  reviously set ha
19140 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20  ndler.)^  ^Note 
19150 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71  that calling [sq
19160 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
19170 75 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c  ut()].** will al
19180 73 6f 20 73 65 74 20 6f 72 20 63 6c 65 61 72 20  so set or clear 
19190 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
191a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79  ..**.** The busy
191b0 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64   callback should
191c0 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63   not take any ac
191d0 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69  tions which modi
191e0 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  fy the.** databa
191f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
19200 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62  at invoked the b
19210 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 41 6e  usy handler.  An
19220 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a  y such actions.*
19230 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65  * result in unde
19240 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a  fined behavior..
19250 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61  ** .** A busy ha
19260 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63  ndler must not c
19270 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73  lose the databas
19280 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
19290 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  or [prepared sta
192a0 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76  tement] that inv
192b0 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61  oked the busy ha
192c0 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ndler..*/.int sq
192d0 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
192e0 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  er(sqlite3*, int
192f0 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20  (*)(void*,int), 
19300 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
19310 41 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42  API3REF: Set A B
19320 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a  usy Timeout.**.*
19330 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
19340 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f  sets a [sqlite3_
19350 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62  busy_handler | b
19360 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61  usy handler] tha
19370 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20  t sleeps.** for 
19380 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75  a specified amou
19390 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20  nt of time when 
193a0 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65  a table is locke
193b0 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72  d.  ^The handler
193c0 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d  .** will sleep m
193d0 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e  ultiple times un
193e0 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73  til at least "ms
193f0 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  " milliseconds o
19400 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61  f sleeping.** ha
19410 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20  ve accumulated. 
19420 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73 74   ^After at least
19430 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e   "ms" millisecon
19440 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a  ds of sleeping,.
19450 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72  ** the handler r
19460 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 63  eturns 0 which c
19470 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73  auses [sqlite3_s
19480 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e  tep()] to return
19490 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  .** [SQLITE_BUSY
194a0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  ] or [SQLITE_IOE
194b0 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a  RR_BLOCKED]..**.
194c0 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73  ** ^Calling this
194d0 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e   routine with an
194e0 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74   argument less t
194f0 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  han or equal to 
19500 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66  zero.** turns of
19510 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c  f all busy handl
19520 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ers..**.** ^(The
19530 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
19540 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
19550 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69  dler for a parti
19560 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61  cular.** [databa
19570 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
19580 6e 79 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d  ny any given mom
19590 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72  ent.  If another
195a0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a   busy handler.**
195b0 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 75   was defined  (u
195c0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75  sing [sqlite3_bu
195d0 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70  sy_handler()]) p
195e0 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a  rior to calling.
195f0 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c  ** this routine,
19600 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79   that other busy
19610 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61   handler is clea
19620 72 65 64 2e 29 5e 0a 2a 2f 0a 69 6e 74 20 73 71  red.)^.*/.int sq
19630 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
19640 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  ut(sqlite3*, int
19650 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50   ms);../*.** CAP
19660 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e  I3REF: Convenien
19670 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20  ce Routines For 
19680 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a  Running Queries.
19690 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20  **.** This is a 
196a0 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
196b0 20 74 68 61 74 20 69 73 20 70 72 65 73 65 72 76   that is preserv
196c0 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ed for backwards
196d0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
196e0 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20 69  ** Use of this i
196f0 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20  nterface is not 
19700 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a  recommended..**.
19710 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41  ** Definition: A
19720 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65   <b>result table
19730 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64  </b> is memory d
19740 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72  ata structure cr
19750 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  eated by the.** 
19760 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
19770 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  le()] interface.
19780 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65    A result table
19790 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20   records the.** 
197a0 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72  complete query r
197b0 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20  esults from one 
197c0 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e  or more queries.
197d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65  .**.** The table
197e0 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61   conceptually ha
197f0 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  s a number of ro
19800 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20  ws and columns. 
19810 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75   But.** these nu
19820 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61  mbers are not pa
19830 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  rt of the result
19840 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20   table itself.  
19850 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73  These.** numbers
19860 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65   are obtained se
19870 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e  parately.  Let N
19880 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   be the number o
19890 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20  f rows.** and M 
198a0 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
198b0 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20   columns..**.** 
198c0 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  A result table i
198d0 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
198e0 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74  inters to zero-t
198f0 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
19900 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72  strings..** Ther
19910 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c  e are (N+1)*M el
19920 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72  ements in the ar
19930 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20  ray.  The first 
19940 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74  M pointers point
19950 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d  .** to zero-term
19960 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74  inated strings t
19970 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65  hat  contain the
19980 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f   names of the co
19990 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65  lumns..** The re
199a0 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20  maining entries 
199b0 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65  all point to que
199c0 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c  ry results.  NUL
199d0 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a  L values result.
199e0 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74  ** in NULL point
199f0 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20  ers.  All other 
19a00 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68  values are in th
19a10 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74  eir UTF-8 zero-t
19a20 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72  erminated.** str
19a30 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69  ing representati
19a40 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62  on as returned b
19a50 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
19a60 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  n_text()]..**.**
19a70 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
19a80 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66  might consist of
19a90 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d   one or more mem
19aa0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e  ory allocations.
19ab0 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61  .** It is not sa
19ac0 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73  fe to pass a res
19ad0 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74  ult table direct
19ae0 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ly to [sqlite3_f
19af0 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73  ree()]..** A res
19b00 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64  ult table should
19b10 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
19b20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
19b30 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a  ree_table()]..**
19b40 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d  .** ^(As an exam
19b50 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c  ple of the resul
19b60 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20  t table format, 
19b70 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20  suppose a query 
19b80 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20  result.** is as 
19b90 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
19ba0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
19bb0 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20  .**        Name 
19bc0 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20         | Age.** 
19bd0 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d         ---------
19be0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a  --------------.*
19bf0 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20  *        Alice  
19c00 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20       | 43.**    
19c10 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20      Bob         
19c20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43  | 28.**        C
19c30 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a  indy       | 21.
19c40 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
19c50 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
19c60 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d  re are two colum
19c70 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72  n (M==2) and thr
19c80 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20  ee rows (N==3). 
19c90 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73   Thus the.** res
19ca0 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20  ult table has 8 
19cb0 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73  entries.  Suppos
19cc0 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  e the result tab
19cd0 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20  le is stored.** 
19ce0 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65  in an array name
19cf0 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65  s azResult.  The
19d00 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73  n azResult holds
19d10 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a   this content:.*
19d20 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
19d30 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20  ><pre>.**       
19d40 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d   azResult&#91;0]
19d50 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20   = "Name";.**   
19d60 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
19d70 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a  1;1] = "Age";.**
19d80 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
19d90 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65  &#91;2] = "Alice
19da0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
19db0 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22  esult&#91;3] = "
19dc0 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  43";.**        a
19dd0 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d  zResult&#91;4] =
19de0 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20   "Bob";.**      
19df0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35    azResult&#91;5
19e00 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20  ] = "28";.**    
19e10 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
19e20 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a  ;6] = "Cindy";.*
19e30 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
19e40 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b  t&#91;7] = "21";
19e50 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
19e60 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20  kquote>)^.**.** 
19e70 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74  ^The sqlite3_get
19e80 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f  _table() functio
19e90 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20  n evaluates one 
19ea0 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63  or more.** semic
19eb0 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53  olon-separated S
19ec0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e  QL statements in
19ed0 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   the zero-termin
19ee0 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74  ated UTF-8.** st
19ef0 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20  ring of its 2nd 
19f00 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65  parameter and re
19f10 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74  turns a result t
19f20 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70  able to the.** p
19f30 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20  ointer given in 
19f40 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65  its 3rd paramete
19f50 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74  r..**.** After t
19f60 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68  he application h
19f70 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
19f80 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
19f90 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
19fa0 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74  le(),.** it must
19fb0 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c 74   pass the result
19fc0 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74   table pointer t
19fd0 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74  o sqlite3_free_t
19fe0 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20  able() in order 
19ff0 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68  to.** release th
1a000 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61  e memory that wa
1a010 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63  s malloced.  Bec
1a020 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20  ause of the way 
1a030 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
1a040 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e  malloc()] happen
1a050 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33  s within sqlite3
1a060 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68  _get_table(), th
1a070 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e  e calling.** fun
1a080 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74  ction must not t
1a090 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69  ry to call [sqli
1a0a0 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65  te3_free()] dire
1a0b0 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b  ctly.  Only.** [
1a0c0 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
1a0d0 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f  le()] is able to
1a0e0 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d   release the mem
1a0f0 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64  ory properly and
1a100 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54   safely..**.** T
1a110 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
1a120 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  able() interface
1a130 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20   is implemented 
1a140 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f  as a wrapper aro
1a150 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  und.** [sqlite3_
1a160 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71  exec()].  The sq
1a170 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1a180 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e  ) routine does n
1a190 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a  ot have access.*
1a1a0 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61  * to any interna
1a1b0 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  l data structure
1a1c0 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74  s of SQLite.  It
1a1d0 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70   uses only the p
1a1e0 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61  ublic.** interfa
1a1f0 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e  ce defined here.
1a200 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e    As a consequen
1a210 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20  ce, errors that 
1a220 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20  occur in the.** 
1a230 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75  wrapper layer ou
1a240 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74  tside of the int
1a250 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65  ernal [sqlite3_e
1a260 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20  xec()] call are 
1a270 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64  not.** reflected
1a280 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63   in subsequent c
1a290 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
1a2a0 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a  _errcode()] or.*
1a2b0 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  * [sqlite3_errms
1a2c0 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  g()]..*/.int sql
1a2d0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a  ite3_get_table(.
1a2e0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
1a2f0 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70          /* An op
1a300 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20  en database */. 
1a310 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
1a320 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f  l,     /* SQL to
1a330 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
1a340 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65  .  char ***pazRe
1a350 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75  sult,    /* Resu
1a360 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79  lts of the query
1a370 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77   */.  int *pnRow
1a380 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e  ,           /* N
1a390 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20  umber of result 
1a3a0 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72  rows written her
1a3b0 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f  e */.  int *pnCo
1a3c0 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20  lumn,        /* 
1a3d0 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74  Number of result
1a3e0 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e   columns written
1a3f0 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20   here */.  char 
1a400 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20  **pzErrmsg      
1a410 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72   /* Error msg wr
1a420 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b  itten here */.);
1a430 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72  .void sqlite3_fr
1a440 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a  ee_table(char **
1a450 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  result);../*.** 
1a460 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74  CAPI3REF: Format
1a470 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74  ted String Print
1a480 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ing Functions.**
1a490 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1a4a0 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b  es are work-alik
1a4b0 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74  es of the "print
1a4c0 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66  f()" family of f
1a4d0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d  unctions.** from
1a4e0 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
1a4f0 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e  library..**.** ^
1a500 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  The sqlite3_mpri
1a510 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ntf() and sqlite
1a520 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75  3_vmprintf() rou
1a530 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65 69  tines write thei
1a540 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74  r.** results int
1a550 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
1a560 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
1a570 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68  malloc()]..** Th
1a580 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e  e strings return
1a590 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f 20  ed by these two 
1a5a0 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20  routines should 
1a5b0 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62  be.** released b
1a5c0 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  y [sqlite3_free(
1a5d0 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 69  )].  ^Both routi
1a5e0 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  nes return a.** 
1a5f0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20  NULL pointer if 
1a600 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1a610 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  )] is unable to 
1a620 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a  allocate enough.
1a630 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  ** memory to hol
1a640 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  d the resulting 
1a650 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28  string..**.** ^(
1a660 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  The sqlite3_snpr
1a670 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69  intf() routine i
1a680 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e  s similar to "sn
1a690 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a  printf()" from.*
1a6a0 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  * the standard C
1a6b0 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 72   library.  The r
1a6c0 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e  esult is written
1a6d0 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66   into the.** buf
1a6e0 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73 20  fer supplied as 
1a6f0 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
1a700 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20  eter whose size 
1a710 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74  is given by.** t
1a720 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
1a730 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68  er. Note that th
1a740 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a  e order of the.*
1a750 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 72 61  * first two para
1a760 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 72 73  meters is revers
1a770 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66  ed from snprintf
1a780 28 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61  ().)^  This is a
1a790 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20  n.** historical 
1a7a0 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 61  accident that ca
1a7b0 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 69  nnot be fixed wi
1a7c0 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a  thout breaking.*
1a7d0 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  * backwards comp
1a7e0 61 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f  atibility.  ^(No
1a7f0 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c  te also that sql
1a800 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
1a810 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ** returns a poi
1a820 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75 66 66  nter to its buff
1a830 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68  er instead of th
1a840 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63  e number of.** c
1a850 68 61 72 61 63 74 65 72 73 20 61 63 74 75 61 6c  haracters actual
1a860 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  ly written into 
1a870 74 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57  the buffer.)^  W
1a880 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20  e admit that.** 
1a890 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
1a8a0 61 72 61 63 74 65 72 73 20 77 72 69 74 74 65 6e  aracters written
1a8b0 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65   would be a more
1a8c0 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a   useful return.*
1a8d0 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 20 63  * value but we c
1a8e0 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  annot change the
1a8f0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
1a900 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  of sqlite3_snpri
1a910 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74  ntf().** now wit
1a920 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f  hout breaking co
1a930 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a  mpatibility..**.
1a940 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74  ** ^As long as t
1a950 68 65 20 62 75 66 66 65 72 20 73 69 7a 65 20 69  he buffer size i
1a960 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a  s greater than z
1a970 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70  ero, sqlite3_snp
1a980 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61  rintf().** guara
1a990 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 62  ntees that the b
1a9a0 75 66 66 65 72 20 69 73 20 61 6c 77 61 79 73 20  uffer is always 
1a9b0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e  zero-terminated.
1a9c0 20 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20    ^The first.** 
1a9d0 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73  parameter "n" is
1a9e0 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20   the total size 
1a9f0 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c 20 69  of the buffer, i
1aa00 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66  ncluding space f
1aa10 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74  or.** the zero t
1aa20 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74  erminator.  So t
1aa30 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e  he longest strin
1aa40 67 20 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f  g that can be co
1aa50 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74  mpletely.** writ
1aa60 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20  ten will be n-1 
1aa70 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a  characters..**.*
1aa80 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
1aa90 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  snprintf() routi
1aaa0 6e 65 20 69 73 20 61 20 76 61 72 61 72 67 73 20  ne is a varargs 
1aab0 76 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74  version of sqlit
1aac0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a  e3_snprintf()..*
1aad0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
1aae0 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e  nes all implemen
1aaf0 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61  t some additiona
1ab00 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20  l formatting.** 
1ab10 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65  options that are
1ab20 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73   useful for cons
1ab30 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61  tructing SQL sta
1ab40 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20  tements..** All 
1ab50 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70 72 69  of the usual pri
1ab60 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67  ntf() formatting
1ab70 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20   options apply. 
1ab80 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68   In addition, th
1ab90 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25  ere.** is are "%
1aba0 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22 25  q", "%Q", and "%
1abb0 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  z" options..**.*
1abc0 2a 20 5e 28 54 68 65 20 25 71 20 6f 70 74 69 6f  * ^(The %q optio
1abd0 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20  n works like %s 
1abe0 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73 74  in that it subst
1abf0 69 74 75 74 65 73 20 61 20 6e 75 6c 2d 74 65 72  itutes a nul-ter
1ac00 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e  minated.** strin
1ac10 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d  g from the argum
1ac20 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25  ent list.  But %
1ac30 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65  q also doubles e
1ac40 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 61 63  very '\'' charac
1ac50 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65  ter..** %q is de
1ac60 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69  signed for use i
1ac70 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c  nside a string l
1ac80 69 74 65 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f  iteral.)^  By do
1ac90 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27  ubling each '\''
1aca0 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69 74  .** character it
1acb0 20 65 73 63 61 70 65 73 20 74 68 61 74 20 63 68   escapes that ch
1acc0 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f  aracter and allo
1acd0 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65  ws it to be inse
1ace0 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65  rted into.** the
1acf0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46   string..**.** F
1ad00 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75  or example, assu
1ad10 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20 76 61  me the string va
1ad20 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e  riable zText con
1ad30 74 61 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f  tains text as fo
1ad40 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
1ad50 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1ad60 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d  *  char *zText =
1ad70 20 22 49 74 27 73 20 61 20 68 61 70 70 79 20 64   "It's a happy d
1ad80 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  ay!";.** </pre><
1ad90 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1ada0 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74  ** One can use t
1adb0 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53  his text in an S
1adc0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20  QL statement as 
1add0 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
1ade0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1adf0 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20  .**  char *zSQL 
1ae00 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  = sqlite3_mprint
1ae10 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  f("INSERT INTO t
1ae20 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27  able VALUES('%q'
1ae30 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20  )", zText);.**  
1ae40 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c  sqlite3_exec(db,
1ae50 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b   zSQL, 0, 0, 0);
1ae60 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65  .**  sqlite3_fre
1ae70 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72  e(zSQL);.** </pr
1ae80 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1ae90 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68  **.** Because th
1aea0 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69  e %q format stri
1aeb0 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 20  ng is used, the 
1aec0 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 20 69  '\'' character i
1aed0 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73  n zText.** is es
1aee0 63 61 70 65 64 20 61 6e 64 20 74 68 65 20 53 51  caped and the SQ
1aef0 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73 20 61  L generated is a
1af00 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
1af10 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1af20 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e  e>.**  INSERT IN
1af30 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53  TO table1 VALUES
1af40 28 27 49 74 27 27 73 20 61 20 68 61 70 70 79 20  ('It''s a happy 
1af50 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e  day!').** </pre>
1af60 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1af70 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72  .** This is corr
1af80 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 73 65  ect.  Had we use
1af90 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20  d %s instead of 
1afa0 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65  %q, the generate
1afb0 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68  d SQL.** would h
1afc0 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20  ave looked like 
1afd0 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  this:.**.** <blo
1afe0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1aff0 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61    INSERT INTO ta
1b000 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27  ble1 VALUES('It'
1b010 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29  s a happy day!')
1b020 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1b030 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
1b040 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70  his second examp
1b050 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e  le is an SQL syn
1b060 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61  tax error.  As a
1b070 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f   general rule yo
1b080 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61  u should.** alwa
1b090 79 73 20 75 73 65 20 25 71 20 69 6e 73 74 65 61  ys use %q instea
1b0a0 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73  d of %s when ins
1b0b0 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f  erting text into
1b0c0 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
1b0d0 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25  l..**.** ^(The %
1b0e0 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  Q option works l
1b0f0 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 69 74  ike %q except it
1b100 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c   also adds singl
1b110 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a  e quotes around.
1b120 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f  ** the outside o
1b130 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69  f the total stri
1b140 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c  ng.  Additionall
1b150 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  y, if the parame
1b160 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72  ter in the.** ar
1b170 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61  gument list is a
1b180 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25   NULL pointer, %
1b190 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74 68  Q substitutes th
1b1a0 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77  e text "NULL" (w
1b1b0 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65  ithout.** single
1b1c0 20 71 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c   quotes).)^  So,
1b1d0 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e   for example, on
1b1e0 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a  e could say:.**.
1b1f0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1b200 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
1b210 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70  SQL = sqlite3_mp
1b220 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e  rintf("INSERT IN
1b230 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28  TO table VALUES(
1b240 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a  %Q)", zText);.**
1b250 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64    sqlite3_exec(d
1b260 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30  b, zSQL, 0, 0, 0
1b270 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66  );.**  sqlite3_f
1b280 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f  ree(zSQL);.** </
1b290 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1b2a0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65  >.**.** The code
1b2b0 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64   above will rend
1b2c0 65 72 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c  er a correct SQL
1b2d0 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68   statement in th
1b2e0 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62  e zSQL.** variab
1b2f0 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a  le even if the z
1b300 54 65 78 74 20 76 61 72 69 61 62 6c 65 20 69 73  Text variable is
1b310 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
1b320 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a  .**.** ^(The "%z
1b330 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  " formatting opt
1b340 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22  ion works like "
1b350 25 73 22 20 62 75 74 20 77 69 74 68 20 74 68 65  %s" but with the
1b360 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61  .** addition tha
1b370 74 20 61 66 74 65 72 20 74 68 65 20 73 74 72 69  t after the stri
1b380 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65 61 64  ng has been read
1b390 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f   and copied into
1b3a0 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20  .** the result, 
1b3b0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1b3c0 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68   is called on th
1b3d0 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 29  e input string.)
1b3e0 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74  ^.*/.char *sqlit
1b3f0 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74  e3_mprintf(const
1b400 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61   char*,...);.cha
1b410 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69  r *sqlite3_vmpri
1b420 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ntf(const char*,
1b430 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20   va_list);.char 
1b440 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  *sqlite3_snprint
1b450 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73  f(int,char*,cons
1b460 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 63  t char*, ...);.c
1b470 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e  har *sqlite3_vsn
1b480 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a  printf(int,char*
1b490 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61  ,const char*, va
1b4a0 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _list);../*.** C
1b4b0 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
1b4c0 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79  Allocation Subsy
1b4d0 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  stem.**.** The S
1b4e0 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20  QLite core uses 
1b4f0 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74  these three rout
1b500 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20  ines for all of 
1b510 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72  its own.** inter
1b520 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  nal memory alloc
1b530 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f  ation needs. "Co
1b540 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 76 69  re" in the previ
1b550 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20  ous sentence.** 
1b560 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
1b570 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65   operating-syste
1b580 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 20 69  m specific VFS i
1b590 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20  mplementation.  
1b5a0 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56  The.** Windows V
1b5b0 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d  FS uses native m
1b5c0 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
1b5d0 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72  () for some oper
1b5e0 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ations..**.** ^T
1b5f0 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  he sqlite3_mallo
1b600 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  c() routine retu
1b610 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
1b620 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d   a block.** of m
1b630 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e  emory at least N
1b640 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68   bytes in length
1b650 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
1b660 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e   parameter..** ^
1b670 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  If sqlite3_mallo
1b680 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  c() is unable to
1b690 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 65   obtain sufficie
1b6a0 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72  nt free.** memor
1b6b0 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 20  y, it returns a 
1b6c0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e  NULL pointer.  ^
1b6d0 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  If the parameter
1b6e0 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33   N to.** sqlite3
1b6f0 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72  _malloc() is zer
1b700 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68  o or negative th
1b710 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  en sqlite3_mallo
1b720 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  c() returns.** a
1b730 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
1b740 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71  *.** ^Calling sq
1b750 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 74  lite3_free() wit
1b760 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76  h a pointer prev
1b770 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a  iously returned.
1b780 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61  ** by sqlite3_ma
1b790 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65  lloc() or sqlite
1b7a0 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65  3_realloc() rele
1b7b0 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79  ases that memory
1b7c0 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d   so.** that it m
1b7d0 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e 20  ight be reused. 
1b7e0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72   ^The sqlite3_fr
1b7f0 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a  ee() routine is.
1b800 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73  ** a no-op if is
1b810 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e   called with a N
1b820 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61  ULL pointer.  Pa
1b830 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69  ssing a NULL poi
1b840 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  nter.** to sqlit
1b850 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 72  e3_free() is har
1b860 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 65  mless.  After be
1b870 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72  ing freed, memor
1b880 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74  y.** should neit
1b890 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20  her be read nor 
1b8a0 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72  written.  Even r
1b8b0 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c  eading previousl
1b8c0 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72  y freed.** memor
1b8d0 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69  y might result i
1b8e0 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e  n a segmentation
1b8f0 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20   fault or other 
1b900 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a  severe error..**
1b910 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69   Memory corrupti
1b920 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69  on, a segmentati
1b930 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68  on fault, or oth
1b940 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a  er severe error.
1b950 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  ** might result 
1b960 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  if sqlite3_free(
1b970 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  ) is called with
1b980 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
1b990 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20  ter that.** was 
1b9a0 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  not obtained fro
1b9b0 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  m sqlite3_malloc
1b9c0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
1b9d0 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  alloc()..**.** ^
1b9e0 28 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61  (The sqlite3_rea
1b9f0 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66 61 63 65  lloc() interface
1ba00 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73   attempts to res
1ba10 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d  ize a.** prior m
1ba20 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1ba30 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20   to be at least 
1ba40 4e 20 62 79 74 65 73 2c 20 77 68 65 72 65 20 4e  N bytes, where N
1ba50 20 69 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e   is the.** secon
1ba60 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68  d parameter.  Th
1ba70 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
1ba80 69 6f 6e 20 74 6f 20 62 65 20 72 65 73 69 7a 65  ion to be resize
1ba90 64 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a  d is the first.*
1baa0 2a 20 70 61 72 61 6d 65 74 65 72 2e 29 5e 20 5e  * parameter.)^ ^
1bab0 20 49 66 20 74 68 65 20 66 69 72 73 74 20 70 61   If the first pa
1bac0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
1bad0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20  e3_realloc().** 
1bae0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
1baf0 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76  r then its behav
1bb00 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c  ior is identical
1bb10 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73   to calling.** s
1bb20 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29  qlite3_malloc(N)
1bb30 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
1bb40 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1bb50 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
1bb60 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 49 66 20 74 68  loc()..** ^If th
1bb70 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
1bb80 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
1bb90 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20  alloc() is zero 
1bba0 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74  or.** negative t
1bbb0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
1bbc0 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20   is exactly the 
1bbd0 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a  same as calling.
1bbe0 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ** sqlite3_free(
1bbf0 50 29 20 77 68 65 72 65 20 50 20 69 73 20 74 68  P) where P is th
1bc00 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
1bc10 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
1bc20 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c 69  lloc()..** ^sqli
1bc30 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65  te3_realloc() re
1bc40 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
1bc50 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  to a memory allo
1bc60 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20  cation.** of at 
1bc70 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e  least N bytes in
1bc80 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66   size or NULL if
1bc90 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f   sufficient memo
1bca0 72 79 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c  ry is unavailabl
1bcb0 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74  e..** ^If M is t
1bcc0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70  he size of the p
1bcd0 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c  rior allocation,
1bce0 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62   then min(N,M) b
1bcf0 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70  ytes.** of the p
1bd00 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
1bd10 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20  are copied into 
1bd20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
1bd30 20 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 64   buffer returned
1bd40 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72  .** by sqlite3_r
1bd50 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68 65  ealloc() and the
1bd60 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
1bd70 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e  n is freed..** ^
1bd80 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  If sqlite3_reall
1bd90 6f 63 28 29 20 72 65 74 75 72 6e 73 20 4e 55 4c  oc() returns NUL
1bda0 4c 2c 20 74 68 65 6e 20 74 68 65 20 70 72 69 6f  L, then the prio
1bdb0 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  r allocation.** 
1bdc0 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a  is not freed..**
1bdd0 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  .** ^The memory 
1bde0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
1bdf0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64  te3_malloc() and
1be00 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1be10 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20  ().** is always 
1be20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65  aligned to at le
1be30 61 73 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f  ast an 8 byte bo
1be40 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a  undary, or to a.
1be50 2a 2a 20 34 20 62 79 74 65 20 62 6f 75 6e 64 61  ** 4 byte bounda
1be60 72 79 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54  ry if the [SQLIT
1be70 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44  E_4_BYTE_ALIGNED
1be80 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65  _MALLOC] compile
1be90 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20  -time.** option 
1bea0 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  is used..**.** I
1beb0 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  n SQLite version
1bec0 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31   3.5.0 and 3.5.1
1bed0 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c  , it was possibl
1bee0 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74  e to define.** t
1bef0 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d  he SQLITE_OMIT_M
1bf00 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e  EMORY_ALLOCATION
1bf10 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75   which would cau
1bf20 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a  se the built-in.
1bf30 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
1bf40 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  n of these routi
1bf50 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65  nes to be omitte
1bf60 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 69 6c  d.  That capabil
1bf70 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e  ity.** is no lon
1bf80 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f  ger provided.  O
1bf90 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  nly built-in mem
1bfa0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63  ory allocators c
1bfb0 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a  an be used..**.*
1bfc0 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c 69 74  * Prior to SQLit
1bfd0 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 31 30  e version 3.7.10
1bfe0 2c 20 74 68 65 20 57 69 6e 64 6f 77 73 20 4f 53  , the Windows OS
1bff0 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
1c000 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68 65 20 73   called.** the s
1c010 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61  ystem malloc() a
1c020 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 63 74  nd free() direct
1c030 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69  ly when converti
1c040 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20  ng.** filenames 
1c050 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d  between the UTF-
1c060 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20  8 encoding used 
1c070 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64  by SQLite.** and
1c080 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61   whatever filena
1c090 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75  me encoding is u
1c0a0 73 65 64 20 62 79 20 74 68 65 20 70 61 72 74 69  sed by the parti
1c0b0 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a  cular Windows.**
1c0c0 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20   installation.  
1c0d0 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  Memory allocatio
1c0e0 6e 20 65 72 72 6f 72 73 20 77 65 72 65 20 64 65  n errors were de
1c0f0 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74  tected, but.** t
1c100 68 65 79 20 77 65 72 65 20 72 65 70 6f 72 74 65  hey were reporte
1c110 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54  d back as [SQLIT
1c120 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a  E_CANTOPEN] or.*
1c130 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d  * [SQLITE_IOERR]
1c140 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51   rather than [SQ
1c150 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a  LITE_NOMEM]..**.
1c160 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61  ** The pointer a
1c170 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c  rguments to [sql
1c180 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64  ite3_free()] and
1c190 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
1c1a0 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20  c()].** must be 
1c1b0 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65  either NULL or e
1c1c0 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74  lse pointers obt
1c1d0 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69  ained from a pri
1c1e0 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e  or.** invocation
1c1f0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   of [sqlite3_mal
1c200 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  loc()] or [sqlit
1c210 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68  e3_realloc()] th
1c220 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79  at have.** not y
1c230 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64  et been released
1c240 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ..**.** The appl
1c250 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
1c260 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 61   read or write a
1c270 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20  ny part of.** a 
1c280 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20  block of memory 
1c290 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65  after it has bee
1c2a0 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e 67  n released using
1c2b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
1c2c0 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  e()] or [sqlite3
1c2d0 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a  _realloc()]..*/.
1c2e0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61  void *sqlite3_ma
1c2f0 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20  lloc(int);.void 
1c300 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  *sqlite3_realloc
1c310 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f  (void*, int);.vo
1c320 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  id sqlite3_free(
1c330 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
1c340 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
1c350 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73  Allocator Statis
1c360 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  tics.**.** SQLit
1c370 65 20 70 72 6f 76 69 64 65 73 20 74 68 65 73 65  e provides these
1c380 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20   two interfaces 
1c390 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e  for reporting on
1c3a0 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f   the status.** o
1c3b0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
1c3c0 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74  alloc()], [sqlit
1c3d0 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20  e3_free()], and 
1c3e0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
1c3f0 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c  ()].** routines,
1c400 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20   which form the 
1c410 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
1c420 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79  allocation subsy
1c430 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  stem..**.** ^The
1c440 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1c450 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65  _used()] routine
1c460 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
1c470 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20  ber of bytes.** 
1c480 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e  of memory curren
1c490 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20  tly outstanding 
1c4a0 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f  (malloced but no
1c4b0 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68  t freed)..** ^Th
1c4c0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  e [sqlite3_memor
1c4d0 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 72  y_highwater()] r
1c4e0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
1c4f0 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61  he maximum.** va
1c500 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  lue of [sqlite3_
1c510 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73  memory_used()] s
1c520 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77 61  ince the high-wa
1c530 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20  ter mark.** was 
1c540 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54 68  last reset.  ^Th
1c550 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
1c560 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65  d by [sqlite3_me
1c570 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64  mory_used()] and
1c580 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  .** [sqlite3_mem
1c590 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
1c5a0 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65   include any ove
1c5b0 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 62  rhead.** added b
1c5c0 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20  y SQLite in its 
1c5d0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
1c5e0 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  f [sqlite3_mallo
1c5f0 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74  c()],.** but not
1c600 20 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 20   overhead added 
1c610 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72  by the any under
1c620 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62  lying system lib
1c630 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  rary.** routines
1c640 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d   that [sqlite3_m
1c650 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c  alloc()] may cal
1c660 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65  l..**.** ^The me
1c670 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72 20  mory high-water 
1c680 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f  mark is reset to
1c690 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c   the current val
1c6a0 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65  ue of.** [sqlite
1c6b0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
1c6c0 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20   if and only if 
1c6d0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  the parameter to
1c6e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  .** [sqlite3_mem
1c6f0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
1c700 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65 20   is true.  ^The 
1c710 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a  value returned.*
1c720 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65  * by [sqlite3_me
1c730 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 31  mory_highwater(1
1c740 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d 77  )] is the high-w
1c750 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69  ater mark.** pri
1c760 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e  or to the reset.
1c770 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  .*/.sqlite3_int6
1c780 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  4 sqlite3_memory
1c790 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c  _used(void);.sql
1c7a0 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
1c7b0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
1c7c0 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61  ter(int resetFla
1c7d0 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  g);../*.** CAPI3
1c7e0 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64  REF: Pseudo-Rand
1c7f0 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61  om Number Genera
1c800 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  tor.**.** SQLite
1c810 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68   contains a high
1c820 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d  -quality pseudo-
1c830 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65  random number ge
1c840 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75  nerator (PRNG) u
1c850 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74  sed to.** select
1c860 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c   random [ROWID |
1c870 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e   ROWIDs] when in
1c880 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f  serting new reco
1c890 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65  rds into a table
1c8a0 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79   that.** already
1c8b0 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73   uses the larges
1c8c0 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49  t possible [ROWI
1c8d0 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73  D].  The PRNG is
1c8e0 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a   also used for.*
1c8f0 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72  * the build-in r
1c900 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64  andom() and rand
1c910 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e  omblob() SQL fun
1c920 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e  ctions.  This in
1c930 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a  terface allows.*
1c940 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * applications t
1c950 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d  o access the sam
1c960 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72  e PRNG for other
1c970 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a   purposes..**.**
1c980 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73   ^A call to this
1c990 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20   routine stores 
1c9a0 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f  N bytes of rando
1c9b0 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65  mness into buffe
1c9c0 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  r P..**.** ^The 
1c9d0 66 69 72 73 74 20 74 69 6d 65 20 74 68 69 73 20  first time this 
1c9e0 72 6f 75 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b  routine is invok
1c9f0 65 64 20 28 65 69 74 68 65 72 20 69 6e 74 65 72  ed (either inter
1ca00 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74  nally or by.** t
1ca10 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 20  he application) 
1ca20 74 68 65 20 50 52 4e 47 20 69 73 20 73 65 65 64  the PRNG is seed
1ca30 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e  ed using randomn
1ca40 65 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20  ess obtained.** 
1ca50 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d  from the xRandom
1ca60 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 74  ness method of t
1ca70 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
1ca80 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
1ca90 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73 75 62 73  .** ^On all subs
1caa0 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f  equent invocatio
1cab0 6e 73 2c 20 74 68 65 20 70 73 65 75 64 6f 2d 72  ns, the pseudo-r
1cac0 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e  andomness is gen
1cad0 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e  erated.** intern
1cae0 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74  ally and without
1caf0 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65   recourse to the
1cb00 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78   [sqlite3_vfs] x
1cb10 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65  Randomness.** me
1cb20 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  thod..*/.void sq
1cb30 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73  lite3_randomness
1cb40 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29  (int N, void *P)
1cb50 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1cb60 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20  F: Compile-Time 
1cb70 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61  Authorization Ca
1cb80 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54  llbacks.**.** ^T
1cb90 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69  his routine regi
1cba0 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72 69  sters an authori
1cbb0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74  zer callback wit
1cbc0 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a  h a particular.*
1cbd0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
1cbe0 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65  ection], supplie
1cbf0 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  d in the first a
1cc00 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  rgument..** ^The
1cc10 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1cc20 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
1cc30 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  as SQL statement
1cc40 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70  s are being comp
1cc50 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69  iled.** by [sqli
1cc60 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
1cc70 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b  r its variants [
1cc80 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1cc90 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  v2()],.** [sqlit
1cca0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
1ccb0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
1ccc0 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e  pare16_v2()].  ^
1ccd0 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f  At various.** po
1cce0 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20  ints during the 
1ccf0 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63  compilation proc
1cd00 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73  ess, as logic is
1cd10 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a   being created.*
1cd20 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72  * to perform var
1cd30 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68  ious actions, th
1cd40 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1cd50 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
1cd60 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68   to.** see if th
1cd70 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20  ose actions are 
1cd80 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61  allowed.  ^The a
1cd90 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1cda0 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74  ck should.** ret
1cdb0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
1cdc0 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74  to allow the act
1cdd0 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e  ion, [SQLITE_IGN
1cde0 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77  ORE] to disallow
1cdf0 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63   the.** specific
1ce00 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f   action but allo
1ce10 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  w the SQL statem
1ce20 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20  ent to continue 
1ce30 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65  to be.** compile
1ce40 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45  d, or [SQLITE_DE
1ce50 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65  NY] to cause the
1ce60 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74   entire SQL stat
1ce70 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72  ement to be.** r
1ce80 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20  ejected with an 
1ce90 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20  error.  ^If the 
1cea0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1ceb0 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  ack returns.** a
1cec0 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74  ny value other t
1ced0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  han [SQLITE_IGNO
1cee0 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  RE], [SQLITE_OK]
1cef0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
1cf00 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b  Y].** then the [
1cf10 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1cf20 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
1cf30 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ent call that tr
1cf40 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61  iggered.** the a
1cf50 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66  uthorizer will f
1cf60 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ail with an erro
1cf70 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a  r message..**.**
1cf80 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61   When the callba
1cf90 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
1cfa0 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61  TE_OK], that mea
1cfb0 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  ns the operation
1cfc0 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 73  .** requested is
1cfd0 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20   ok.  ^When the 
1cfe0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1cff0 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20   [SQLITE_DENY], 
1d000 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
1d010 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
1d020 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c   equivalent call
1d030 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20   that triggered 
1d040 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65  the.** authorize
1d050 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68  r will fail with
1d060 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
1d070 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61  e explaining tha
1d080 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64  t.** access is d
1d090 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54  enied. .**.** ^T
1d0a0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
1d0b0 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  er to the author
1d0c0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
1d0d0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74   a copy of the t
1d0e0 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hird.** paramete
1d0f0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
1d100 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
1d110 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68  ) interface. ^Th
1d120 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
1d130 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c  er.** to the cal
1d140 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65  lback is an inte
1d150 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59  ger [SQLITE_COPY
1d160 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20   | action code] 
1d170 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a  that specifies.*
1d180 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  * the particular
1d190 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75   action to be au
1d1a0 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74  thorized. ^The t
1d1b0 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78  hird through six
1d1c0 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a  th parameters.**
1d1d0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
1d1e0 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   are zero-termin
1d1f0 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61  ated strings tha
1d200 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69  t contain additi
1d210 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20  onal.** details 
1d220 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e  about the action
1d230 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65   to be authorize
1d240 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
1d250 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20   action code is 
1d260 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a  [SQLITE_READ].**
1d270 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63   and the callbac
1d280 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
1d290 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74  E_IGNORE] then t
1d2a0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
1d2b0 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65  statement] state
1d2c0 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63  ment is construc
1d2d0 74 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 74  ted to substitut
1d2e0 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75  e.** a NULL valu
1d2f0 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68  e in place of th
1d300 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74  e table column t
1d310 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a  hat would have.*
1d320 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b  * been read if [
1d330 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62  SQLITE_OK] had b
1d340 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54  een returned.  T
1d350 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  he [SQLITE_IGNOR
1d360 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e  E].** return can
1d370 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79   be used to deny
1d380 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73   an untrusted us
1d390 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64  er access to ind
1d3a0 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d  ividual.** colum
1d3b0 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a  ns of a table..*
1d3c0 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e  * ^If the action
1d3d0 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45   code is [SQLITE
1d3e0 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65  _DELETE] and the
1d3f0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1d400 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e  s.** [SQLITE_IGN
1d410 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44  ORE] then the [D
1d420 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e  ELETE] operation
1d430 20 70 72 6f 63 65 65 64 73 20 62 75 74 20 74 68   proceeds but th
1d440 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f  e.** [truncate o
1d450 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20  ptimization] is 
1d460 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c  disabled and all
1d470 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65   rows are delete
1d480 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a  d individually..
1d490 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69  **.** An authori
1d4a0 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e  zer is used when
1d4b0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1d4c0 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a  e | preparing].*
1d4d0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
1d4e0 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74   from an untrust
1d4f0 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e  ed source, to en
1d500 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51  sure that the SQ
1d510 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
1d520 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63  do not try to ac
1d530 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61  cess data they a
1d540 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74  re not allowed t
1d550 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74  o see, or that t
1d560 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72  hey do not.** tr
1d570 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c  y to execute mal
1d580 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74  icious statement
1d590 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68  s that damage th
1d5a0 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72  e database.  For
1d5b0 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20  .** example, an 
1d5c0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20  application may 
1d5d0 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20  allow a user to 
1d5e0 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a  enter arbitrary.
1d5f0 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66  ** SQL queries f
1d600 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79  or evaluation by
1d610 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75   a database.  Bu
1d620 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
1d630 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61  n does.** not wa
1d640 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62  nt the user to b
1d650 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61  e able to make a
1d660 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73  rbitrary changes
1d670 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   to the.** datab
1d680 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69  ase.  An authori
1d690 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62  zer could then b
1d6a0 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77  e put in place w
1d6b0 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72  hile the.** user
1d6c0 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20  -entered SQL is 
1d6d0 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  being [sqlite3_p
1d6e0 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65  repare | prepare
1d6f0 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c  d] that.** disal
1d700 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20  lows everything 
1d710 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20  except [SELECT] 
1d720 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
1d730 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * Applications t
1d740 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63  hat need to proc
1d750 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74  ess SQL from unt
1d760 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a  rusted sources.*
1d770 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e  * might also con
1d780 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72  sider lowering r
1d790 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75  esource limits u
1d7a0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69  sing [sqlite3_li
1d7b0 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69  mit()].** and li
1d7c0 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  miting database 
1d7d0 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b  size using the [
1d7e0 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20  max_page_count] 
1d7f0 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61  [PRAGMA].** in a
1d800 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67  ddition to using
1d810 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a   an authorizer..
1d820 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73  **.** ^(Only a s
1d830 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72  ingle authorizer
1d840 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65   can be in place
1d850 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63   on a database c
1d860 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20  onnection.** at 
1d870 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61  a time.  Each ca
1d880 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65  ll to sqlite3_se
1d890 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65  t_authorizer ove
1d8a0 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72  rrides the.** pr
1d8b0 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20  evious call.)^  
1d8c0 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 74  ^Disable the aut
1d8d0 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61  horizer by insta
1d8e0 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c  lling a NULL cal
1d8f0 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75  lback..** The au
1d900 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61  thorizer is disa
1d910 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
1d920 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
1d930 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  rizer callback m
1d940 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
1d950 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
1d960 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
1d970 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1d980 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
1d990 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1d9a0 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  back..** Note th
1d9b0 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  at [sqlite3_prep
1d9c0 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
1d9d0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62  qlite3_step()] b
1d9e0 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72  oth modify their
1d9f0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
1da00 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
1da10 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
1da20 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
1da30 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57  agraph..**.** ^W
1da40 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hen [sqlite3_pre
1da50 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73  pare_v2()] is us
1da60 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 20  ed to prepare a 
1da70 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a  statement, the.*
1da80 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68  * statement migh
1da90 74 20 62 65 20 72 65 2d 70 72 65 70 61 72 65 64  t be re-prepared
1daa0 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33   during [sqlite3
1dab0 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20  _step()] due to 
1dac0 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61  a .** schema cha
1dad0 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65  nge.  Hence, the
1dae0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
1daf0 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74 20  uld ensure that 
1db00 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61  the.** correct a
1db10 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1db20 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c  ck remains in pl
1db30 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b  ace during the [
1db40 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
1db50 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61  .**.** ^Note tha
1db60 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  t the authorizer
1db70 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
1db80 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67  oked only during
1db90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
1dba0 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76  pare()] or its v
1dbb0 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72  ariants.  Author
1dbc0 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a  ization is not.*
1dbd0 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69  * performed duri
1dbe0 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61  ng statement eva
1dbf0 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69  luation in [sqli
1dc00 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c  te3_step()], unl
1dc10 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64  ess.** as stated
1dc20 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73   in the previous
1dc30 20 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69   paragraph, sqli
1dc40 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b  te3_step() invok
1dc50 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72  es.** sqlite3_pr
1dc60 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65  epare_v2() to re
1dc70 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d  prepare a statem
1dc80 65 6e 74 20 61 66 74 65 72 20 61 20 73 63 68 65  ent after a sche
1dc90 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e  ma change..*/.in
1dca0 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  t sqlite3_set_au
1dcb0 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69  thorizer(.  sqli
1dcc0 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41  te3*,.  int (*xA
1dcd0 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  uth)(void*,int,c
1dce0 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
1dcf0 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
1dd00 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  r*,const char*),
1dd10 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61  .  void *pUserDa
1dd20 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ta.);../*.** CAP
1dd30 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
1dd40 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a  r Return Codes.*
1dd50 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
1dd60 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1dd70 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61   | authorizer ca
1dd80 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d  llback function]
1dd90 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20   must.** return 
1dda0 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f  either [SQLITE_O
1ddb0 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65  K] or one of the
1ddc0 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73  se two constants
1ddd0 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20   in order.** to 
1dde0 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68  signal SQLite wh
1ddf0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
1de00 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69   action is permi
1de10 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a  tted.  See the.*
1de20 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  * [sqlite3_set_a
1de30 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68  uthorizer | auth
1de40 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61  orizer documenta
1de50 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69  tion] for additi
1de60 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
1de70 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ion..**.** Note 
1de80 74 68 61 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f  that SQLITE_IGNO
1de90 52 45 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20  RE is also used 
1dea0 61 73 20 61 20 5b 53 51 4c 49 54 45 5f 52 4f 4c  as a [SQLITE_ROL
1deb0 4c 42 41 43 4b 20 7c 20 72 65 74 75 72 6e 20 63  LBACK | return c
1dec0 6f 64 65 5d 0a 2a 2a 20 66 72 6f 6d 20 74 68 65  ode].** from the
1ded0 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f   [sqlite3_vtab_o
1dee0 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e  n_conflict()] in
1def0 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66  terface..*/.#def
1df00 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20  ine SQLITE_DENY 
1df10 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74    1   /* Abort t
1df20 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
1df30 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a   with an error *
1df40 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1df50 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44  _IGNORE 2   /* D
1df60 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73  on't allow acces
1df70 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e  s, but don't gen
1df80 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a  erate an error *
1df90 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
1dfa0 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63  F: Authorizer Ac
1dfb0 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  tion Codes.**.**
1dfc0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
1dfd0 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20  t_authorizer()] 
1dfe0 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
1dff0 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  ers a callback f
1e000 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20  unction.** that 
1e010 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75  is invoked to au
1e020 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20  thorize certain 
1e030 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63  SQL statement ac
1e040 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73  tions.  The.** s
1e050 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1e060 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
1e070 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f  is an integer co
1e080 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65  de that specifie
1e090 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e  s.** what action
1e0a0 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72   is being author
1e0b0 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65  ized.  These are
1e0c0 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74   the integer act
1e0d0 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a  ion codes that.*
1e0e0 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * the authorizer
1e0f0 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65   callback may be
1e100 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   passed..**.** T
1e110 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65  hese action code
1e120 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20   values signify 
1e130 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65  what kind of ope
1e140 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a  ration is to be.
1e150 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20  ** authorized.  
1e160 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20  The 3rd and 4th 
1e170 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
1e180 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a  e authorization.
1e190 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  ** callback func
1e1a0 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72  tion will be par
1e1b0 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20  ameters or NULL 
1e1c0 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69  depending on whi
1e1d0 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63  ch of these.** c
1e1e0 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20  odes is used as 
1e1f0 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
1e200 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68  eter.  ^(The 5th
1e210 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1e220 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20  e.** authorizer 
1e230 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20  callback is the 
1e240 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
1e250 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74  base ("main", "t
1e260 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69  emp",.** etc.) i
1e270 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20  f applicable.)^ 
1e280 20 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d 65   ^The 6th parame
1e290 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ter to the autho
1e2a0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a  rizer callback.*
1e2b0 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  * is the name of
1e2c0 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20   the inner-most 
1e2d0 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20  trigger or view 
1e2e0 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69  that is responsi
1e2f0 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61  ble for.** the a
1e300 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72  ccess attempt or
1e310 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63   NULL if this ac
1e320 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20  cess attempt is 
1e330 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a  directly from.**
1e340 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63   top-level SQL c
1e350 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a  ode..*/./*******
1e360 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1e370 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1e380 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a  **** 3rd *******
1e390 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a  ***** 4th ******
1e3a0 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  *****/.#define S
1e3b0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44  QLITE_CREATE_IND
1e3c0 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20  EX          1   
1e3d0 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
1e3e0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1e3f0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1e400 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c  LITE_CREATE_TABL
1e410 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f  E          2   /
1e420 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1e430 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1e440 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1e450 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
1e460 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a  INDEX     3   /*
1e470 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
1e480 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1e490 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1e4a0 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54  TE_CREATE_TEMP_T
1e4b0 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20  ABLE     4   /* 
1e4c0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1e4d0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1e4e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1e4f0 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52  E_CREATE_TEMP_TR
1e500 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54  IGGER   5   /* T
1e510 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
1e520 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1e530 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1e540 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45  _CREATE_TEMP_VIE
1e550 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69  W      6   /* Vi
1e560 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
1e570 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1e580 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1e590 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20  CREATE_TRIGGER  
1e5a0 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69        7   /* Tri
1e5b0 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
1e5c0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1e5d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1e5e0 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20  REATE_VIEW      
1e5f0 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77       8   /* View
1e600 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
1e610 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1e620 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
1e630 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20  LETE            
1e640 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65      9   /* Table
1e650 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1e660 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1e670 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1e680 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  P_INDEX         
1e690 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20    10   /* Index 
1e6a0 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
1e6b0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1e6c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1e6d0 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
1e6e0 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   11   /* Table N
1e6f0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1e700 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1e710 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1e720 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20  TEMP_INDEX      
1e730 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  12   /* Index Na
1e740 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
1e750 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1e760 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
1e770 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31  EMP_TABLE      1
1e780 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  3   /* Table Nam
1e790 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1e7a0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1e7b0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
1e7c0 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34  MP_TRIGGER    14
1e7d0 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
1e7e0 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
1e7f0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1e800 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
1e810 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20  P_VIEW       15 
1e820 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
1e830 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1e840 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1e850 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47  SQLITE_DROP_TRIG
1e860 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20  GER         16  
1e870 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
1e880 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1e890 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1e8a0 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20  QLITE_DROP_VIEW 
1e8b0 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20             17   
1e8c0 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
1e8d0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1e8e0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1e8f0 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20  LITE_INSERT     
1e900 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f            18   /
1e910 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1e920 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1e930 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1e940 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20  ITE_PRAGMA      
1e950 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a           19   /*
1e960 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20   Pragma Name    
1e970 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c   1st arg or NULL
1e980 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1e990 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20  TE_READ         
1e9a0 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20          20   /* 
1e9b0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1e9c0 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20  Column Name     
1e9d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1e9e0 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20  E_SELECT        
1e9f0 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e         21   /* N
1ea00 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e  ULL            N
1ea10 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1ea20 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1ea30 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20  _TRANSACTION    
1ea40 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70        22   /* Op
1ea50 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55  eration       NU
1ea60 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1ea70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1ea80 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20  UPDATE          
1ea90 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62       23   /* Tab
1eaa0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c  le Name      Col
1eab0 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  umn Name     */.
1eac0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
1ead0 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20  TTACH           
1eae0 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65      24   /* File
1eaf0 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c  name        NULL
1eb00 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1eb10 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
1eb20 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20  TACH            
1eb30 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62     25   /* Datab
1eb40 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20  ase Name   NULL 
1eb50 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1eb60 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54  efine SQLITE_ALT
1eb70 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  ER_TABLE        
1eb80 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61    26   /* Databa
1eb90 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20  se Name   Table 
1eba0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1ebb0 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e  fine SQLITE_REIN
1ebc0 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20  DEX             
1ebd0 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   27   /* Index N
1ebe0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1ebf0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1ec00 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59  ine SQLITE_ANALY
1ec10 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ZE              
1ec20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  28   /* Table Na
1ec30 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1ec40 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1ec50 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1ec60 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32  _VTABLE        2
1ec70 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  9   /* Table Nam
1ec80 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61  e      Module Na
1ec90 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
1eca0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54  e SQLITE_DROP_VT
1ecb0 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30  ABLE          30
1ecc0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1ecd0 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d        Module Nam
1ece0 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
1ecf0 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e   SQLITE_FUNCTION
1ed00 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20               31 
1ed10 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
1ed20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61       Function Na
1ed30 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20  me   */.#define 
1ed40 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54  SQLITE_SAVEPOINT
1ed50 20 20 20 20 20 20 20 20 20 20 20 20 33 32 20 20              32  
1ed60 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20   /* Operation   
1ed70 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61      Savepoint Na
1ed80 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  me  */.#define S
1ed90 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20  QLITE_COPY      
1eda0 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20              0   
1edb0 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65  /* No longer use
1edc0 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d */../*.** CAPI
1edd0 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e  3REF: Tracing An
1ede0 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63  d Profiling Func
1edf0 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
1ee00 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73  e routines regis
1ee10 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  ter callback fun
1ee20 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20  ctions that can 
1ee30 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74  be used for.** t
1ee40 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69  racing and profi
1ee50 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69  ling the executi
1ee60 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d  on of SQL statem
1ee70 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ents..**.** ^The
1ee80 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1ee90 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
1eea0 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
1eeb0 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a   is invoked at.*
1eec0 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20  * various times 
1eed0 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  when an SQL stat
1eee0 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72  ement is being r
1eef0 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73  un by [sqlite3_s
1ef00 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20  tep()]..** ^The 
1ef10 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
1ef20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
1ef30 6b 65 64 20 77 69 74 68 20 61 20 55 54 46 2d 38  ked with a UTF-8
1ef40 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
1ef50 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  e.** SQL stateme
1ef60 6e 74 20 74 65 78 74 20 61 73 20 74 68 65 20 73  nt text as the s
1ef70 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62  tatement first b
1ef80 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e  egins executing.
1ef90 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c  .** ^(Additional
1efa0 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
1efb0 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74   callbacks might
1efc0 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63   occur.** as eac
1efd0 68 20 74 72 69 67 67 65 72 65 64 20 73 75 62 70  h triggered subp
1efe0 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65  rogram is entere
1eff0 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  d.  The callback
1f000 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a  s for triggers.*
1f010 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d  * contain a UTF-
1f020 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68  8 SQL comment th
1f030 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 68  at identifies th
1f040 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a  e trigger.)^.**.
1f050 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** The [SQLITE_T
1f060 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d  RACE_SIZE_LIMIT]
1f070 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
1f080 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64  tion can be used
1f090 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 68 65   to limit.** the
1f0a0 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f 75 6e   length of [boun
1f0b0 64 20 70 61 72 61 6d 65 74 65 72 5d 20 65 78 70  d parameter] exp
1f0c0 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20 6f 75  ansion in the ou
1f0d0 74 70 75 74 20 6f 66 20 73 71 6c 69 74 65 33 5f  tput of sqlite3_
1f0e0 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  trace()..**.** ^
1f0f0 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
1f100 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64  ction registered
1f110 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66   by sqlite3_prof
1f120 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ile() is invoked
1f130 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20  .** as each SQL 
1f140 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68  statement finish
1f150 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c  es.  ^The profil
1f160 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61  e callback conta
1f170 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69  ins.** the origi
1f180 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  nal statement te
1f190 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61  xt and an estima
1f1a0 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b  te of wall-clock
1f1b0 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20   time.** of how 
1f1c0 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d  long that statem
1f1d0 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e  ent took to run.
1f1e0 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63    ^The profile c
1f1f0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20  allback.** time 
1f200 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e  is in units of n
1f210 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65  anoseconds, howe
1f220 76 65 72 20 74 68 65 20 63 75 72 72 65 6e 74 20  ver the current 
1f230 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  implementation.*
1f240 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c  * is only capabl
1f250 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  e of millisecond
1f260 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74   resolution so t
1f270 68 65 20 73 69 78 20 6c 65 61 73 74 20 73 69 67  he six least sig
1f280 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69  nificant.** digi
1f290 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20 61  ts in the time a
1f2a0 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20  re meaningless. 
1f2b0 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
1f2c0 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69   of SQLite.** mi
1f2d0 67 68 74 20 70 72 6f 76 69 64 65 20 67 72 65 61  ght provide grea
1f2e0 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f  ter resolution o
1f2f0 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20 63  n the profiler c
1f300 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a  allback.  The.**
1f310 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65   sqlite3_profile
1f320 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
1f330 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 72 69  onsidered experi
1f340 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a  mental and is.**
1f350 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
1f360 67 65 20 69 6e 20 66 75 74 75 72 65 20 76 65 72  ge in future ver
1f370 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e  sions of SQLite.
1f380 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
1f390 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a  3_trace(sqlite3*
1f3a0 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28  , void(*xTrace)(
1f3b0 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72  void*,const char
1f3c0 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49  *), void*);.SQLI
1f3d0 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20  TE_EXPERIMENTAL 
1f3e0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72  void *sqlite3_pr
1f3f0 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a  ofile(sqlite3*,.
1f400 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c     void(*xProfil
1f410 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63  e)(void*,const c
1f420 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e  har*,sqlite3_uin
1f430 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  t64), void*);../
1f440 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51  *.** CAPI3REF: Q
1f450 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61  uery Progress Ca
1f460 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54  llbacks.**.** ^T
1f470 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  he sqlite3_progr
1f480 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c  ess_handler(D,N,
1f490 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20 63  X,P) interface c
1f4a0 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61  auses the callba
1f4b0 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58  ck.** function X
1f4c0 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70   to be invoked p
1f4d0 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69  eriodically duri
1f4e0 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20  ng long running 
1f4f0 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c  calls to.** [sql
1f500 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73  ite3_exec()], [s
1f510 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61  qlite3_step()] a
1f520 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  nd [sqlite3_get_
1f530 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20  table()] for.** 
1f540 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1f550 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70  ion D.  An examp
1f560 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a  le use for this.
1f570 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
1f580 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 70  to keep a GUI up
1f590 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c  dated during a l
1f5a0 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a  arge query..**.*
1f5b0 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72  * ^The parameter
1f5c0 20 50 20 69 73 20 70 61 73 73 65 64 20 74 68 72   P is passed thr
1f5d0 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79  ough as the only
1f5e0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1f5f0 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66  e .** callback f
1f600 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65  unction X.  ^The
1f610 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20   parameter N is 
1f620 74 68 65 20 61 70 70 72 6f 78 69 6d 61 74 65 20  the approximate 
1f630 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76  number of .** [v
1f640 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69  irtual machine i
1f650 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61  nstructions] tha
1f660 74 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20  t are evaluated 
1f670 62 65 74 77 65 65 6e 20 73 75 63 63 65 73 73 69  between successi
1f680 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e  ve.** invocation
1f690 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63  s of the callbac
1f6a0 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69 73 20 6c  k X.  ^If N is l
1f6b0 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 74 68 65  ess than one the
1f6c0 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73 0a 2a  n the progress.*
1f6d0 2a 20 68 61 6e 64 6c 65 72 20 69 73 20 64 69 73  * handler is dis
1f6e0 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e  abled..**.** ^On
1f6f0 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67  ly a single prog
1f700 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79  ress handler may
1f710 20 62 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f   be defined at o
1f720 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b  ne time per.** [
1f730 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1f740 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20  ion]; setting a 
1f750 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e  new progress han
1f760 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65  dler cancels the
1f770 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53  .** old one.  ^S
1f780 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72  etting parameter
1f790 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62   X to NULL disab
1f7a0 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65 73 73  les the progress
1f7b0 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68   handler..** ^Th
1f7c0 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
1f7d0 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62  er is also disab
1f7e0 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e  led by setting N
1f7f0 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73   to a value less
1f800 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a  .** than 1..**.*
1f810 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65  * ^If the progre
1f820 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  ss callback retu
1f830 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
1f840 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a  e operation is.*
1f850 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20  * interrupted.  
1f860 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e  This feature can
1f870 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c   be used to impl
1f880 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63  ement a.** "Canc
1f890 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20  el" button on a 
1f8a0 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69 61  GUI progress dia
1f8b0 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54  log box..**.** T
1f8c0 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
1f8d0 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73  ler callback mus
1f8e0 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
1f8f0 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
1f900 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
1f910 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
1f920 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70  at invoked the p
1f930 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e  rogress handler.
1f940 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73  .** Note that [s
1f950 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1f960 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
1f970 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d  3_step()] both m
1f980 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64  odify their.** d
1f990 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1f9a0 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
1f9b0 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
1f9c0 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
1f9d0 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71  h..**.*/.void sq
1f9e0 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
1f9f0 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
1fa00 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69   int, int(*)(voi
1fa10 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  d*), void*);../*
1fa20 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70  .** CAPI3REF: Op
1fa30 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61  ening A New Data
1fa40 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a  base Connection.
1fa50 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
1fa60 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51  tines open an SQ
1fa70 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66 69  Lite database fi
1fa80 6c 65 20 61 73 20 73 70 65 63 69 66 69 65 64 20  le as specified 
1fa90 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e  by the .** filen
1faa0 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54  ame argument. ^T
1fab0 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
1fac0 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65  ment is interpre
1fad0 74 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72  ted as UTF-8 for
1fae0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
1faf0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
1fb00 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20  pen_v2() and as 
1fb10 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61  UTF-16 in the na
1fb20 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64  tive byte.** ord
1fb30 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  er for sqlite3_o
1fb40 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64 61  pen16(). ^(A [da
1fb50 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1fb60 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75  n] handle is usu
1fb70 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64  ally.** returned
1fb80 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20   in *ppDb, even 
1fb90 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  if an error occu
1fba0 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78  rs.  The only ex
1fbb0 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a  ception is that.
1fbc0 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  ** if SQLite is 
1fbd0 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
1fbe0 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  te memory to hol
1fbf0 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20  d the [sqlite3] 
1fc00 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c  object,.** a NUL
1fc10 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65  L will be writte
1fc20 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73  n into *ppDb ins
1fc30 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65  tead of a pointe
1fc40 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
1fc50 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20  3].** object.)^ 
1fc60 5e 28 49 66 20 74 68 65 20 64 61 74 61 62 61 73  ^(If the databas
1fc70 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64  e is opened (and
1fc80 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 63  /or created) suc
1fc90 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a  cessfully, then.
1fca0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69  ** [SQLITE_OK] i
1fcb0 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68  s returned.  Oth
1fcc0 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72  erwise an [error
1fcd0 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
1fce0 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73  ed.)^ ^The.** [s
1fcf0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
1fd00 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   or [sqlite3_err
1fd10 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  msg16()] routine
1fd20 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  s can be used to
1fd30 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e   obtain.** an En
1fd40 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64  glish language d
1fd50 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68  escription of th
1fd60 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e  e error followin
1fd70 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20 61  g a failure of a
1fd80 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c  ny.** of the sql
1fd90 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74  ite3_open() rout
1fda0 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ines..**.** ^The
1fdb0 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e   default encodin
1fdc0 67 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61  g for the databa
1fdd0 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38  se will be UTF-8
1fde0 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f   if.** sqlite3_o
1fdf0 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
1fe00 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 63 61  _open_v2() is ca
1fe10 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d  lled and.** UTF-
1fe20 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
1fe30 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 20 73   byte order if s
1fe40 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20  qlite3_open16() 
1fe50 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57  is used..**.** W
1fe60 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e  hether or not an
1fe70 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
1fe80 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c  en it is opened,
1fe90 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73   resources.** as
1fea0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
1feb0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
1fec0 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73  ection] handle s
1fed0 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65  hould be release
1fee0 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20  d by.** passing 
1fef0 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
1ff00 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20  lose()] when it 
1ff10 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71  is no longer req
1ff20 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  uired..**.** The
1ff30 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1ff40 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72  () interface wor
1ff50 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f  ks like sqlite3_
1ff60 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74  open().** except
1ff70 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74 73   that it accepts
1ff80 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
1ff90 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61  parameters for a
1ffa0 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f  dditional contro
1ffb0 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65  l.** over the ne
1ffc0 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
1ffd0 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c  ction.  ^(The fl
1ffe0 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ags parameter to
1fff0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
20000 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20 6f  _v2() can take o
20010 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c  ne of.** the fol
20020 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c  lowing three val
20030 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20  ues, optionally 
20040 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68  combined with th
20050 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  e .** [SQLITE_OP
20060 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51  EN_NOMUTEX], [SQ
20070 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
20080 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50  TEX], [SQLITE_OP
20090 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c  EN_SHAREDCACHE],
200a0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
200b0 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 2c 20  _PRIVATECACHE], 
200c0 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f  and/or [SQLITE_O
200d0 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29  PEN_URI] flags:)
200e0 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ^.**.** <dl>.** 
200f0 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  ^(<dt>[SQLITE_OP
20100 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74  EN_READONLY]</dt
20110 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
20120 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
20130 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64  in read-only mod
20140 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 62  e.  If the datab
20150 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  ase does not.** 
20160 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 61  already exist, a
20170 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  n error is retur
20180 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ned.</dd>)^.**.*
20190 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  * ^(<dt>[SQLITE_
201a0 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c  OPEN_READWRITE]<
201b0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
201c0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
201d0 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  ed for reading a
201e0 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f  nd writing if po
201f0 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69  ssible, or readi
20200 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68  ng.** only if th
20210 65 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20  e file is write 
20220 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 65  protected by the
20230 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
20240 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a  m.  In either.**
20250 20 63 61 73 65 20 74 68 65 20 64 61 74 61 62 61   case the databa
20260 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20  se must already 
20270 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65  exist, otherwise
20280 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74   an error is ret
20290 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  urned.</dd>)^.**
202a0 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54  .** ^(<dt>[SQLIT
202b0 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
202c0 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ] | [SQLITE_OPEN
202d0 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a  _CREATE]</dt>.**
202e0 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
202f0 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
20300 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74  reading and writ
20310 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61  ing, and is crea
20320 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65  ted if.** it doe
20330 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78  s not already ex
20340 69 73 74 2e 20 54 68 69 73 20 69 73 20 74 68 65  ist. This is the
20350 20 62 65 68 61 76 69 6f 72 20 74 68 61 74 20 69   behavior that i
20360 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f  s always used fo
20370 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  r.** sqlite3_ope
20380 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
20390 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e  open16().</dd>)^
203a0 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </dl>.**.** 
203b0 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
203c0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
203d0 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74  open_v2() is not
203e0 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63   one of the.** c
203f0 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77  ombinations show
20400 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c  n above optional
20410 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68  ly combined with
20420 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54   other.** [SQLIT
20430 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20  E_OPEN_READONLY 
20440 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20  | SQLITE_OPEN_* 
20450 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  bits].** then th
20460 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
20470 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
20480 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  If the [SQLITE_O
20490 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61  PEN_NOMUTEX] fla
204a0 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74  g is set, then t
204b0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
204c0 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20  ection.** opens 
204d0 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72  in the multi-thr
204e0 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  ead [threading m
204f0 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20  ode] as long as 
20500 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61  the single-threa
20510 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f  d.** mode has no
20520 74 20 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f  t been set at co
20530 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74  mpile-time or st
20540 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74  art-time.  ^If t
20550 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  he.** [SQLITE_OP
20560 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c  EN_FULLMUTEX] fl
20570 61 67 20 69 73 20 73 65 74 20 74 68 65 6e 20 74  ag is set then t
20580 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
20590 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20  ection opens.** 
205a0 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65  in the serialize
205b0 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
205c0 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65  e] unless single
205d0 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70  -thread was.** p
205e0 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74  reviously select
205f0 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  ed at compile-ti
20600 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65  me or start-time
20610 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ..** ^The [SQLIT
20620 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
20630 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20  HE] flag causes 
20640 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
20650 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a  nection to be.**
20660 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 65   eligible to use
20670 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d   [shared cache m
20680 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 73  ode], regardless
20690 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
206a0 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63  ot shared.** cac
206b0 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75 73  he is enabled us
206c0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61  ing [sqlite3_ena
206d0 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65  ble_shared_cache
206e0 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53  ()].  ^The.** [S
206f0 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
20700 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61  TECACHE] flag ca
20710 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73  uses the databas
20720 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  e connection to 
20730 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 61  not.** participa
20740 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61  te in [shared ca
20750 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69  che mode] even i
20760 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64 2e  f it is enabled.
20770 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72  .**.** ^The four
20780 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
20790 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
207a0 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  ) is the name of
207b0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
207c0 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61  _vfs] object tha
207d0 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70  t defines the op
207e0 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69  erating system i
207f0 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a  nterface that.**
20800 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73   the new databas
20810 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f  e connection sho
20820 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74 68  uld use.  ^If th
20830 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
20840 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20  er is.** a NULL 
20850 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65  pointer then the
20860 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
20870 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73  3_vfs] object is
20880 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66   used..**.** ^If
20890 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
208a0 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65   ":memory:", the
208b0 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d  n a private, tem
208c0 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79  porary in-memory
208d0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20   database.** is 
208e0 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20  created for the 
208f0 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68  connection.  ^Th
20900 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  is in-memory dat
20910 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73  abase will vanis
20920 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61  h when.** the da
20930 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
20940 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75  n is closed.  Fu
20950 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
20960 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a   SQLite might.**
20970 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64   make use of add
20980 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20  itional special 
20990 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62  filenames that b
209a0 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a  egin with the ":
209b0 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  " character..** 
209c0 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  It is recommende
209d0 64 20 74 68 61 74 20 77 68 65 6e 20 61 20 64 61  d that when a da
209e0 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
209f0 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65  actually does be
20a00 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a  gin with.** a ":
20a10 22 20 63 68 61 72 61 63 74 65 72 20 79 6f 75 20  " character you 
20a20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68  should prefix th
20a30 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20  e filename with 
20a40 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20  a pathname such 
20a50 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76  as.** "./" to av
20a60 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a  oid ambiguity..*
20a70 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c  *.** ^If the fil
20a80 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74  ename is an empt
20a90 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61  y string, then a
20aa0 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72   private, tempor
20ab0 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64  ary.** on-disk d
20ac0 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20  atabase will be 
20ad0 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73 20  created.  ^This 
20ae0 70 72 69 76 61 74 65 20 64 61 74 61 62 61 73 65  private database
20af0 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f   will be.** auto
20b00 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65  matically delete
20b10 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65  d as soon as the
20b20 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
20b30 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a  tion is closed..
20b40 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65  **.** [[URI file
20b50 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69 74 65 33  names in sqlite3
20b60 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52  _open()]] <h3>UR
20b70 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e  I Filenames</h3>
20b80 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20  .**.** ^If [URI 
20b90 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70  filename] interp
20ba0 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62  retation is enab
20bb0 6c 65 64 2c 20 61 6e 64 20 74 68 65 20 66 69 6c  led, and the fil
20bc0 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ename argument.*
20bd0 2a 20 62 65 67 69 6e 73 20 77 69 74 68 20 22 66  * begins with "f
20be0 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68 65 20  ile:", then the 
20bf0 66 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74 65  filename is inte
20c00 72 70 72 65 74 65 64 20 61 73 20 61 20 55 52 49  rpreted as a URI
20c10 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61  . ^URI.** filena
20c20 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  me interpretatio
20c30 6e 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20  n is enabled if 
20c40 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
20c50 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a  _URI] flag is.**
20c60 20 73 65 74 20 69 6e 20 74 68 65 20 66 6f 75 72   set in the four
20c70 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  th argument to s
20c80 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
20c90 2c 20 6f 72 20 69 66 20 69 74 20 68 61 73 0a 2a  , or if it has.*
20ca0 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 20 67  * been enabled g
20cb0 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20 74 68  lobally using th
20cc0 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  e [SQLITE_CONFIG
20cd0 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74  _URI] option wit
20ce0 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  h the.** [sqlite
20cf0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68  3_config()] meth
20d00 6f 64 20 6f 72 20 62 79 20 74 68 65 20 5b 53 51  od or by the [SQ
20d10 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f  LITE_USE_URI] co
20d20 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
20d30 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69  n..** As of SQLi
20d40 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37  te version 3.7.7
20d50 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 69  , URI filename i
20d60 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73  nterpretation is
20d70 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62   turned off.** b
20d80 79 20 64 65 66 61 75 6c 74 2c 20 62 75 74 20 66  y default, but f
20d90 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
20da0 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 65  f SQLite might e
20db0 6e 61 62 6c 65 20 55 52 49 20 66 69 6c 65 6e 61  nable URI filena
20dc0 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 61  me.** interpreta
20dd0 74 69 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e  tion by default.
20de0 20 20 53 65 65 20 22 5b 55 52 49 20 66 69 6c 65    See "[URI file
20df0 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61 64 64 69  names]" for addi
20e00 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d  tional.** inform
20e10 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49  ation..**.** URI
20e20 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 70   filenames are p
20e30 61 72 73 65 64 20 61 63 63 6f 72 64 69 6e 67 20  arsed according 
20e40 74 6f 20 52 46 43 20 33 39 38 36 2e 20 5e 49 66  to RFC 3986. ^If
20e50 20 74 68 65 20 55 52 49 20 63 6f 6e 74 61 69 6e   the URI contain
20e60 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74  s an.** authorit
20e70 79 2c 20 74 68 65 6e 20 69 74 20 6d 75 73 74 20  y, then it must 
20e80 62 65 20 65 69 74 68 65 72 20 61 6e 20 65 6d 70  be either an emp
20e90 74 79 20 73 74 72 69 6e 67 20 6f 72 20 74 68 65  ty string or the
20ea0 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63   string .** "loc
20eb0 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 65  alhost". ^If the
20ec0 20 61 75 74 68 6f 72 69 74 79 20 69 73 20 6e 6f   authority is no
20ed0 74 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  t an empty strin
20ee0 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22  g or "localhost"
20ef0 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69  , an .** error i
20f00 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68  s returned to th
20f10 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66  e caller. ^The f
20f20 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e  ragment componen
20f30 74 20 6f 66 20 61 20 55 52 49 2c 20 69 66 20 0a  t of a URI, if .
20f40 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69 73 20 69  ** present, is i
20f50 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53  gnored..**.** ^S
20f60 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 70  QLite uses the p
20f70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ath component of
20f80 20 74 68 65 20 55 52 49 20 61 73 20 74 68 65 20   the URI as the 
20f90 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 69 73 6b  name of the disk
20fa0 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63   file.** which c
20fb0 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74 61  ontains the data
20fc0 62 61 73 65 2e 20 5e 49 66 20 74 68 65 20 70 61  base. ^If the pa
20fd0 74 68 20 62 65 67 69 6e 73 20 77 69 74 68 20 61  th begins with a
20fe0 20 27 2f 27 20 63 68 61 72 61 63 74 65 72 2c 20   '/' character, 
20ff0 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 69  .** then it is i
21000 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 6e  nterpreted as an
21010 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 2e 20   absolute path. 
21020 5e 49 66 20 74 68 65 20 70 61 74 68 20 64 6f 65  ^If the path doe
21030 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20  s not begin .** 
21040 77 69 74 68 20 61 20 27 2f 27 20 28 6d 65 61 6e  with a '/' (mean
21050 69 6e 67 20 74 68 61 74 20 74 68 65 20 61 75 74  ing that the aut
21060 68 6f 72 69 74 79 20 73 65 63 74 69 6f 6e 20 69  hority section i
21070 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  s omitted from t
21080 68 65 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20  he URI).** then 
21090 74 68 65 20 70 61 74 68 20 69 73 20 69 6e 74 65  the path is inte
210a0 72 70 72 65 74 65 64 20 61 73 20 61 20 72 65 6c  rpreted as a rel
210b0 61 74 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20  ative path. .** 
210c0 5e 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68 65  ^On windows, the
210d0 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74   first component
210e0 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74 65 20   of an absolute 
210f0 70 61 74 68 20 0a 2a 2a 20 69 73 20 61 20 64 72  path .** is a dr
21100 69 76 65 20 73 70 65 63 69 66 69 63 61 74 69 6f  ive specificatio
21110 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e 0a 2a  n (e.g. "C:")..*
21120 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20  *.** [[core URI 
21130 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73  query parameters
21140 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72 79 20  ]].** The query 
21150 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55  component of a U
21160 52 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70  RI may contain p
21170 61 72 61 6d 65 74 65 72 73 20 74 68 61 74 20 61  arameters that a
21180 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 0a 2a  re interpreted.*
21190 2a 20 65 69 74 68 65 72 20 62 79 20 53 51 4c 69  * either by SQLi
211a0 74 65 20 69 74 73 65 6c 66 2c 20 6f 72 20 62 79  te itself, or by
211b0 20 61 20 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d   a [VFS | custom
211c0 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
211d0 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20  ion]..** SQLite 
211e0 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 66  interprets the f
211f0 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 71  ollowing three q
21200 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 3a  uery parameters:
21210 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20  .**.** <ul>.**  
21220 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e   <li> <b>vfs</b>
21230 3a 20 5e 54 68 65 20 22 76 66 73 22 20 70 61 72  : ^The "vfs" par
21240 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 75 73  ameter may be us
21250 65 64 20 74 6f 20 73 70 65 63 69 66 79 20 74 68  ed to specify th
21260 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20  e name of.**    
21270 20 61 20 56 46 53 20 6f 62 6a 65 63 74 20 74 68   a VFS object th
21280 61 74 20 70 72 6f 76 69 64 65 73 20 74 68 65 20  at provides the 
21290 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
212a0 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
212b0 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65  should.**     be
212c0 20 75 73 65 64 20 74 6f 20 61 63 63 65 73 73 20   used to access 
212d0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
212e0 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74  e on disk. ^If t
212f0 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  his option is se
21300 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65  t to.**     an e
21310 6d 70 74 79 20 73 74 72 69 6e 67 20 74 68 65 20  mpty string the 
21320 64 65 66 61 75 6c 74 20 56 46 53 20 6f 62 6a 65  default VFS obje
21330 63 74 20 69 73 20 75 73 65 64 2e 20 5e 53 70 65  ct is used. ^Spe
21340 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f  cifying an unkno
21350 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 73  wn.**     VFS is
21360 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 73   an error. ^If s
21370 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
21380 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65   is used and the
21390 20 76 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a   vfs option is.*
213a0 2a 20 20 20 20 20 70 72 65 73 65 6e 74 2c 20 74  *     present, t
213b0 68 65 6e 20 74 68 65 20 56 46 53 20 73 70 65 63  hen the VFS spec
213c0 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 70 74  ified by the opt
213d0 69 6f 6e 20 74 61 6b 65 73 20 70 72 65 63 65 64  ion takes preced
213e0 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20  ence over.**    
213f0 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65   the value passe
21400 64 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20  d as the fourth 
21410 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
21420 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a  ite3_open_v2()..
21430 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e  **.**   <li> <b>
21440 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20  mode</b>: ^(The 
21450 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 6d  mode parameter m
21460 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74  ay be set to eit
21470 68 65 72 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a  her "ro", "rw",.
21480 2a 2a 20 20 20 20 20 22 72 77 63 22 2c 20 6f 72  **     "rwc", or
21490 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d   "memory". Attem
214a0 70 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74 20  pting to set it 
214b0 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c  to any other val
214c0 75 65 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20  ue is.**     an 
214d0 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20  error)^. .**    
214e0 20 5e 49 66 20 22 72 6f 22 20 69 73 20 73 70 65   ^If "ro" is spe
214f0 63 69 66 69 65 64 2c 20 74 68 65 6e 20 74 68 65  cified, then the
21500 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
21510 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c  ned for read-onl
21520 79 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73  y .**     access
21530 2c 20 6a 75 73 74 20 61 73 20 69 66 20 74 68 65  , just as if the
21540 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
21550 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64  ADONLY] flag had
21560 20 62 65 65 6e 20 73 65 74 20 69 6e 20 74 68 65   been set in the
21570 20 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 20 61   .**     third a
21580 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
21590 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49  e3_open_v2(). ^I
215a0 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f  f the mode optio
215b0 6e 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20  n is set to .** 
215c0 20 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74      "rw", then t
215d0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
215e0 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77  pened for read-w
215f0 72 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72  rite (but not cr
21600 65 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63  eate) .**     ac
21610 63 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49  cess, as if SQLI
21620 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
21630 45 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54  E (but not SQLIT
21640 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68  E_OPEN_CREATE) h
21650 61 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20  ad .**     been 
21660 73 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63  set. ^Value "rwc
21670 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20  " is equivalent 
21680 74 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20  to setting both 
21690 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f  .**     SQLITE_O
216a0 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e  PEN_READWRITE an
216b0 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  d SQLITE_OPEN_CR
216c0 45 41 54 45 2e 20 20 5e 49 66 20 74 68 65 20 6d  EATE.  ^If the m
216d0 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a  ode option is.**
216e0 20 20 20 20 20 73 65 74 20 74 6f 20 22 6d 65 6d       set to "mem
216f0 6f 72 79 22 20 74 68 65 6e 20 61 20 70 75 72 65  ory" then a pure
21700 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61   [in-memory data
21710 62 61 73 65 5d 20 74 68 61 74 20 6e 65 76 65 72  base] that never
21720 20 72 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72   reads.**     or
21730 20 77 72 69 74 65 73 20 66 72 6f 6d 20 64 69 73   writes from dis
21740 6b 20 69 73 20 75 73 65 64 2e 20 5e 49 74 20 69  k is used. ^It i
21750 73 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70  s an error to sp
21760 65 63 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f  ecify a value fo
21770 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f 64  r.**     the mod
21780 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74  e parameter that
21790 20 69 73 20 6c 65 73 73 20 72 65 73 74 72 69 63   is less restric
217a0 74 69 76 65 20 74 68 61 6e 20 74 68 61 74 20 73  tive than that s
217b0 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20  pecified by.**  
217c0 20 20 20 74 68 65 20 66 6c 61 67 73 20 70 61 73     the flags pas
217d0 73 65 64 20 69 6e 20 74 68 65 20 74 68 69 72 64  sed in the third
217e0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
217f0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
21800 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62  .**.**   <li> <b
21810 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65  >cache</b>: ^The
21820 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72   cache parameter
21830 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65   may be set to e
21840 69 74 68 65 72 20 22 73 68 61 72 65 64 22 20 6f  ither "shared" o
21850 72 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61 74  r.**     "privat
21860 65 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 20  e". ^Setting it 
21870 74 6f 20 22 73 68 61 72 65 64 22 20 69 73 20 65  to "shared" is e
21880 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74  quivalent to set
21890 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20  ting the.**     
218a0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
218b0 45 44 43 41 43 48 45 20 62 69 74 20 69 6e 20 74  EDCACHE bit in t
218c0 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
218d0 74 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20  t passed to.**  
218e0 20 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f     sqlite3_open_
218f0 76 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 74  v2(). ^Setting t
21900 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74  he cache paramet
21910 65 72 20 74 6f 20 22 70 72 69 76 61 74 65 22 20  er to "private" 
21920 69 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 76  is .**     equiv
21930 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67  alent to setting
21940 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e   the SQLITE_OPEN
21950 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 62 69  _PRIVATECACHE bi
21960 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 71  t..**     ^If sq
21970 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
21980 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20  is used and the 
21990 22 63 61 63 68 65 22 20 70 61 72 61 6d 65 74 65  "cache" paramete
219a0 72 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e 0a  r is present in.
219b0 2a 2a 20 20 20 20 20 61 20 55 52 49 20 66 69 6c  **     a URI fil
219c0 65 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 65  ename, its value
219d0 20 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20 62   overrides any b
219e0 65 68 61 76 69 6f 72 20 72 65 71 75 65 73 74 65  ehavior requeste
219f0 64 20 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20  d by setting.** 
21a00 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f      SQLITE_OPEN_
21a10 50 52 49 56 41 54 45 43 41 43 48 45 20 6f 72 20  PRIVATECACHE or 
21a20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
21a30 45 44 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a  EDCACHE flag..**
21a40 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70   </ul>.**.** ^Sp
21a50 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e  ecifying an unkn
21a60 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69 6e  own parameter in
21a70 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f   the query compo
21a80 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69 73  nent of a URI is
21a90 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72   not an.** error
21aa0 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
21ab0 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  ns of SQLite mig
21ac0 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61 64  ht understand ad
21ad0 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a  ditional query.*
21ae0 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 53  * parameters.  S
21af0 65 65 20 22 5b 71 75 65 72 79 20 70 61 72 61 6d  ee "[query param
21b00 65 74 65 72 73 20 77 69 74 68 20 73 70 65 63 69  eters with speci
21b10 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51  al meaning to SQ
21b20 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64  Lite]" for.** ad
21b30 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
21b40 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52  tion..**.** [[UR
21b50 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70  I filename examp
21b60 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69  les]] <h3>URI fi
21b70 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c  lename examples<
21b80 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c  /h3>.**.** <tabl
21b90 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c 69  e border="1" ali
21ba0 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70 61  gn=center cellpa
21bb0 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e  dding=5>.** <tr>
21bc0 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d  <th> URI filenam
21bd0 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a  es <th> Results.
21be0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
21bf0 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a  :data.db <td> .*
21c00 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
21c10 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64  the file "data.d
21c20 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  b" in the curren
21c30 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20  t directory..** 
21c40 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68  <tr><td> file:/h
21c50 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
21c60 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20  <br>.**         
21c70 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72   file:///home/fr
21c80 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20  ed/data.db <br> 
21c90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c  .**          fil
21ca0 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f  e://localhost/ho
21cb0 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20  me/fred/data.db 
21cc0 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  <br> <td> .**   
21cd0 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20         Open the 
21ce0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 22 2f  database file "/
21cf0 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
21d00 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  b"..** <tr><td> 
21d10 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f  file://darkstar/
21d20 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
21d30 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  b <td> .**      
21d40 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 64      An error. "d
21d50 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74 20  arkstar" is not 
21d60 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75 74  a recognized aut
21d70 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c  hority..** <tr><
21d80 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65 2d  td style="white-
21d90 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a  space:nowrap"> .
21da0 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65  **          file
21db0 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73  :///C:/Documents
21dc0 25 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e 67  %20and%20Setting
21dd0 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64  s/fred/Desktop/d
21de0 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74  ata.db.**     <t
21df0 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a  d> Windows only:
21e00 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22   Open the file "
21e10 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65 64  data.db" on fred
21e20 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72  's desktop on dr
21e30 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ive.**          
21e40 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68  C:. Note that th
21e50 65 20 25 32 30 20 65 73 63 61 70 69 6e 67 20 69  e %20 escaping i
21e60 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20 69  n this example i
21e70 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 0a  s not strictly .
21e80 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63 65  **          nece
21e90 73 73 61 72 79 20 2d 20 73 70 61 63 65 20 63 68  ssary - space ch
21ea0 61 72 61 63 74 65 72 73 20 63 61 6e 20 62 65 20  aracters can be 
21eb0 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a  used literally.*
21ec0 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 55 52  *          in UR
21ed0 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20  I filenames..** 
21ee0 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61  <tr><td> file:da
21ef0 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61  ta.db?mode=ro&ca
21f00 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64 3e  che=private <td>
21f10 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70   .**          Op
21f20 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62  en file "data.db
21f30 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  " in the current
21f40 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20 72   directory for r
21f50 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e  ead-only access.
21f60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65 67  .**          Reg
21f70 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
21f80 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64  er or not shared
21f90 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20 65  -cache mode is e
21fa0 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20  nabled by.**    
21fb0 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20 75        default, u
21fc0 73 65 20 61 20 70 72 69 76 61 74 65 20 63 61 63  se a private cac
21fd0 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  he..** <tr><td> 
21fe0 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f  file:/home/fred/
21ff0 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78  data.db?vfs=unix
22000 2d 6e 6f 6c 6f 63 6b 20 3c 74 64 3e 0a 2a 2a 20  -nolock <td>.** 
22010 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69           Open fi
22020 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  le "/home/fred/d
22030 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74 68 65  ata.db". Use the
22040 20 73 70 65 63 69 61 6c 20 56 46 53 20 22 75 6e   special VFS "un
22050 69 78 2d 6e 6f 6c 6f 63 6b 22 2e 0a 2a 2a 20 3c  ix-nolock"..** <
22060 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74  tr><td> file:dat
22070 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e  a.db?mode=readon
22080 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  ly <td> .**     
22090 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22       An error. "
220a0 72 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74  readonly" is not
220b0 20 61 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20   a valid option 
220c0 66 6f 72 20 74 68 65 20 22 6d 6f 64 65 22 20 70  for the "mode" p
220d0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74  arameter..** </t
220e0 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49  able>.**.** ^URI
220f0 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63   hexadecimal esc
22100 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 28 25  ape sequences (%
22110 48 48 29 20 61 72 65 20 73 75 70 70 6f 72 74 65  HH) are supporte
22120 64 20 77 69 74 68 69 6e 20 74 68 65 20 70 61 74  d within the pat
22130 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63  h and.** query c
22140 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55  omponents of a U
22150 52 49 2e 20 41 20 68 65 78 61 64 65 63 69 6d 61  RI. A hexadecima
22160 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63  l escape sequenc
22170 65 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a  e consists of a.
22180 2a 2a 20 70 65 72 63 65 6e 74 20 73 69 67 6e 20  ** percent sign 
22190 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64  - "%" - followed
221a0 20 62 79 20 65 78 61 63 74 6c 79 20 74 77 6f 20   by exactly two 
221b0 68 65 78 61 64 65 63 69 6d 61 6c 20 64 69 67 69  hexadecimal digi
221c0 74 73 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e  ts .** specifyin
221d0 67 20 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 65  g an octet value
221e0 2e 20 5e 42 65 66 6f 72 65 20 74 68 65 20 70 61  . ^Before the pa
221f0 74 68 20 6f 72 20 71 75 65 72 79 20 63 6f 6d 70  th or query comp
22200 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55  onents of a.** U
22210 52 49 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 20  RI filename are 
22220 69 6e 74 65 72 70 72 65 74 65 64 2c 20 74 68 65  interpreted, the
22230 79 20 61 72 65 20 65 6e 63 6f 64 65 64 20 75 73  y are encoded us
22240 69 6e 67 20 55 54 46 2d 38 20 61 6e 64 20 61 6c  ing UTF-8 and al
22250 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d 61  l .** hexadecima
22260 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63  l escape sequenc
22270 65 73 20 72 65 70 6c 61 63 65 64 20 62 79 20 61  es replaced by a
22280 20 73 69 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e   single byte con
22290 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63  taining the.** c
222a0 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74  orresponding oct
222b0 65 74 2e 20 49 66 20 74 68 69 73 20 70 72 6f 63  et. If this proc
222c0 65 73 73 20 67 65 6e 65 72 61 74 65 73 20 61 6e  ess generates an
222d0 20 69 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 65   invalid UTF-8 e
222e0 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20  ncoding,.** the 
222f0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
22300 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  fined..**.** <b>
22310 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20  Note to Windows 
22320 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20  users:</b>  The 
22330 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f  encoding used fo
22340 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61  r the filename a
22350 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71  rgument.** of sq
22360 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
22370 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
22380 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38  () must be UTF-8
22390 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a  , not whatever.*
223a0 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63 75  * codepage is cu
223b0 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e  rrently defined.
223c0 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74    Filenames cont
223d0 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69  aining internati
223e0 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65  onal.** characte
223f0 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  rs must be conve
22400 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72  rted to UTF-8 pr
22410 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74  ior to passing t
22420 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69  hem into.** sqli
22430 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
22440 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
22450 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74  .**.** <b>Note t
22460 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d  o Windows Runtim
22470 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68  e users:</b>  Th
22480 65 20 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65  e temporary dire
22490 63 74 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65  ctory must be se
224a0 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61  t.** prior to ca
224b0 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70  lling sqlite3_op
224c0 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
224d0 6f 70 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65  open_v2().  Othe
224e0 72 77 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a  rwise, various.*
224f0 2a 20 66 65 61 74 75 72 65 73 20 74 68 61 74 20  * features that 
22500 72 65 71 75 69 72 65 20 74 68 65 20 75 73 65 20  require the use 
22510 6f 66 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  of temporary fil
22520 65 73 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a  es may fail..**.
22530 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
22540 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63  lite3_temp_direc
22550 74 6f 72 79 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  tory].*/.int sql
22560 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e  ite3_open(.  con
22570 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d  st char *filenam
22580 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
22590 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38   filename (UTF-8
225a0 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
225b0 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f  *ppDb          /
225c0 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
225d0 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e   handle */.);.in
225e0 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  t sqlite3_open16
225f0 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  (.  const void *
22600 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
22610 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
22620 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73   (UTF-16) */.  s
22630 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20  qlite3 **ppDb   
22640 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
22650 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
22660 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
22670 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e  3_open_v2(.  con
22680 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d  st char *filenam
22690 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
226a0 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38   filename (UTF-8
226b0 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
226c0 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f  *ppDb,         /
226d0 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
226e0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74   handle */.  int
226f0 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20   flags,         
22700 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f       /* Flags */
22710 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
22720 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61  Vfs        /* Na
22730 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65  me of VFS module
22740 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f   to use */.);../
22750 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
22760 62 74 61 69 6e 20 56 61 6c 75 65 73 20 46 6f 72  btain Values For
22770 20 55 52 49 20 50 61 72 61 6d 65 74 65 72 73 0a   URI Parameters.
22780 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20  **.** These are 
22790 75 74 69 6c 69 74 79 20 72 6f 75 74 69 6e 65 73  utility routines
227a0 2c 20 75 73 65 66 75 6c 20 74 6f 20 56 46 53 20  , useful to VFS 
227b0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c  implementations,
227c0 20 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74   that check.** t
227d0 6f 20 73 65 65 20 69 66 20 61 20 64 61 74 61 62  o see if a datab
227e0 61 73 65 20 66 69 6c 65 20 77 61 73 20 61 20 55  ase file was a U
227f0 52 49 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 65  RI that containe
22800 64 20 61 20 73 70 65 63 69 66 69 63 20 71 75 65  d a specific que
22810 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ry .** parameter
22820 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f 62 74 61  , and if so obta
22830 69 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66  ins the value of
22840 20 74 68 61 74 20 71 75 65 72 79 20 70 61 72 61   that query para
22850 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  meter..**.** If 
22860 46 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73  F is the databas
22870 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74  e filename point
22880 65 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74  er passed into t
22890 68 65 20 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f  he xOpen() metho
228a0 64 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20 69  d of .** a VFS i
228b0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68  mplementation wh
228c0 65 6e 20 74 68 65 20 66 6c 61 67 73 20 70 61 72  en the flags par
228d0 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 28  ameter to xOpen(
228e0 29 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a  ) has one or .**
228f0 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51   more of the [SQ
22900 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f  LITE_OPEN_URI] o
22910 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  r [SQLITE_OPEN_M
22920 41 49 4e 5f 44 42 5d 20 62 69 74 73 20 73 65 74  AIN_DB] bits set
22930 20 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68 65   and.** P is the
22940 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 71 75 65   name of the que
22950 72 79 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68  ry parameter, th
22960 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72  en.** sqlite3_ur
22970 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29  i_parameter(F,P)
22980 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c   returns the val
22990 75 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70  ue of the P.** p
229a0 61 72 61 6d 65 74 65 72 20 69 66 20 69 74 20 65  arameter if it e
229b0 78 69 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20  xists or a NULL 
229c0 70 6f 69 6e 74 65 72 20 69 66 20 50 20 64 6f 65  pointer if P doe
229d0 73 20 6e 6f 74 20 61 70 70 65 61 72 20 61 73 20  s not appear as 
229e0 61 20 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61  a .** query para
229f0 6d 65 74 65 72 20 6f 6e 20 46 2e 20 20 49 66 20  meter on F.  If 
22a00 50 20 69 73 20 61 20 71 75 65 72 79 20 70 61 72  P is a query par
22a10 61 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68  ameter of F.** h
22a20 61 73 20 6e 6f 20 65 78 70 6c 69 63 69 74 20 76  as no explicit v
22a30 61 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c 69 74  alue, then sqlit
22a40 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72  e3_uri_parameter
22a50 28 46 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a  (F,P) returns.**
22a60 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
22a70 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a   empty string..*
22a80 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
22a90 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
22aa0 2c 42 29 20 72 6f 75 74 69 6e 65 20 61 73 73 75  ,B) routine assu
22ab0 6d 65 73 20 74 68 61 74 20 50 20 69 73 20 61 20  mes that P is a 
22ac0 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d  boolean.** param
22ad0 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73  eter and returns
22ae0 20 74 72 75 65 20 28 31 29 20 6f 72 20 66 61 6c   true (1) or fal
22af0 73 65 20 28 30 29 20 61 63 63 6f 72 64 69 6e 67  se (0) according
22b00 20 74 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a   to the value.**
22b10 20 6f 66 20 50 2e 20 20 54 68 65 20 73 71 6c 69   of P.  The sqli
22b20 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
22b30 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 72  F,P,B) routine r
22b40 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20  eturns true (1) 
22b50 69 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20  if the.** value 
22b60 6f 66 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  of query paramet
22b70 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22  er P is one of "
22b80 79 65 73 22 2c 20 22 74 72 75 65 22 2c 20 6f 72  yes", "true", or
22b90 20 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20   "on" in any.** 
22ba0 63 61 73 65 20 6f 72 20 69 66 20 74 68 65 20 76  case or if the v
22bb0 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68  alue begins with
22bc0 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62   a non-zero numb
22bd0 65 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c  er.  The .** sql
22be0 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
22bf0 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 73  (F,P,B) routines
22c00 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 28   returns false (
22c10 30 29 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  0) if the value 
22c20 6f 66 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61  of.** query para
22c30 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f  meter P is one o
22c40 66 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c  f "no", "false",
22c50 20 6f 72 20 22 6f 66 66 22 20 69 6e 20 61 6e 79   or "off" in any
22c60 20 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74   case or.** if t
22c70 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20  he value begins 
22c80 77 69 74 68 20 61 20 6e 75 6d 65 72 69 63 20 7a  with a numeric z
22c90 65 72 6f 2e 20 20 49 66 20 50 20 69 73 20 6e 6f  ero.  If P is no
22ca0 74 20 61 20 71 75 65 72 79 0a 2a 2a 20 70 61 72  t a query.** par
22cb0 61 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72 20 69  ameter on F or i
22cc0 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50  f the value of P
22cd0 20 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74   is does not mat
22ce0 63 68 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a  ch any of the.**
22cf0 20 61 62 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c   above, then sql
22d00 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
22d10 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20  (F,P,B) returns 
22d20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  (B!=0)..**.** Th
22d30 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e  e sqlite3_uri_in
22d40 74 36 34 28 46 2c 50 2c 44 29 20 72 6f 75 74 69  t64(F,P,D) routi
22d50 6e 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 20  ne converts the 
22d60 76 61 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f 20  value of P into 
22d70 61 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69 67 6e  a.** 64-bit sign
22d80 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 72  ed integer and r
22d90 65 74 75 72 6e 73 20 74 68 61 74 20 69 6e 74 65  eturns that inte
22da0 67 65 72 2c 20 6f 72 20 44 20 69 66 20 50 20 64  ger, or D if P d
22db0 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74  oes not.** exist
22dc0 2e 20 20 49 66 20 74 68 65 20 76 61 6c 75 65 20  .  If the value 
22dd0 6f 66 20 50 20 69 73 20 73 6f 6d 65 74 68 69 6e  of P is somethin
22de0 67 20 6f 74 68 65 72 20 74 68 61 6e 20 61 6e 20  g other than an 
22df0 69 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a  integer, then.**
22e00 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65   zero is returne
22e10 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69  d..** .** If F i
22e20 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
22e30 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75  , then sqlite3_u
22e40 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50  ri_parameter(F,P
22e50 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61  ) returns NULL a
22e60 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72  nd.** sqlite3_ur
22e70 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
22e80 20 72 65 74 75 72 6e 73 20 42 2e 20 20 49 66 20   returns B.  If 
22e90 46 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20  F is not a NULL 
22ea0 70 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69  pointer and.** i
22eb0 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65  s not a database
22ec0 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 70   file pathname p
22ed0 6f 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69  ointer that SQLi
22ee0 74 65 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74  te passed into t
22ef0 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20  he xOpen.** VFS 
22f00 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65  method, then the
22f10 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69   behavior of thi
22f20 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64  s routine is und
22f30 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
22f40 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62  bly.** undesirab
22f50 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  le..*/.const cha
22f60 72 20 2a 73 71 6c 69 74 65 33 5f 75 72 69 5f 70  r *sqlite3_uri_p
22f70 61 72 61 6d 65 74 65 72 28 63 6f 6e 73 74 20 63  arameter(const c
22f80 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20  har *zFilename, 
22f90 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72  const char *zPar
22fa0 61 6d 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  am);.int sqlite3
22fb0 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e  _uri_boolean(con
22fc0 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20  st char *zFile, 
22fd0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72  const char *zPar
22fe0 61 6d 2c 20 69 6e 74 20 62 44 65 66 61 75 6c 74  am, int bDefault
22ff0 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
23000 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74   sqlite3_uri_int
23010 36 34 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  64(const char*, 
23020 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c  const char*, sql
23030 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f  ite3_int64);.../
23040 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
23050 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d  rror Codes And M
23060 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54  essages.**.** ^T
23070 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  he sqlite3_errco
23080 64 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  de() interface r
23090 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72  eturns the numer
230a0 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d  ic [result code]
230b0 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   or.** [extended
230c0 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f   result code] fo
230d0 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  r the most recen
230e0 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33  t failed sqlite3
230f0 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61  _* API call.** a
23100 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61  ssociated with a
23110 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
23120 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69  ction]. If a pri
23130 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c  or API call fail
23140 65 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f  ed.** but the mo
23150 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61  st recent API ca
23160 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74 68  ll succeeded, th
23170 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
23180 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65  rom.** sqlite3_e
23190 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65  rrcode() is unde
231a0 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 73 71 6c  fined.  ^The sql
231b0 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72  ite3_extended_er
231c0 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72  rcode().** inter
231d0 66 61 63 65 20 69 73 20 74 68 65 20 73 61 6d 65  face is the same
231e0 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20   except that it 
231f0 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 74  always returns t
23200 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64  he .** [extended
23210 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76   result code] ev
23220 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64  en when extended
23230 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
23240 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a  e.** disabled..*
23250 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
23260 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73  3_errmsg() and s
23270 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
23280 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68  ) return English
23290 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78  -language.** tex
232a0 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73  t that describes
232b0 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65   the error, as e
232c0 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55  ither UTF-8 or U
232d0 54 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 65  TF-16 respective
232e0 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20  ly..** ^(Memory 
232f0 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f  to hold the erro
23300 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
23310 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65   is managed inte
23320 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61  rnally..** The a
23330 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20  pplication does 
23340 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72  not need to worr
23350 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20  y about freeing 
23360 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48  the result..** H
23370 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f  owever, the erro
23380 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62  r string might b
23390 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72  e overwritten or
233a0 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a   deallocated by.
233b0 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  ** subsequent ca
233c0 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c  lls to other SQL
233d0 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 75  ite interface fu
233e0 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a  nctions.)^.**.**
233f0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72   ^The sqlite3_er
23400 72 73 74 72 28 29 20 69 6e 74 65 72 66 61 63 65  rstr() interface
23410 20 72 65 74 75 72 6e 73 20 74 68 65 20 45 6e 67   returns the Eng
23420 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 65  lish-language te
23430 78 74 0a 2a 2a 20 74 68 61 74 20 64 65 73 63 72  xt.** that descr
23440 69 62 65 73 20 74 68 65 20 5b 72 65 73 75 6c 74  ibes the [result
23450 20 63 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d 38   code], as UTF-8
23460 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f  ..** ^(Memory to
23470 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20   hold the error 
23480 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69  message string i
23490 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e  s managed intern
234a0 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 74  ally.** and must
234b0 20 6e 6f 74 20 62 65 20 66 72 65 65 64 20 62 79   not be freed by
234c0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
234d0 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  )^..**.** When t
234e0 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74  he serialized [t
234f0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69  hreading mode] i
23500 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67  s in use, it mig
23510 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73  ht be the.** cas
23520 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20  e that a second 
23530 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20  error occurs on 
23540 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
23550 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20  d in between.** 
23560 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20  the time of the 
23570 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20  first error and 
23580 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73  the call to thes
23590 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a  e interfaces..**
235a0 20 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 65   When that happe
235b0 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65  ns, the second e
235c0 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70  rror will be rep
235d0 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 73  orted since thes
235e0 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  e.** interfaces 
235f0 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 68  always report th
23600 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65  e most recent re
23610 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a  sult.  To avoid.
23620 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 68  ** this, each th
23630 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20  read can obtain 
23640 65 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66  exclusive use of
23650 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
23660 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20  onnection] D.** 
23670 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c  by invoking [sql
23680 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72  ite3_mutex_enter
23690 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75  ]([sqlite3_db_mu
236a0 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20  tex](D)) before 
236b0 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20  beginning.** to 
236c0 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69  use D and invoki
236d0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
236e0 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65  x_leave]([sqlite
236f0 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20  3_db_mutex](D)) 
23700 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c  after.** all cal
23710 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66  ls to the interf
23720 61 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 65  aces listed here
23730 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a   are completed..
23740 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65  **.** If an inte
23750 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68  rface fails with
23760 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20   SQLITE_MISUSE, 
23770 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69  that means the i
23780 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20  nterface.** was 
23790 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63  invoked incorrec
237a0 74 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c 69  tly by the appli
237b0 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74  cation.  In that
237c0 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72   case, the.** er
237d0 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73  ror code and mes
237e0 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20  sage may or may 
237f0 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 69  not be set..*/.i
23800 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  nt sqlite3_errco
23810 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b  de(sqlite3 *db);
23820 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74  .int sqlite3_ext
23830 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71  ended_errcode(sq
23840 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73  lite3 *db);.cons
23850 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
23860 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29  errmsg(sqlite3*)
23870 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
23880 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73  lite3_errmsg16(s
23890 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20  qlite3*);.const 
238a0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72  char *sqlite3_er
238b0 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  rstr(int);../*.*
238c0 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20  * CAPI3REF: SQL 
238d0 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
238e0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70  .** KEYWORDS: {p
238f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
23900 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61  t} {prepared sta
23910 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41  tements}.**.** A
23920 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
23930 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73  is object repres
23940 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51  ents a single SQ
23950 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20  L statement..** 
23960 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76  This object is v
23970 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61  ariously known a
23980 73 20 61 20 22 70 72 65 70 61 72 65 64 20 73 74  s a "prepared st
23990 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a  atement" or a.**
239a0 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73   "compiled SQL s
239b0 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d  tatement" or sim
239c0 70 6c 79 20 61 73 20 61 20 22 73 74 61 74 65 6d  ply as a "statem
239d0 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ent"..**.** The 
239e0 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d  life of a statem
239f0 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20  ent object goes 
23a00 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74  something like t
23a10 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  his:.**.** <ol>.
23a20 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74  ** <li> Create t
23a30 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20  he object using 
23a40 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
23a50 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61  _v2()] or a rela
23a60 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63  ted.**      func
23a70 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69  tion..** <li> Bi
23a80 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f  nd values to [ho
23a90 73 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75  st parameters] u
23aa0 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
23ab0 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20  _bind_*().**    
23ac0 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a    interfaces..**
23ad0 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51   <li> Run the SQ
23ae0 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  L by calling [sq
23af0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e  lite3_step()] on
23b00 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e  e or more times.
23b10 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74  .** <li> Reset t
23b20 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  he statement usi
23b30 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
23b40 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63  t()] then go bac
23b50 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65  k.**      to ste
23b60 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65  p 2.  Do this ze
23b70 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ro or more times
23b80 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f  ..** <li> Destro
23b90 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69  y the object usi
23ba0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
23bb0 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c  lize()]..** </ol
23bc0 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f  >.**.** Refer to
23bd0 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f   documentation o
23be0 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74  n individual met
23bf0 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61  hods above for a
23c00 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
23c10 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70  ormation..*/.typ
23c20 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
23c30 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33  te3_stmt sqlite3
23c40 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  _stmt;../*.** CA
23c50 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65  PI3REF: Run-time
23c60 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e 28   Limits.**.** ^(
23c70 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61  This interface a
23c80 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f  llows the size o
23c90 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72  f various constr
23ca0 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74  ucts to be limit
23cb0 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65  ed.** on a conne
23cc0 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74  ction by connect
23cd0 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20  ion basis.  The 
23ce0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
23cf0 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62  is the.** [datab
23d00 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
23d10 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74  whose limit is t
23d20 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 72  o be set or quer
23d30 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63  ied.  The.** sec
23d40 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
23d50 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d   one of the [lim
23d60 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74  it categories] t
23d70 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20  hat define a.** 
23d80 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75  class of constru
23d90 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c  cts to be size l
23da0 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 69  imited.  The thi
23db0 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rd parameter is 
23dc0 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74  the.** new limit
23dd0 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72   for that constr
23de0 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66  uct.)^.**.** ^If
23df0 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69   the new limit i
23e00 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d  s a negative num
23e10 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69  ber, the limit i
23e20 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20  s unchanged..** 
23e30 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74  ^(For each limit
23e40 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45   category SQLITE
23e50 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f  _LIMIT_<i>NAME</
23e60 69 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a  i> there is a .*
23e70 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64  * [limits | hard
23e80 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a   upper bound].**
23e90 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d   set at compile-
23ea0 74 69 6d 65 20 62 79 20 61 20 43 20 70 72 65 70  time by a C prep
23eb0 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63  rocessor macro c
23ec0 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73  alled.** [limits
23ed0 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69   | SQLITE_MAX_<i
23ee0 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28  >NAME</i>]..** (
23ef0 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e  The "_LIMIT_" in
23f00 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61   the name is cha
23f10 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e  nged to "_MAX_".
23f20 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73  ))^.** ^Attempts
23f30 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c   to increase a l
23f40 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 68  imit above its h
23f50 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20  ard upper bound 
23f60 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20  are.** silently 
23f70 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65  truncated to the
23f80 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
23f90 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64  d..**.** ^Regard
23fa0 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
23fb0 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74  or not the limit
23fc0 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68   was changed, th
23fd0 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c  e .** [sqlite3_l
23fe0 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63  imit()] interfac
23ff0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 70 72  e returns the pr
24000 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65  ior value of the
24010 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63   limit..** ^Henc
24020 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63  e, to find the c
24030 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20  urrent value of 
24040 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20  a limit without 
24050 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20  changing it,.** 
24060 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68  simply invoke th
24070 69 73 20 69 6e 74 65 72 66 61 63 65 20 77 69 74  is interface wit
24080 68 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  h the third para
24090 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e  meter set to -1.
240a0 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20  .**.** Run-time 
240b0 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e  limits are inten
240c0 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61  ded for use in a
240d0 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
240e0 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20   manage.** both 
240f0 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e  their own intern
24100 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  al database and 
24110 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20 74  also databases t
24120 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c  hat are controll
24130 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74  ed.** by untrust
24140 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72  ed external sour
24150 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65  ces.  An example
24160 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67   application mig
24170 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62  ht be a.** web b
24180 72 6f 77 73 65 72 20 74 68 61 74 20 68 61 73 20  rowser that has 
24190 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65  its own database
241a0 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69  s for storing hi
241b0 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70  story and.** sep
241c0 61 72 61 74 65 20 64 61 74 61 62 61 73 65 73 20  arate databases 
241d0 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61  controlled by Ja
241e0 76 61 53 63 72 69 70 74 20 61 70 70 6c 69 63 61  vaScript applica
241f0 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64  tions downloaded
24200 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65  .** off the Inte
24210 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72  rnet.  The inter
24220 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20 63 61  nal databases ca
24230 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a  n be given the.*
24240 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74  * large, default
24250 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61   limits.  Databa
24260 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65  ses managed by e
24270 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20  xternal sources 
24280 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20  can.** be given 
24290 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d  much smaller lim
242a0 69 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20  its designed to 
242b0 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c  prevent a denial
242c0 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61   of service.** a
242d0 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65  ttack.  Develope
242e0 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61  rs might also wa
242f0 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73  nt to use the [s
24300 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
24310 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65  rizer()].** inte
24320 72 66 61 63 65 20 74 6f 20 66 75 72 74 68 65 72  rface to further
24330 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74   control untrust
24340 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a  ed SQL.  The siz
24350 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
24360 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20  e.** created by 
24370 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63 72  an untrusted scr
24380 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61  ipt can be conta
24390 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a  ined using the.*
243a0 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e  * [max_page_coun
243b0 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a  t] [PRAGMA]..**.
243c0 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20  ** New run-time 
243d0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
243e0 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
243f0 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
24400 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
24410 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c  _limit(sqlite3*,
24420 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77   int id, int new
24430 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  Val);../*.** CAP
24440 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20  I3REF: Run-Time 
24450 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73  Limit Categories
24460 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c  .** KEYWORDS: {l
24470 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b  imit category} {
24480 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65  *limit categorie
24490 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  s}.**.** These c
244a0 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20  onstants define 
244b0 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61  various performa
244c0 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68  nce limits.** th
244d0 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65  at can be lowere
244e0 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73  d at run-time us
244f0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  ing [sqlite3_lim
24500 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79  it()]..** The sy
24510 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65  nopsis of the me
24520 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61  anings of the va
24530 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20  rious limits is 
24540 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20  shown below..** 
24550 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  Additional infor
24560 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61  mation is availa
24570 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c  ble at [limits |
24580 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74   Limits in SQLit
24590 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  e]..**.** <dl>.*
245a0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
245b0 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e  _LENGTH]] ^(<dt>
245c0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
245d0 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
245e0 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65  The maximum size
245f0 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f   of any string o
24600 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20  r BLOB or table 
24610 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64  row, in bytes.<d
24620 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
24630 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
24640 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  NGTH]] ^(<dt>SQL
24650 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
24660 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
24670 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e  >The maximum len
24680 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74  gth of an SQL st
24690 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65  atement, in byte
246a0 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  s.</dd>)^.**.** 
246b0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  [[SQLITE_LIMIT_C
246c0 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51  OLUMN]] ^(<dt>SQ
246d0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
246e0 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  N</dt>.** <dd>Th
246f0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
24700 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
24710 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f   table definitio
24720 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72  n or in the.** r
24730 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b  esult set of a [
24740 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d  SELECT] or the m
24750 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
24760 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69   columns in an i
24770 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e  ndex.** or in an
24780 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f   ORDER BY or GRO
24790 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64  UP BY clause.</d
247a0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
247b0 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
247c0 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  EPTH]] ^(<dt>SQL
247d0 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
247e0 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EPTH</dt>.** <dd
247f0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70  >The maximum dep
24800 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20  th of the parse 
24810 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72  tree on any expr
24820 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a  ession.</dd>)^.*
24830 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
24840 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MIT_COMPOUND_SEL
24850 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  ECT]] ^(<dt>SQLI
24860 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
24870 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a  D_SELECT</dt>.**
24880 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
24890 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73   number of terms
248a0 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53   in a compound S
248b0 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e  ELECT statement.
248c0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
248d0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
248e0 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  E_OP]] ^(<dt>SQL
248f0 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
24900 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  P</dt>.** <dd>Th
24910 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
24920 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73   of instructions
24930 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61   in a virtual ma
24940 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a  chine program.**
24950 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
24960 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  nt an SQL statem
24970 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 74  ent.  This limit
24980 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c   is not currentl
24990 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74  y.** enforced, t
249a0 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68 74  hough that might
249b0 20 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f 6d   be added in som
249c0 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  e future release
249d0 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f   of.** SQLite.</
249e0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
249f0 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
24a00 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e  ION_ARG]] ^(<dt>
24a10 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
24a20 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a  CTION_ARG</dt>.*
24a30 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
24a40 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  m number of argu
24a50 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74  ments on a funct
24a60 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ion.</dd>)^.**.*
24a70 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
24a80 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64  _ATTACHED]] ^(<d
24a90 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  t>SQLITE_LIMIT_A
24aa0 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20  TTACHED</dt>.** 
24ab0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
24ac0 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43  number of [ATTAC
24ad0 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 74  H | attached dat
24ae0 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a  abases].)^</dd>.
24af0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
24b00 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52  IMIT_LIKE_PATTER
24b10 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28  N_LENGTH]].** ^(
24b20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
24b30 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
24b40 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
24b50 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e  >The maximum len
24b60 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65  gth of the patte
24b70 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  rn argument to t
24b80 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20  he [LIKE] or.** 
24b90 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73  [GLOB] operators
24ba0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
24bb0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  [SQLITE_LIMIT_VA
24bc0 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a  RIABLE_NUMBER]].
24bd0 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
24be0 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
24bf0 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  UMBER</dt>.** <d
24c00 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e  d>The maximum in
24c10 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e  dex number of an
24c20 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  y [parameter] in
24c30 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
24c40 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  t.)^.**.** [[SQL
24c50 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45  ITE_LIMIT_TRIGGE
24c60 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e  R_DEPTH]] ^(<dt>
24c70 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49  SQLITE_LIMIT_TRI
24c80 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a  GGER_DEPTH</dt>.
24c90 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
24ca0 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75  um depth of recu
24cb0 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65  rsion for trigge
24cc0 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f  rs.</dd>)^.** </
24cd0 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
24ce0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
24cf0 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
24d00 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20        0.#define 
24d10 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
24d20 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20  _LENGTH         
24d30 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
24d40 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f   SQLITE_LIMIT_CO
24d50 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20  LUMN            
24d60 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
24d70 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  e SQLITE_LIMIT_E
24d80 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20  XPR_DEPTH       
24d90 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69           3.#defi
24da0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
24db0 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20  COMPOUND_SELECT 
24dc0 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66            4.#def
24dd0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
24de0 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20  _VDBE_OP        
24df0 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65             5.#de
24e00 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
24e10 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20  T_FUNCTION_ARG  
24e20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64              6.#d
24e30 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
24e40 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20  IT_ATTACHED     
24e50 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23               7.#
24e60 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
24e70 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
24e80 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a  _LENGTH       8.
24e90 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
24ea0 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
24eb0 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39  MBER           9
24ec0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
24ed0 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45  LIMIT_TRIGGER_DE
24ee0 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31  PTH            1
24ef0 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  0../*.** CAPI3RE
24f00 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20  F: Compiling An 
24f10 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL Statement.**
24f20 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20   KEYWORDS: {SQL 
24f30 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c  statement compil
24f40 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65  er}.**.** To exe
24f50 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72  cute an SQL quer
24f60 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74  y, it must first
24f70 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74   be compiled int
24f80 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a  o a byte-code.**
24f90 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f   program using o
24fa0 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ne of these rout
24fb0 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ines..**.** The 
24fc0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20  first argument, 
24fd0 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61  "db", is a [data
24fe0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
24ff0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61   obtained from a
25000 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73  .** prior succes
25010 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
25020 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
25030 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
25040 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
25050 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68  3_open16()].  Th
25060 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
25070 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68  ction must not h
25080 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e  ave been closed.
25090 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  .**.** The secon
250a0 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71  d argument, "zSq
250b0 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65  l", is the state
250c0 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69  ment to be compi
250d0 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20  led, encoded.** 
250e0 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20  as either UTF-8 
250f0 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20  or UTF-16.  The 
25100 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
25110 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  ) and sqlite3_pr
25120 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e  epare_v2().** in
25130 74 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46  terfaces use UTF
25140 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  -8, and sqlite3_
25150 70 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20  prepare16() and 
25160 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
25170 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54  6_v2().** use UT
25180 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  F-16..**.** ^If 
25190 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65  the nByte argume
251a0 6e 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  nt is less than 
251b0 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20  zero, then zSql 
251c0 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68  is read up to th
251d0 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20  e.** first zero 
251e0 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20  terminator. ^If 
251f0 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67  nByte is non-neg
25200 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69  ative, then it i
25210 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a  s the maximum.**
25220 20 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65   number of  byte
25230 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c  s read from zSql
25240 2e 20 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 69  .  ^When nByte i
25250 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
25260 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69  the.** zSql stri
25270 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74 68 65  ng ends at eithe
25280 72 20 74 68 65 20 66 69 72 73 74 20 27 5c 30 30  r the first '\00
25290 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63  0' or '\u0000' c
252a0 68 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74  haracter or.** t
252b0 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65  he nByte-th byte
252c0 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65  , whichever come
252d0 73 20 66 69 72 73 74 2e 20 49 66 20 74 68 65 20  s first. If the 
252e0 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20  caller knows.** 
252f0 74 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65  that the supplie
25300 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d  d string is nul-
25310 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e  terminated, then
25320 20 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c   there is a smal
25330 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65  l.** performance
25340 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65   advantage to be
25350 20 67 61 69 6e 65 64 20 62 79 20 70 61 73 73 69   gained by passi
25360 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61  ng an nByte para
25370 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73  meter that.** is
25380 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75   equal to the nu
25390 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
253a0 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
253b0 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f  g <i>including</
253c0 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65  i>.** the nul-te
253d0 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 20 61  rminator bytes a
253e0 73 20 74 68 69 73 20 73 61 76 65 73 20 53 51 4c  s this saves SQL
253f0 69 74 65 20 66 72 6f 6d 20 68 61 76 69 6e 67 20  ite from having 
25400 74 6f 0a 2a 2a 20 6d 61 6b 65 20 61 20 63 6f 70  to.** make a cop
25410 79 20 6f 66 20 74 68 65 20 69 6e 70 75 74 20 73  y of the input s
25420 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  tring..**.** ^If
25430 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e   pzTail is not N
25440 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c  ULL then *pzTail
25450 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   is made to poin
25460 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62  t to the first b
25470 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20  yte.** past the 
25480 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74  end of the first
25490 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
254a0 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72  n zSql.  These r
254b0 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20  outines only.** 
254c0 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73  compile the firs
254d0 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a  t statement in z
254e0 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20  Sql, so *pzTail 
254f0 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
25500 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61   to.** what rema
25510 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a  ins uncompiled..
25520 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69  **.** ^*ppStmt i
25530 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
25540 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70  to a compiled [p
25550 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
25560 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a  t] that can be.*
25570 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67  * executed using
25580 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
25590 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 73  ].  ^If there is
255a0 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74   an error, *ppSt
255b0 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20  mt is set.** to 
255c0 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69  NULL.  ^If the i
255d0 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69  nput text contai
255e0 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68  ns no SQL (if th
255f0 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d  e input is an em
25600 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72  pty.** string or
25610 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e   a comment) then
25620 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20   *ppStmt is set 
25630 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20  to NULL..** The 
25640 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72  calling procedur
25650 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  e is responsible
25660 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68   for deleting th
25670 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51  e compiled.** SQ
25680 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  L statement usin
25690 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
256a0 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20  ize()] after it 
256b0 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
256c0 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20  h it..** ppStmt 
256d0 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e  may not be NULL.
256e0 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65  .**.** ^On succe
256f0 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ss, the sqlite3_
25700 70 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79  prepare() family
25710 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74   of routines ret
25720 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b  urn [SQLITE_OK];
25730 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e  .** otherwise an
25740 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
25750 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
25760 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   The sqlite3_pre
25770 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71  pare_v2() and sq
25780 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
25790 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 20  v2() interfaces 
257a0 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64  are.** recommend
257b0 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70  ed for all new p
257c0 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f  rograms. The two
257d0 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65   older interface
257e0 73 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a  s are retained.*
257f0 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20  * for backwards 
25800 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62  compatibility, b
25810 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20  ut their use is 
25820 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20  discouraged..** 
25830 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74  ^In the "v2" int
25840 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65  erfaces, the pre
25850 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
25860 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72  ** that is retur
25870 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65  ned (the [sqlite
25880 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20  3_stmt] object) 
25890 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20  contains a copy 
258a0 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e  of the.** origin
258b0 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69  al SQL text. Thi
258c0 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71  s causes the [sq
258d0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e  lite3_step()] in
258e0 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65  terface to.** be
258f0 68 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79  have differently
25900 20 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a   in three ways:.
25910 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
25920 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61  i>.** ^If the da
25930 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
25940 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f  anges, instead o
25950 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c  f returning [SQL
25960 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69  ITE_SCHEMA] as i
25970 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64  t.** always used
25980 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33   to do, [sqlite3
25990 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75  _step()] will au
259a0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f  tomatically reco
259b0 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a  mpile the SQL.**
259c0 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
259d0 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61  ry to run it aga
259e0 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73 20 5b  in. As many as [
259f0 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d  SQLITE_MAX_SCHEM
25a00 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72  A_RETRY].** retr
25a10 69 65 73 20 77 69 6c 6c 20 6f 63 63 75 72 20 62  ies will occur b
25a20 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 73 74  efore sqlite3_st
25a30 65 70 28 29 20 67 69 76 65 73 20 75 70 20 61 6e  ep() gives up an
25a40 64 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72 72  d returns an err
25a50 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a  or..** </li>.**.
25a60 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e  ** <li>.** ^When
25a70 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
25a80 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
25a90 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f  )] will return o
25aa0 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c  ne of the detail
25ab0 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  ed.** [error cod
25ac0 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64  es] or [extended
25ad0 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20   error codes].  
25ae0 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61  ^The legacy beha
25af0 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a  vior was that.**
25b00 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
25b10 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74  ] would only ret
25b20 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53  urn a generic [S
25b30 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73  QLITE_ERROR] res
25b40 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20  ult code.** and 
25b50 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
25b60 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61  would have to ma
25b70 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c  ke a second call
25b80 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
25b90 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65  et()].** in orde
25ba0 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e  r to find the un
25bb0 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f  derlying cause o
25bc0 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57  f the problem. W
25bd0 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65  ith the "v2" pre
25be0 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  pare.** interfac
25bf0 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69  es, the underlyi
25c00 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68  ng reason for th
25c10 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  e error is retur
25c20 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e  ned immediately.
25c30 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20  .** </li>.**.** 
25c40 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  <li>.** ^If the 
25c50 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 62  specific value b
25c60 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74  ound to [paramet
25c70 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65  er | host parame
25c80 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20  ter] in the .** 
25c90 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67  WHERE clause mig
25ca0 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65  ht influence the
25cb0 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79   choice of query
25cc0 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74   plan for a stat
25cd0 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74  ement,.** then t
25ce0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c  he statement wil
25cf0 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  l be automatical
25d00 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61  ly recompiled, a
25d10 73 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62  s if there had b
25d20 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61  een .** a schema
25d30 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20   change, on the 
25d40 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f  first  [sqlite3_
25d50 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c  step()] call fol
25d60 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67  lowing any chang
25d70 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c  e.** to the [sql
25d80 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c  ite3_bind_text |
25d90 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68   bindings] of th
25da0 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20  at [parameter]. 
25db0 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69  .** ^The specifi
25dc0 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45  c value of WHERE
25dd0 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74  -clause [paramet
25de0 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65  er] might influe
25df0 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69  nce the .** choi
25e00 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e  ce of query plan
25e10 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
25e20 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61  r is the left-ha
25e30 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49  nd side of a [LI
25e40 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d  KE].** or [GLOB]
25e50 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20   operator or if 
25e60 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  the parameter is
25e70 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20   compared to an 
25e80 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a  indexed column.*
25e90 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54  * and the [SQLIT
25ea0 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20  E_ENABLE_STAT3] 
25eb0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
25ec0 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a  ion is enabled..
25ed0 2a 2a 20 74 68 65 20 0a 2a 2a 20 3c 2f 6c 69 3e  ** the .** </li>
25ee0 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74  .** </ol>.*/.int
25ef0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
25f00 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
25f10 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
25f20 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
25f30 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
25f40 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
25f50 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
25f60 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  F-8 encoded */. 
25f70 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
25f80 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
25f90 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
25fa0 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
25fb0 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
25fc0 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
25fd0 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
25fe0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
25ff0 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  ar **pzTail     
26000 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
26010 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
26020 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
26030 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
26040 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  are_v2(.  sqlite
26050 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
26060 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
26070 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
26080 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
26090 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
260a0 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
260b0 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
260c0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
260d0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
260e0 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
260f0 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
26100 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
26110 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
26120 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
26130 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
26140 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
26150 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
26160 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
26170 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
26180 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73  3_prepare16(.  s
26190 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
261a0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
261b0 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
261c0 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c  onst void *zSql,
261d0 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
261e0 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20  atement, UTF-16 
261f0 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
26200 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
26210 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
26220 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
26230 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
26240 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
26250 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
26260 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
26270 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
26280 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
26290 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
262a0 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
262b0 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
262c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
262d0 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  6_v2(.  sqlite3 
262e0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
262f0 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
26300 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
26310 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  id *zSql,       
26320 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
26330 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  , UTF-16 encoded
26340 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
26350 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
26360 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
26370 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
26380 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
26390 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
263a0 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
263b0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
263c0 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c  st void **pzTail
263d0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
263e0 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
263f0 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
26400 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
26410 33 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67  3REF: Retrieving
26420 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a   Statement SQL.*
26430 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72  *.** ^This inter
26440 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64  face can be used
26450 20 74 6f 20 72 65 74 72 69 65 76 65 20 61 20 73   to retrieve a s
26460 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65  aved copy of the
26470 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c   original.** SQL
26480 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 72   text used to cr
26490 65 61 74 65 20 61 20 5b 70 72 65 70 61 72 65 64  eate a [prepared
264a0 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74   statement] if t
264b0 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61  hat statement wa
264c0 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73  s.** compiled us
264d0 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69  ing either [sqli
264e0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
264f0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
26500 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
26510 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
26520 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65  lite3_sql(sqlite
26530 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
26540 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
26550 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e   Determine If An
26560 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 57   SQL Statement W
26570 72 69 74 65 73 20 54 68 65 20 44 61 74 61 62 61  rites The Databa
26580 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  se.**.** ^The sq
26590 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
265a0 6e 6c 79 28 58 29 20 69 6e 74 65 72 66 61 63 65  nly(X) interface
265b0 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e   returns true (n
265c0 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61  on-zero) if.** a
265d0 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b  nd only if the [
265e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
265f0 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64  nt] X makes no d
26600 69 72 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f  irect changes to
26610 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  .** the content 
26620 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
26630 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  file..**.** Note
26640 20 74 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69   that [applicati
26650 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
26660 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20  unctions] or.** 
26670 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d  [virtual tables]
26680 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74 68   might change th
26690 65 20 64 61 74 61 62 61 73 65 20 69 6e 64 69 72  e database indir
266a0 65 63 74 6c 79 20 61 73 20 61 20 73 69 64 65 20  ectly as a side 
266b0 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46  effect.  .** ^(F
266c0 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61  or example, if a
266d0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  n application de
266e0 66 69 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e  fines a function
266f0 20 22 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a   "eval()" that .
26700 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65  ** calls [sqlite
26710 33 5f 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20  3_exec()], then 
26720 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51  the following SQ
26730 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c  L statement woul
26740 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20  d.** change the 
26750 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 68  database file th
26760 72 6f 75 67 68 20 73 69 64 65 2d 65 66 66 65 63  rough side-effec
26770 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ts:.**.** <block
26780 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
26790 20 20 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44    SELECT eval('D
267a0 45 4c 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20  ELETE FROM t1') 
267b0 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72  FROM t2;.** </pr
267c0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
267d0 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73  **.** But becaus
267e0 65 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73  e the [SELECT] s
267f0 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f  tatement does no
26800 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74  t change the dat
26810 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69  abase file.** di
26820 72 65 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f  rectly, sqlite3_
26830 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20  stmt_readonly() 
26840 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75  would still retu
26850 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a  rn true.)^.**.**
26860 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f   ^Transaction co
26870 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73  ntrol statements
26880 20 73 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d   such as [BEGIN]
26890 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c  , [COMMIT], [ROL
268a0 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45  LBACK],.** [SAVE
268b0 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c  POINT], and [REL
268c0 45 41 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69  EASE] cause sqli
268d0 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
268e0 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72  y() to return tr
268f0 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65  ue,.** since the
26900 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d   statements them
26910 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63  selves do not ac
26920 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68  tually modify th
26930 65 20 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a  e database but.*
26940 2a 20 72 61 74 68 65 72 20 74 68 65 79 20 63 6f  * rather they co
26950 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67  ntrol the timing
26960 20 6f 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73   of when other s
26970 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79  tatements modify
26980 20 74 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73   the .** databas
26990 65 2e 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48  e.  ^The [ATTACH
269a0 5d 20 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73  ] and [DETACH] s
269b0 74 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63  tatements also c
269c0 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ause.** sqlite3_
269d0 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20  stmt_readonly() 
269e0 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 20 73  to return true s
269f0 69 6e 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73  ince, while thos
26a00 65 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  e statements.** 
26a10 63 68 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69  change the confi
26a20 67 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61  guration of a da
26a30 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
26a40 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d  n, they do not m
26a50 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20  ake .** changes 
26a60 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  to the content o
26a70 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  f the database f
26a80 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f  iles on disk..*/
26a90 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  .int sqlite3_stm
26aa0 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74  t_readonly(sqlit
26ab0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
26ac0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
26ad0 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
26ae0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
26af0 65 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65 73  ent Has Been Res
26b00 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  et.**.** ^The sq
26b10 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28  lite3_stmt_busy(
26b20 53 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  S) interface ret
26b30 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a  urns true (non-z
26b40 65 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b  ero) if the.** [
26b50 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
26b60 6e 74 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73  nt] S has been s
26b70 74 65 70 70 65 64 20 61 74 20 6c 65 61 73 74 20  tepped at least 
26b80 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b  once using .** [
26b90 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
26ba0 20 62 75 74 20 68 61 73 20 6e 6f 74 20 72 75 6e   but has not run
26bb0 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61   to completion a
26bc0 6e 64 2f 6f 72 20 68 61 73 20 6e 6f 74 20 0a 2a  nd/or has not .*
26bd0 2a 20 62 65 65 6e 20 72 65 73 65 74 20 75 73 69  * been reset usi
26be0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
26bf0 74 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c  t(S)].  ^The sql
26c00 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53  ite3_stmt_busy(S
26c10 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72  ).** interface r
26c20 65 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20  eturns false if 
26c30 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  S is a NULL poin
26c40 74 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f  ter.  If S is no
26c50 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69  t a .** NULL poi
26c60 6e 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20  nter and is not 
26c70 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76  a pointer to a v
26c80 61 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20 73  alid [prepared s
26c90 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a  tatement].** obj
26ca0 65 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65  ect, then the be
26cb0 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
26cc0 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79  ned and probably
26cd0 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a   undesirable..**
26ce0 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
26cf0 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 69  ce can be used i
26d00 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73  n combination [s
26d10 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74  qlite3_next_stmt
26d20 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65  ()].** to locate
26d30 20 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74   all prepared st
26d40 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61  atements associa
26d50 74 65 64 20 77 69 74 68 20 61 20 64 61 74 61 62  ted with a datab
26d60 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  ase .** connecti
26d70 6f 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e  on that are in n
26d80 65 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73  eed of being res
26d90 65 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65  et.  This can be
26da0 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78   used,.** for ex
26db0 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f  ample, in diagno
26dc0 73 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f  stic routines to
26dd0 20 73 65 61 72 63 68 20 66 6f 72 20 70 72 65 70   search for prep
26de0 61 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65  ared .** stateme
26df0 6e 74 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c  nts that are hol
26e00 64 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69  ding a transacti
26e10 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20  on open..*/.int 
26e20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73  sqlite3_stmt_bus
26e30 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  y(sqlite3_stmt*)
26e40 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
26e50 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54  F: Dynamically T
26e60 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63  yped Value Objec
26e70 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  t.** KEYWORDS: {
26e80 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
26e90 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74  3_value} {unprot
26ea0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
26eb0 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  lue}.**.** SQLit
26ec0 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74  e uses the sqlit
26ed0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
26ee0 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c  to represent all
26ef0 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20   values.** that 
26f00 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e  can be stored in
26f10 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c   a database tabl
26f20 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64  e. SQLite uses d
26f30 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a  ynamic typing.**
26f40 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20   for the values 
26f50 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c  it stores.  ^Val
26f60 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71  ues stored in sq
26f70 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
26f80 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e  cts.** can be in
26f90 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67  tegers, floating
26fa0 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73   point values, s
26fb0 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f  trings, BLOBs, o
26fc0 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e  r NULL..**.** An
26fd0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
26fe0 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74  bject may be eit
26ff0 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20  her "protected" 
27000 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22  or "unprotected"
27010 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66  ..** Some interf
27020 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70  aces require a p
27030 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
27040 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69  _value.  Other i
27050 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c  nterfaces.** wil
27060 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20  l accept either 
27070 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61  a protected or a
27080 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
27090 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20  lite3_value..** 
270a0 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20  Every interface 
270b0 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c  that accepts sql
270c0 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d  ite3_value argum
270d0 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a  ents specifies.*
270e0 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  * whether or not
270f0 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70   it requires a p
27100 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
27110 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  _value..**.** Th
27120 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74  e terms "protect
27130 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65  ed" and "unprote
27140 63 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77  cted" refer to w
27150 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a  hether or not.**
27160 20 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64   a mutex is held
27170 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d  .  An internal m
27180 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72  utex is held for
27190 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   a protected.** 
271a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
271b0 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65  ject but no mute
271c0 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e  x is held for an
271d0 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
271e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
271f0 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65  ject.  If SQLite
27200 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20   is compiled to 
27210 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  be single-thread
27220 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c  ed.** (with [SQL
27230 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
27240 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69  ] and with [sqli
27250 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
27260 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a  ] returning 0).*
27270 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69  * or if SQLite i
27280 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20  s run in one of 
27290 72 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f  reduced mutex mo
272a0 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  des .** [SQLITE_
272b0 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
272c0 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  EAD] or [SQLITE_
272d0 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
272e0 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72  AD].** then ther
272f0 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74  e is no distinct
27300 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74  ion between prot
27310 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74  ected and unprot
27320 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
27330 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61  _value objects a
27340 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75  nd they can be u
27350 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61  sed interchangea
27360 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a  bly.  However,.*
27370 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f  * for maximum co
27380 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69  de portability i
27390 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
273a0 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f   that applicatio
273b0 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65  ns.** still make
273c0 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e   the distinction
273d0 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74   between protect
273e0 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74  ed and unprotect
273f0 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
27400 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e  lue objects even
27410 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74   when not strict
27420 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  ly required..**.
27430 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
27440 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68  value objects th
27450 61 74 20 61 72 65 20 70 61 73 73 65 64 20 61 73  at are passed as
27460 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f   parameters into
27470 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   the.** implemen
27480 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69  tation of [appli
27490 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
274a0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72  QL functions] ar
274b0 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20  e protected..** 
274c0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
274d0 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ue object return
274e0 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
274f0 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
27500 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64  ] is unprotected
27510 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64  ..** Unprotected
27520 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
27530 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20  bjects may only 
27540 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20  be used with.** 
27550 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
27560 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71  value()] and [sq
27570 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
27580 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  ()]..** The [sql
27590 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20  ite3_value_blob 
275a0 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  | sqlite3_value_
275b0 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f  type()] family o
275c0 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  f.** interfaces 
275d0 72 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65  require protecte
275e0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
275f0 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65  objects..*/.type
27600 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73  def struct Mem s
27610 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f  qlite3_value;../
27620 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
27630 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74  QL Function Cont
27640 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ext Object.**.**
27650 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20   The context in 
27660 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e  which an SQL fun
27670 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69  ction executes i
27680 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a  s stored in an.*
27690 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  * sqlite3_contex
276a0 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f  t object.  ^A po
276b0 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69  inter to an sqli
276c0 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65  te3_context obje
276d0 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20  ct.** is always 
276e0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
276f0 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  to [application-
27700 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
27710 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61  tions]..** The a
27720 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
27730 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ed SQL function 
27740 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
27750 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a  ill pass this.**
27760 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68   pointer through
27770 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b   into calls to [
27780 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
27790 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73  nt | sqlite3_res
277a0 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ult()],.** [sqli
277b0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
277c0 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74  ntext()], [sqlit
277d0 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c  e3_user_data()],
277e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
277f0 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29  text_db_handle()
27800 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  ], [sqlite3_get_
27810 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61  auxdata()],.** a
27820 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73  nd/or [sqlite3_s
27830 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a  et_auxdata()]..*
27840 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
27850 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
27860 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
27870 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
27880 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65  F: Binding Value
27890 73 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74  s To Prepared St
278a0 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57  atements.** KEYW
278b0 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61  ORDS: {host para
278c0 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72  meter} {host par
278d0 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70  ameters} {host p
278e0 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a  arameter name}.*
278f0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c  * KEYWORDS: {SQL
27900 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c   parameter} {SQL
27910 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61   parameters} {pa
27920 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d  rameter binding}
27930 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20  .**.** ^(In the 
27940 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  SQL statement te
27950 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  xt input to [sql
27960 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
27970 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61  )] and its varia
27980 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73  nts,.** literals
27990 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64   may be replaced
279a0 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72   by a [parameter
279b0 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f  ] that matches o
279c0 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a  ne of following.
279d0 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a  ** templates:.**
279e0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
279f0 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e    ?.** <li>  ?NN
27a00 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a  N.** <li>  :VVV.
27a10 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a  ** <li>  @VVV.**
27a20 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c   <li>  $VVV.** <
27a30 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68  /ul>.**.** In th
27a40 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76  e templates abov
27a50 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74  e, NNN represent
27a60 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74  s an integer lit
27a70 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56  eral,.** and VVV
27a80 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61   represents an a
27a90 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e  lphanumeric iden
27aa0 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20  tifier.)^  ^The 
27ab0 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a  values of these.
27ac0 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 61  ** parameters (a
27ad0 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74  lso called "host
27ae0 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73   parameter names
27af0 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65  " or "SQL parame
27b00 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65  ters").** can be
27b10 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73   set using the s
27b20 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
27b30 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64  routines defined
27b40 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   here..**.** ^Th
27b50 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
27b60 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
27b70 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
27b80 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61  s is always.** a
27b90 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
27ba0 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f  [sqlite3_stmt] o
27bb0 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66  bject returned f
27bc0 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  rom.** [sqlite3_
27bd0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
27be0 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a   its variants..*
27bf0 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64  *.** ^The second
27c00 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
27c10 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51   index of the SQ
27c20 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  L parameter to b
27c30 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c  e set..** ^The l
27c40 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61  eftmost SQL para
27c50 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64  meter has an ind
27c60 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20  ex of 1.  ^When 
27c70 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a  the same named.*
27c80 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  * SQL parameter 
27c90 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61  is used more tha
27ca0 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61  n once, second a
27cb0 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a  nd subsequent.**
27cc0 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76   occurrences hav
27cd0 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78  e the same index
27ce0 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63   as the first oc
27cf0 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68  currence..** ^Th
27d00 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65  e index for name
27d10 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e  d parameters can
27d20 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73   be looked up us
27d30 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ing the.** [sqli
27d40 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
27d50 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20  er_index()] API 
27d60 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68  if desired.  ^Th
27d70 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22  e index.** for "
27d80 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73  ?NNN" parameters
27d90 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
27da0 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e   NNN..** ^The NN
27db0 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20  N value must be 
27dc0 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68  between 1 and th
27dd0 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  e [sqlite3_limit
27de0 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ()].** parameter
27df0 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56   [SQLITE_LIMIT_V
27e00 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20  ARIABLE_NUMBER] 
27e10 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20  (default value: 
27e20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  999)..**.** ^The
27e30 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
27e40 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20  is the value to 
27e50 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61  bind to the para
27e60 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68  meter..** ^If th
27e70 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
27e80 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
27e90 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69  d_text() or sqli
27ea0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
27eb0 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
27ec0 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 61  bind_blob() is a
27ed0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
27ee0 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  en the fourth pa
27ef0 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69 67  rameter.** is ig
27f00 6e 6f 72 65 64 20 61 6e 64 20 74 68 65 20 65 6e  nored and the en
27f10 64 20 72 65 73 75 6c 74 20 69 73 20 74 68 65 20  d result is the 
27f20 73 61 6d 65 20 61 73 20 73 71 6c 69 74 65 33 5f  same as sqlite3_
27f30 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a  bind_null()..**.
27f40 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f  ** ^(In those ro
27f50 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 65  utines that have
27f60 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65   a fourth argume
27f70 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73  nt, its value is
27f80 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
27f90 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 70  f bytes in the p
27fa0 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65  arameter.  To be
27fb0 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75   clear: the valu
27fc0 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  e is the.** numb
27fd0 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f  er of <u>bytes</
27fe0 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c  u> in the value,
27ff0 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20   not the number 
28000 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e  of characters.)^
28010 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72  .** ^If the four
28020 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
28030 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
28040 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  t() or sqlite3_b
28050 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20  ind_text16().** 
28060 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
28070 6e 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20  n the length of 
28080 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a  the string is.**
28090 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
280a0 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66  ytes up to the f
280b0 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
280c0 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ator..** If the 
280d0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
280e0 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
280f0 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65 67 61 74  _blob() is negat
28100 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65  ive, then.** the
28110 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
28120 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20  efined..** If a 
28130 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75  non-negative fou
28140 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
28150 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c   provided to sql
28160 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
28170 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  .** or sqlite3_b
28180 69 6e 64 5f 74 65 78 74 31 36 28 29 20 74 68 65  ind_text16() the
28190 6e 20 74 68 61 74 20 70 61 72 61 6d 65 74 65 72  n that parameter
281a0 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74   must be the byt
281b0 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65 72  e offset.** wher
281c0 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e  e the NUL termin
281d0 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75 72  ator would occur
281e0 20 61 73 73 75 6d 69 6e 67 20 74 68 65 20 73 74   assuming the st
281f0 72 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a  ring were NUL.**
28200 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66   terminated.  If
28210 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74   any NUL charact
28220 65 72 73 20 6f 63 63 75 72 20 61 74 20 62 79 74  ers occur at byt
28230 65 20 6f 66 66 73 65 74 73 20 6c 65 73 73 20 74  e offsets less t
28240 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75  han .** the valu
28250 65 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20  e of the fourth 
28260 70 61 72 61 6d 65 74 65 72 20 74 68 65 6e 20 74  parameter then t
28270 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72  he resulting str
28280 69 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a  ing value will.*
28290 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64  * contain embedd
282a0 65 64 20 4e 55 4c 73 2e 20 20 54 68 65 20 72 65  ed NULs.  The re
282b0 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69  sult of expressi
282c0 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74  ons involving st
282d0 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d  rings.** with em
282e0 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75  bedded NULs is u
282f0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
28300 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d  ^The fifth argum
28310 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ent to sqlite3_b
28320 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69  ind_blob(), sqli
28330 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c  te3_bind_text(),
28340 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   and.** sqlite3_
28350 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 69 73  bind_text16() is
28360 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 73   a destructor us
28370 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66  ed to dispose of
28380 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20   the BLOB or.** 
28390 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c  string after SQL
283a0 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64  ite has finished
283b0 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20   with it.  ^The 
283c0 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61  destructor is ca
283d0 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f  lled.** to dispo
283e0 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f  se of the BLOB o
283f0 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66  r string even if
28400 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c   the call to sql
28410 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
28420 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e  ,.** sqlite3_bin
28430 64 5f 74 65 78 74 28 29 2c 20 6f 72 20 73 71 6c  d_text(), or sql
28440 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
28450 28 29 20 66 61 69 6c 73 2e 20 20 0a 2a 2a 20 5e  () fails.  .** ^
28460 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67  If the fifth arg
28470 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20  ument is.** the 
28480 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53  special value [S
28490 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74  QLITE_STATIC], t
284a0 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d  hen SQLite assum
284b0 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69  es that the.** i
284c0 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e  nformation is in
284d0 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67   static, unmanag
284e0 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65  ed space and doe
284f0 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
28500 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74   freed..** ^If t
28510 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
28520 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20  t has the value 
28530 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e  [SQLITE_TRANSIEN
28540 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69  T], then.** SQLi
28550 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e  te makes its own
28560 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
28570 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69   the data immedi
28580 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a  ately, before.**
28590 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
285a0 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65  d_*() routine re
285b0 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  turns..**.** ^Th
285c0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a  e sqlite3_bind_z
285d0 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e  eroblob() routin
285e0 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f  e binds a BLOB o
285f0 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a  f length N that.
28600 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  ** is filled wit
28610 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65  h zeroes.  ^A ze
28620 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69  roblob uses a fi
28630 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65  xed amount of me
28640 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e  mory.** (just an
28650 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64   integer to hold
28660 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65   its size) while
28670 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f   it is being pro
28680 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62  cessed..** Zerob
28690 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65  lobs are intende
286a0 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c  d to serve as pl
286b0 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42  aceholders for B
286c0 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f  LOBs whose.** co
286d0 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77  ntent is later w
286e0 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20  ritten using.** 
286f0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70  [sqlite3_blob_op
28700 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c  en | incremental
28710 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69   BLOB I/O] routi
28720 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74  nes..** ^A negat
28730 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68  ive value for th
28740 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c  e zeroblob resul
28750 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e  ts in a zero-len
28760 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20  gth BLOB..**.** 
28770 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73  ^If any of the s
28780 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
28790 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
287a0 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20  led with a NULL 
287b0 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74  pointer.** for t
287c0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
287d0 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20  tement] or with 
287e0 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  a prepared state
287f0 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a  ment for which.*
28800 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
28810 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c  )] has been call
28820 65 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79  ed more recently
28830 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72   than [sqlite3_r
28840 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e  eset()],.** then
28850 20 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72   the call will r
28860 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49  eturn [SQLITE_MI
28870 53 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73  SUSE].  If any s
28880 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a  qlite3_bind_().*
28890 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73  * routine is pas
288a0 73 65 64 20 61 20 5b 70 72 65 70 61 72 65 64 20  sed a [prepared 
288b0 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
288c0 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  has been finaliz
288d0 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c  ed, the.** resul
288e0 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61  t is undefined a
288f0 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d  nd probably harm
28900 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64  ful..**.** ^Bind
28910 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65  ings are not cle
28920 61 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  ared by the [sql
28930 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f  ite3_reset()] ro
28940 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75  utine..** ^Unbou
28950 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  nd parameters ar
28960 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  e interpreted as
28970 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   NULL..**.** ^Th
28980 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
28990 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
289a0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
289b0 73 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a  success or an.**
289c0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66   [error code] if
289d0 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77   anything goes w
289e0 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54  rong..** ^[SQLIT
289f0 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75  E_RANGE] is retu
28a00 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61  rned if the para
28a10 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69  meter.** index i
28a20 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20  s out of range. 
28a30 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d   ^[SQLITE_NOMEM]
28a40 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
28a50 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a  malloc() fails..
28a60 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
28a70 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
28a80 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
28a90 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
28aa0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
28ab0 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  e()], and [sqlit
28ac0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
28ad0 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69  r_index()]..*/.i
28ae0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
28af0 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
28b00 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76  t*, int, const v
28b10 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69  oid*, int n, voi
28b20 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
28b30 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64  t sqlite3_bind_d
28b40 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  ouble(sqlite3_st
28b50 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65  mt*, int, double
28b60 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
28b70 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  ind_int(sqlite3_
28b80 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29  stmt*, int, int)
28b90 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
28ba0 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  nd_int64(sqlite3
28bb0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c  _stmt*, int, sql
28bc0 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74  ite3_int64);.int
28bd0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75   sqlite3_bind_nu
28be0 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ll(sqlite3_stmt*
28bf0 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69  , int);.int sqli
28c00 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71  te3_bind_text(sq
28c10 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
28c20 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  , const char*, i
28c30 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f  nt n, void(*)(vo
28c40 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
28c50 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73  e3_bind_text16(s
28c60 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
28c70 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
28c80 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
28c90 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
28ca0 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c  3_bind_value(sql
28cb0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
28cc0 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76   const sqlite3_v
28cd0 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
28ce0 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
28cf0 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
28d00 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f   int, int n);../
28d10 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
28d20 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72  umber Of SQL Par
28d30 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54  ameters.**.** ^T
28d40 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20  his routine can 
28d50 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20  be used to find 
28d60 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53  the number of [S
28d70 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a  QL parameters].*
28d80 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64  * in a [prepared
28d90 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51   statement].  SQ
28da0 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  L parameters are
28db0 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a   tokens of the.*
28dc0 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e  * form "?", "?NN
28dd0 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41  N", ":AAA", "$AA
28de0 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68  A", or "@AAA" th
28df0 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70  at serve as.** p
28e00 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20  laceholders for 
28e10 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20  values that are 
28e20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
28e30 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74  ob | bound].** t
28e40 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73  o the parameters
28e50 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65   at a later time
28e60 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72  ..**.** ^(This r
28e70 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20  outine actually 
28e80 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65  returns the inde
28e90 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74  x of the largest
28ea0 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20   (rightmost).** 
28eb0 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61  parameter. For a
28ec0 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20  ll forms except 
28ed0 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20  ?NNN, this will 
28ee0 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68  correspond to th
28ef0 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75  e.** number of u
28f00 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73  nique parameters
28f10 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73  .  If parameters
28f20 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72   of the ?NNN for
28f30 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74  m are used,.** t
28f40 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73  here may be gaps
28f50 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a   in the list.)^.
28f60 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
28f70 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
28f80 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
28f90 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
28fa0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
28fb0 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  ame()], and.** [
28fc0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
28fd0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
28fe0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
28ff0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
29000 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
29010 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
29020 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20  3REF: Name Of A 
29030 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a  Host Parameter.*
29040 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
29050 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
29060 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72  _name(P,N) inter
29070 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20  face returns.** 
29080 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
29090 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65  N-th [SQL parame
290a0 74 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65  ter] in the [pre
290b0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
290c0 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72   P..** ^(SQL par
290d0 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
290e0 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a  orm "?NNN" or ":
290f0 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f  AAA" or "@AAA" o
29100 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65  r "$AAA".** have
29110 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73   a name which is
29120 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e   the string "?NN
29130 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20  N" or ":AAA" or 
29140 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22  "@AAA" or "$AAA"
29150 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79  .** respectively
29160 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f  ..** In other wo
29170 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c  rds, the initial
29180 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22   ":" or "$" or "
29190 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20  @" or "?".** is 
291a0 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74  included as part
291b0 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a   of the name.)^.
291c0 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f  ** ^Parameters o
291d0 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77  f the form "?" w
291e0 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69  ithout a followi
291f0 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20  ng integer have 
29200 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61  no name.** and a
29210 72 65 20 72 65 66 65 72 72 65 64 20 74 6f 20 61  re referred to a
29220 73 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20  s "nameless" or 
29230 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d  "anonymous param
29240 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eters"..**.** ^T
29250 68 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61  he first host pa
29260 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69  rameter has an i
29270 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30  ndex of 1, not 0
29280 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
29290 76 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f  value N is out o
292a0 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68  f range or if th
292b0 65 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72  e N-th parameter
292c0 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c   is.** nameless,
292d0 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65   then NULL is re
292e0 74 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65  turned.  ^The re
292f0 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
29300 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54  .** always in UT
29310 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65  F-8 encoding eve
29320 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70  n if the named p
29330 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20  arameter was.** 
29340 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69  originally speci
29350 66 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69  fied as UTF-16 i
29360 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
29370 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  re16()] or.** [s
29380 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
29390 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65  _v2()]..**.** Se
293a0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
293b0 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
293c0 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
293d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
293e0 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
293f0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
29400 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
29410 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e  index()]..*/.con
29420 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
29430 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
29440 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
29450 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  t*, int);../*.**
29460 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78   CAPI3REF: Index
29470 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20   Of A Parameter 
29480 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d  With A Given Nam
29490 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20  e.**.** ^Return 
294a0 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20  the index of an 
294b0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69  SQL parameter gi
294c0 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e  ven its name.  ^
294d0 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c  The.** index val
294e0 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73  ue returned is s
294f0 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20  uitable for use 
29500 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  as the second.**
29510 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
29520 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
29530 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
29540 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73  .  ^A zero.** is
29550 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20   returned if no 
29560 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74  matching paramet
29570 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54  er is found.  ^T
29580 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  he parameter.** 
29590 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76  name must be giv
295a0 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e  en in UTF-8 even
295b0 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c   if the original
295c0 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61   statement.** wa
295d0 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20  s prepared from 
295e0 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e  UTF-16 text usin
295f0 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
29600 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  re16_v2()]..**.*
29610 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
29620 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
29630 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
29640 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
29650 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
29660 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
29670 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
29680 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
29690 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
296a0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
296b0 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  x(sqlite3_stmt*,
296c0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
296d0 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  me);../*.** CAPI
296e0 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20  3REF: Reset All 
296f0 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72  Bindings On A Pr
29700 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
29710 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79  .**.** ^Contrary
29720 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f   to the intuitio
29730 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69  n of many, [sqli
29740 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65  te3_reset()] doe
29750 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74  s not reset.** t
29760 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
29770 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73  _blob | bindings
29780 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64  ] on a [prepared
29790 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
297a0 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e  ^Use this routin
297b0 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68  e to reset all h
297c0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74  ost parameters t
297d0 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73  o NULL..*/.int s
297e0 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
297f0 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
29800 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
29810 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66  I3REF: Number Of
29820 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65   Columns In A Re
29830 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e  sult Set.**.** ^
29840 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65  Return the numbe
29850 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
29860 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72  the result set r
29870 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a  eturned by the.*
29880 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
29890 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f  ement]. ^This ro
298a0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20  utine returns 0 
298b0 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53  if pStmt is an S
298c0 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  QL.** statement 
298d0 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65  that does not re
298e0 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65  turn data (for e
298f0 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54  xample an [UPDAT
29900 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  E])..**.** See a
29910 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61  lso: [sqlite3_da
29920 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69  ta_count()].*/.i
29930 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
29940 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  n_count(sqlite3_
29950 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
29960 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
29970 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41  olumn Names In A
29980 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a   Result Set.**.*
29990 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
299a0 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d  s return the nam
299b0 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20  e assigned to a 
299c0 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d  particular colum
299d0 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75  n.** in the resu
299e0 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c  lt set of a [SEL
299f0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20  ECT] statement. 
29a00 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
29a10 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69  lumn_name().** i
29a20 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
29a30 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
29a40 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
29a50 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20  UTF-8 string.** 
29a60 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
29a70 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75  mn_name16() retu
29a80 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
29a90 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
29aa0 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72  ed.** UTF-16 str
29ab0 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74  ing.  ^The first
29ac0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
29ad0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
29ae0 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69  ement].** that i
29af0 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53  mplements the [S
29b00 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
29b10 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  . ^The second pa
29b20 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
29b30 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  * column number.
29b40 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20    ^The leftmost 
29b50 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72  column is number
29b60 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72   0..**.** ^The r
29b70 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70  eturned string p
29b80 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20  ointer is valid 
29b90 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65  until either the
29ba0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
29bb0 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74  ment].** is dest
29bc0 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65  royed by [sqlite
29bd0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
29be0 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65   until the state
29bf0 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69  ment is automati
29c00 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61  cally.** reprepa
29c10 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  red by the first
29c20 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
29c30 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20  3_step()] for a 
29c40 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a  particular run.*
29c50 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e  * or until the n
29c60 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73  ext call to.** s
29c70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
29c80 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  me() or sqlite3_
29c90 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20  column_name16() 
29ca0 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75  on the same colu
29cb0 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71  mn..**.** ^If sq
29cc0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66  lite3_malloc() f
29cd0 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20  ails during the 
29ce0 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69  processing of ei
29cf0 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  ther routine.** 
29d00 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72  (for example dur
29d10 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e  ing a conversion
29d20 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55   from UTF-8 to U
29d30 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a  TF-16) then a.**
29d40 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
29d50 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
29d60 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20   ^The name of a 
29d70 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73  result column is
29d80 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
29d90 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f  e "AS" clause fo
29da0 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e  r.** that column
29db0 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e  , if there is an
29dc0 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20   AS clause.  If 
29dd0 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63  there is no AS c
29de0 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68  lause.** then th
29df0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f  e name of the co
29e00 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66  lumn is unspecif
29e10 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e  ied and may chan
29e20 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72  ge from.** one r
29e30 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
29e40 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f   to the next..*/
29e50 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
29e60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
29e70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
29e80 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f  int N);.const vo
29e90 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
29ea0 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  mn_name16(sqlite
29eb0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b  3_stmt*, int N);
29ec0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
29ed0 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61  : Source Of Data
29ee0 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 75   In A Query Resu
29ef0 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  lt.**.** ^These 
29f00 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65  routines provide
29f10 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65   a means to dete
29f20 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62 61  rmine the databa
29f30 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a  se, table, and.*
29f40 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74  * table column t
29f50 68 61 74 20 69 73 20 74 68 65 20 6f 72 69 67 69  hat is the origi
29f60 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61  n of a particula
29f70 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  r result column 
29f80 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73  in.** [SELECT] s
29f90 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  tatement..** ^Th
29fa0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  e name of the da
29fb0 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20  tabase or table 
29fc0 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65  or column can be
29fd0 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20   returned as.** 
29fe0 65 69 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f  either a UTF-8 o
29ff0 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e  r UTF-16 string.
2a000 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65    ^The _database
2a010 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
2a020 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  n.** the databas
2a030 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62  e name, the _tab
2a040 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  le_ routines ret
2a050 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61  urn the table na
2a060 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f  me, and.** the o
2a070 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20  rigin_ routines 
2a080 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d  return the colum
2a090 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20  n name..** ^The 
2a0a0 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
2a0b0 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74  is valid until t
2a0c0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2a0d0 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72  tement] is destr
2a0e0 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73  oyed.** using [s
2a0f0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2a100 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  )] or until the 
2a110 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74  statement is aut
2a120 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65  omatically.** re
2a130 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20  prepared by the 
2a140 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73  first call to [s
2a150 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66  qlite3_step()] f
2a160 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
2a170 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20  run.** or until 
2a180 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61  the same informa
2a190 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65  tion is requeste
2a1a0 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20  d.** again in a 
2a1b0 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69  different encodi
2a1c0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e  ng..**.** ^The n
2a1d0 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72  ames returned ar
2a1e0 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75  e the original u
2a1f0 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20  n-aliased names 
2a200 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  of the.** databa
2a210 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63  se, table, and c
2a220 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  olumn..**.** ^Th
2a230 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
2a240 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66   to these interf
2a250 61 63 65 73 20 69 73 20 61 20 5b 70 72 65 70 61  aces is a [prepa
2a260 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
2a270 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69  ** ^These functi
2a280 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72  ons return infor
2a290 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65  mation about the
2a2a0 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75   Nth result colu
2a2b0 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  mn returned by.*
2a2c0 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c  * the statement,
2a2d0 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
2a2e0 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20  second function 
2a2f0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  argument..** ^Th
2a300 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75  e left-most colu
2a310 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66  mn is column 0 f
2a320 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  or these routine
2a330 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  s..**.** ^If the
2a340 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75   Nth column retu
2a350 72 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74  rned by the stat
2a360 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72  ement is an expr
2a370 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62  ession or.** sub
2a380 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74  query and is not
2a390 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c   a column value,
2a3a0 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65   then all of the
2a3b0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  se functions ret
2a3c0 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54  urn.** NULL.  ^T
2a3d0 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67  hese routine mig
2a3e0 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e  ht also return N
2a3f0 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20  ULL if a memory 
2a400 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
2a410 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74  .** occurs.  ^Ot
2a420 68 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65  herwise, they re
2a430 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  turn the name of
2a440 20 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61   the attached da
2a450 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a  tabase, table,.*
2a460 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74  * or column that
2a470 20 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f   query result co
2a480 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74  lumn was extract
2a490 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  ed from..**.** ^
2a4a0 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65  As with all othe
2a4b0 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74  r SQLite APIs, t
2a4c0 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73  hose whose names
2a4d0 20 65 6e 64 20 77 69 74 68 20 22 31 36 22 20 72   end with "16" r
2a4e0 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20  eturn.** UTF-16 
2a4f0 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20  encoded strings 
2a500 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66 75  and the other fu
2a510 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55  nctions return U
2a520 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  TF-8..**.** ^The
2a530 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79  se APIs are only
2a540 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68   available if th
2a550 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f  e library was co
2a560 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a  mpiled with the.
2a570 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  ** [SQLITE_ENABL
2a580 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54  E_COLUMN_METADAT
2a590 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f  A] C-preprocesso
2a5a0 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20  r symbol..**.** 
2a5b0 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74  If two or more t
2a5c0 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20  hreads call one 
2a5d0 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65  or more of these
2a5e0 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73   routines agains
2a5f0 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72  t the same.** pr
2a600 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2a610 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74   and column at t
2a620 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65  he same time the
2a630 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
2a640 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a  e.** undefined..
2a650 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20  **.** If two or 
2a660 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c  more threads cal
2a670 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a  l one or more.**
2a680 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2a690 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c  _database_name |
2a6a0 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61   column metadata
2a6b0 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20   interfaces].** 
2a6c0 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72  for the same [pr
2a6d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2a6e0 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c  ] and result col
2a6f0 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61  umn.** at the sa
2a700 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65  me time then the
2a710 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
2a720 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74  efined..*/.const
2a730 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
2a740 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
2a750 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
2a760 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
2a770 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
2a780 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
2a790 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2a7a0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61  ,int);.const cha
2a7b0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
2a7c0 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c  n_table_name(sql
2a7d0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
2a7e0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
2a7f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
2a800 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  e_name16(sqlite3
2a810 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
2a820 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
2a830 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
2a840 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
2a850 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
2a860 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
2a870 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36  mn_origin_name16
2a880 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2a890 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
2a8a0 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44  3REF: Declared D
2a8b0 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65  atatype Of A Que
2a8c0 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20  ry Result.**.** 
2a8d0 5e 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61  ^(The first para
2a8e0 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70  meter is a [prep
2a8f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
2a900 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74  .** If this stat
2a910 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45  ement is a [SELE
2a920 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  CT] statement an
2a930 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  d the Nth column
2a940 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72   of the.** retur
2a950 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f  ned result set o
2a960 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20  f that [SELECT] 
2a970 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d  is a table colum
2a980 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70  n (not an.** exp
2a990 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
2a9a0 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65  ery) then the de
2a9b0 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74  clared type of t
2a9c0 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75  he table.** colu
2a9d0 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  mn is returned.)
2a9e0 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63  ^  ^If the Nth c
2a9f0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
2aa00 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a  ult set is an.**
2aa10 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73   expression or s
2aa20 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20  ubquery, then a 
2aa30 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
2aa40 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68  returned..** ^Th
2aa50 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
2aa60 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d  g is always UTF-
2aa70 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a  8 encoded..**.**
2aa80 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20   ^(For example, 
2aa90 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61  given the databa
2aaa0 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a  se schema:.**.**
2aab0 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31   CREATE TABLE t1
2aac0 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a  (c1 VARIANT);.**
2aad0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c  .** and the foll
2aae0 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  owing statement 
2aaf0 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a  to be compiled:.
2ab00 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20  **.** SELECT c1 
2ab10 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b  + 1, c1 FROM t1;
2ab20 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  .**.** this rout
2ab30 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e  ine would return
2ab40 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52   the string "VAR
2ab50 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65  IANT" for the se
2ab60 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63  cond result.** c
2ab70 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e  olumn (i==1), an
2ab80 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  d a NULL pointer
2ab90 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72   for the first r
2aba0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d  esult column (i=
2abb0 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51  =0).)^.**.** ^SQ
2abc0 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69  Lite uses dynami
2abd0 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e  c run-time typin
2abe0 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63  g.  ^So just bec
2abf0 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a  ause a column.**
2ac00 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20   is declared to 
2ac10 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63  contain a partic
2ac20 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e  ular type does n
2ac30 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65  ot mean that the
2ac40 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20  .** data stored 
2ac50 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69  in that column i
2ac60 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65  s of the declare
2ac70 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20  d type.  SQLite 
2ac80 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74  is.** strongly t
2ac90 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79  yped, but the ty
2aca0 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20  ping is dynamic 
2acb0 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79  not static.  ^Ty
2acc0 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61  pe.** is associa
2acd0 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64  ted with individ
2ace0 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20  ual values, not 
2acf0 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e  with the contain
2ad00 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68  ers.** used to h
2ad10 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73  old those values
2ad20 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
2ad30 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2ad40 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33  decltype(sqlite3
2ad50 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
2ad60 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2ad70 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
2ad80 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2ad90 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ,int);../*.** CA
2ada0 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65  PI3REF: Evaluate
2adb0 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
2adc0 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20  t.**.** After a 
2add0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2ade0 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72  ent] has been pr
2adf0 65 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74  epared using eit
2ae00 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  her.** [sqlite3_
2ae10 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
2ae20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2ae30 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65  e16_v2()] or one
2ae40 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a   of the legacy.*
2ae50 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71  * interfaces [sq
2ae60 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
2ae70 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
2ae80 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20  pare16()], this 
2ae90 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74  function.** must
2aea0 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f   be called one o
2aeb0 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20  r more times to 
2aec0 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61  evaluate the sta
2aed0 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  tement..**.** Th
2aee0 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65  e details of the
2aef0 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65   behavior of the
2af00 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
2af10 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64  interface depend
2af20 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74  .** on whether t
2af30 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73  he statement was
2af40 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
2af50 74 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69  the newer "v2" i
2af60 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c  nterface.** [sql
2af70 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2af80 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
2af90 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
2afa0 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67  or the older leg
2afb0 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
2afc0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2afd0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
2afe0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20  3_prepare16()]. 
2aff0 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a   The use of the.
2b000 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65  ** new "v2" inte
2b010 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65  rface is recomme
2b020 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70  nded for new app
2b030 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68  lications but th
2b040 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
2b050 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69  rface will conti
2b060 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72  nue to be suppor
2b070 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74  ted..**.** ^In t
2b080 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
2b090 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20  ace, the return 
2b0a0 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69  value will be ei
2b0b0 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53  ther [SQLITE_BUS
2b0c0 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  Y],.** [SQLITE_D
2b0d0 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f  ONE], [SQLITE_RO
2b0e0 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  W], [SQLITE_ERRO
2b0f0 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d  R], or [SQLITE_M
2b100 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68  ISUSE]..** ^With
2b110 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
2b120 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20  ace, any of the 
2b130 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f  other [result co
2b140 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65  des] or.** [exte
2b150 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
2b160 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75  s] might be retu
2b170 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a  rned as well..**
2b180 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53  .** ^[SQLITE_BUS
2b190 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  Y] means that th
2b1a0 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e  e database engin
2b1b0 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20  e was unable to 
2b1c0 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64  acquire the.** d
2b1d0 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74  atabase locks it
2b1e0 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73   needs to do its
2b1f0 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73   job.  ^If the s
2b200 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43  tatement is a [C
2b210 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63  OMMIT].** or occ
2b220 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61  urs outside of a
2b230 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
2b240 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75  action, then you
2b250 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a   can retry the.*
2b260 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66  * statement.  If
2b270 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
2b280 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d  s not a [COMMIT]
2b290 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68   and occurs with
2b2a0 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69  in an.** explici
2b2b0 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68  t transaction th
2b2c0 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f  en you should ro
2b2d0 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73  llback the trans
2b2e0 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a  action before.**
2b2f0 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a   continuing..**.
2b300 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  ** ^[SQLITE_DONE
2b310 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
2b320 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66   statement has f
2b330 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e  inished executin
2b340 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c  g.** successfull
2b350 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70  y.  sqlite3_step
2b360 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  () should not be
2b370 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e   called again on
2b380 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a   this virtual.**
2b390 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74   machine without
2b3a0 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b   first calling [
2b3b0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2b3c0 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69   to reset the vi
2b3d0 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65  rtual.** machine
2b3e0 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69   back to its ini
2b3f0 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a  tial state..**.*
2b400 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74  * ^If the SQL st
2b410 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78  atement being ex
2b420 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61  ecuted returns a
2b430 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53  ny data, then [S
2b440 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73  QLITE_ROW].** is
2b450 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74   returned each t
2b460 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66  ime a new row of
2b470 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66   data is ready f
2b480 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79  or processing by
2b490 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20   the.** caller. 
2b4a0 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62  The values may b
2b4b0 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67  e accessed using
2b4c0 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63   the [column acc
2b4d0 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a  ess functions]..
2b4e0 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
2b4f0 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69  ) is called agai
2b500 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68  n to retrieve th
2b510 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61  e next row of da
2b520 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49  ta..**.** ^[SQLI
2b530 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20  TE_ERROR] means 
2b540 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20  that a run-time 
2b550 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61  error (such as a
2b560 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76   constraint.** v
2b570 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63  iolation) has oc
2b580 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33  curred.  sqlite3
2b590 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e  _step() should n
2b5a0 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61  ot be called aga
2b5b0 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e  in on.** the VM.
2b5c0 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f   More informatio
2b5d0 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62  n may be found b
2b5e0 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
2b5f0 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a  e3_errmsg()]..**
2b600 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61 63   ^With the legac
2b610 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d  y interface, a m
2b620 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72  ore specific err
2b630 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61  or code (for exa
2b640 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  mple,.** [SQLITE
2b650 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51  _INTERRUPT], [SQ
2b660 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53  LITE_SCHEMA], [S
2b670 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20  QLITE_CORRUPT], 
2b680 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a  and so forth).**
2b690 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64   can be obtained
2b6a0 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
2b6b0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e  ite3_reset()] on
2b6c0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
2b6d0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e  d statement].  ^
2b6e0 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  In the "v2" inte
2b6f0 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f  rface,.** the mo
2b700 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f  re specific erro
2b710 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e  r code is return
2b720 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73  ed directly by s
2b730 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a  qlite3_step()..*
2b740 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53  *.** [SQLITE_MIS
2b750 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  USE] means that 
2b760 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  the this routine
2b770 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70   was called inap
2b780 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20  propriately..** 
2b790 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63  Perhaps it was c
2b7a0 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70  alled on a [prep
2b7b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2b7c0 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65  that has.** alre
2b7d0 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65  ady been [sqlite
2b7e0 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
2b7f0 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e  alized] or on on
2b800 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72  e that had.** pr
2b810 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65  eviously returne
2b820 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  d [SQLITE_ERROR]
2b830 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45   or [SQLITE_DONE
2b840 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a  ].  Or it could.
2b850 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74  ** be the case t
2b860 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74  hat the same dat
2b870 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2b880 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62   is being used b
2b890 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65  y two or.** more
2b8a0 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20   threads at the 
2b8b0 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74  same moment in t
2b8c0 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61  ime..**.** For a
2b8d0 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  ll versions of S
2b8e0 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20  QLite up to and 
2b8f0 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33  including 3.6.23
2b900 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a  .1, a call to.**
2b910 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2b920 29 5d 20 77 61 73 20 72 65 71 75 69 72 65 64 20  )] was required 
2b930 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74  after sqlite3_st
2b940 65 70 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e  ep() returned an
2b950 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20  ything.** other 
2b960 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  than [SQLITE_ROW
2b970 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62  ] before any sub
2b980 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69  sequent invocati
2b990 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33  on of.** sqlite3
2b9a0 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72  _step().  Failur
2b9b0 65 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 70  e to reset the p
2b9c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2b9d0 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c  t using .** [sql
2b9e0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f  ite3_reset()] wo
2b9f0 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e  uld result in an
2ba00 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
2ba10 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20   return from.** 
2ba20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20  sqlite3_step(). 
2ba30 20 42 75 74 20 61 66 74 65 72 20 76 65 72 73 69   But after versi
2ba40 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c  on 3.6.23.1, sql
2ba50 69 74 65 33 5f 73 74 65 70 28 29 20 62 65 67 61  ite3_step() bega
2ba60 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71  n.** calling [sq
2ba70 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61  lite3_reset()] a
2ba80 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20  utomatically in 
2ba90 74 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63  this circumstanc
2baa0 65 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e  e rather.** than
2bab0 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49   returning [SQLI
2bac0 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69  TE_MISUSE].  Thi
2bad0 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65  s is not conside
2bae0 72 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c  red a compatibil
2baf0 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63  ity.** break bec
2bb00 61 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61  ause any applica
2bb10 74 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72  tion that ever r
2bb20 65 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54  eceives an SQLIT
2bb30 45 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a  E_MISUSE error.*
2bb40 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64  * is broken by d
2bb50 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20  efinition.  The 
2bb60 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54  [SQLITE_OMIT_AUT
2bb70 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d  ORESET] compile-
2bb80 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63  time option.** c
2bb90 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65  an be used to re
2bba0 73 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79  store the legacy
2bbb0 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a   behavior..**.**
2bbc0 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66   <b>Goofy Interf
2bbd0 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49  ace Alert:</b> I
2bbe0 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  n the legacy int
2bbf0 65 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69  erface, the sqli
2bc00 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50  te3_step().** AP
2bc10 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  I always returns
2bc20 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72   a generic error
2bc30 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45   code, [SQLITE_E
2bc40 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67  RROR], following
2bc50 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74   any.** error ot
2bc60 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
2bc70 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49  _BUSY] and [SQLI
2bc80 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75  TE_MISUSE].  You
2bc90 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73   must call.** [s
2bca0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2bcb0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
2bcc0 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72  lize()] in order
2bcd0 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20   to find one of 
2bce0 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20  the.** specific 
2bcf0 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68  [error codes] th
2bd00 61 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69  at better descri
2bd10 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a  bes the error..*
2bd20 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20  * We admit that 
2bd30 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20  this is a goofy 
2bd40 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f  design.  The pro
2bd50 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69  blem has been fi
2bd60 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  xed.** with the 
2bd70 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20  "v2" interface. 
2bd80 20 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20   If you prepare 
2bd90 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20  all of your SQL 
2bda0 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73  statements.** us
2bdb0 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69  ing either [sqli
2bdc0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2bdd0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
2bde0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e  epare16_v2()] in
2bdf0 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20  stead.** of the 
2be00 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f  legacy [sqlite3_
2be10 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b  prepare()] and [
2be20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2be30 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c  6()] interfaces,
2be40 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72  .** then the mor
2be50 65 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f  e specific [erro
2be60 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74  r codes] are ret
2be70 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a  urned directly.*
2be80 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65  * by sqlite3_ste
2be90 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66  p().  The use of
2bea0 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
2beb0 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ace is recommend
2bec0 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ed..*/.int sqlit
2bed0 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f  e3_step(sqlite3_
2bee0 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
2bef0 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
2bf00 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20  of columns in a 
2bf10 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a  result set.**.**
2bf20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
2bf30 74 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65  ta_count(P) inte
2bf40 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
2bf50 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
2bf60 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75  mns in the.** cu
2bf70 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65  rrent row of the
2bf80 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b   result set of [
2bf90 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2bfa0 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72  nt] P..** ^If pr
2bfb0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2bfc0 20 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65   P does not have
2bfd0 20 72 65 73 75 6c 74 73 20 72 65 61 64 79 20 74   results ready t
2bfe0 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61  o return.** (via
2bff0 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73   calls to the [s
2c000 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
2c010 74 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  t | sqlite3_colu
2c020 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e  mn_*()] of.** in
2c030 74 65 72 66 61 63 65 73 29 20 74 68 65 6e 20 73  terfaces) then s
2c040 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
2c050 74 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a  t(P) returns 0..
2c060 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2c070 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f  data_count(P) ro
2c080 75 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72  utine also retur
2c090 6e 73 20 30 20 69 66 20 50 20 69 73 20 61 20 4e  ns 0 if P is a N
2c0a0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20  ULL pointer..** 
2c0b0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
2c0c0 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69  a_count(P) routi
2c0d0 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20  ne returns 0 if 
2c0e0 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c  the previous cal
2c0f0 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
2c100 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e  _step](P) return
2c110 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  ed [SQLITE_DONE]
2c120 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
2c130 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a  data_count(P).**
2c140 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e   will return non
2c150 2d 7a 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75  -zero if previou
2c160 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  s call to [sqlit
2c170 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75  e3_step](P) retu
2c180 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  rned.** [SQLITE_
2c190 52 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20  ROW], except in 
2c1a0 74 68 65 20 63 61 73 65 20 6f 66 20 74 68 65 20  the case of the 
2c1b0 5b 50 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e  [PRAGMA incremen
2c1c0 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77  tal_vacuum].** w
2c1d0 68 65 72 65 20 69 74 20 61 6c 77 61 79 73 20 72  here it always r
2c1e0 65 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63  eturns zero sinc
2c1f0 65 20 65 61 63 68 20 73 74 65 70 20 6f 66 20 74  e each step of t
2c200 68 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a  hat multi-step.*
2c210 2a 20 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73  * pragma returns
2c220 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61   0 columns of da
2c230 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ta..**.** See al
2c240 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  so: [sqlite3_col
2c250 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a  umn_count()].*/.
2c260 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61  int sqlite3_data
2c270 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
2c280 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2c290 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75  .** CAPI3REF: Fu
2c2a0 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79  ndamental Dataty
2c2b0 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  pes.** KEYWORDS:
2c2c0 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a   SQLITE_TEXT.**.
2c2d0 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65  ** ^(Every value
2c2e0 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f   in SQLite has o
2c2f0 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61  ne of five funda
2c300 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73  mental datatypes
2c310 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
2c320 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e  <li> 64-bit sign
2c330 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c  ed integer.** <l
2c340 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66  i> 64-bit IEEE f
2c350 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75  loating point nu
2c360 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72  mber.** <li> str
2c370 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42  ing.** <li> BLOB
2c380 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a  .** <li> NULL.**
2c390 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54   </ul>)^.**.** T
2c3a0 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
2c3b0 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63  re codes for eac
2c3c0 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73  h of those types
2c3d0 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
2c3e0 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58  t the SQLITE_TEX
2c3f0 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61  T constant was a
2c400 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69  lso used in SQLi
2c410 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20  te version 2.** 
2c420 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79  for a completely
2c430 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69   different meani
2c440 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68  ng.  Software th
2c450 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74  at links against
2c460 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20   both.** SQLite 
2c470 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51  version 2 and SQ
2c480 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73  Lite version 3 s
2c490 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45  hould use SQLITE
2c4a0 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53  3_TEXT, not.** S
2c4b0 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23  QLITE_TEXT..*/.#
2c4c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
2c4d0 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65  TEGER  1.#define
2c4e0 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20   SQLITE_FLOAT   
2c4f0 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
2c500 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65  E_BLOB     4.#de
2c510 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c  fine SQLITE_NULL
2c520 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51       5.#ifdef SQ
2c530 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65  LITE_TEXT.# unde
2c540 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65  f SQLITE_TEXT.#e
2c550 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  lse.# define SQL
2c560 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23  ITE_TEXT     3.#
2c570 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51  endif.#define SQ
2c580 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33  LITE3_TEXT     3
2c590 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2c5a0 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20  : Result Values 
2c5b0 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20  From A Query.** 
2c5c0 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d  KEYWORDS: {colum
2c5d0 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
2c5e0 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ns}.**.** These 
2c5f0 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68  routines form th
2c600 65 20 22 72 65 73 75 6c 74 20 73 65 74 22 20 69  e "result set" i
2c610 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
2c620 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
2c630 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69  return informati
2c640 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c  on about a singl
2c650 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  e column of the 
2c660 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c  current.** resul
2c670 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79  t row of a query
2c680 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73  .  ^In every cas
2c690 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  e the first argu
2c6a0 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
2c6b0 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65  r.** to the [pre
2c6c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2c6d0 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65   that is being e
2c6e0 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73  valuated (the [s
2c6f0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a  qlite3_stmt*].**
2c700 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e   that was return
2c710 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
2c720 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
2c730 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72  r one of its var
2c740 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68  iants).** and th
2c750 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
2c760 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f  t is the index o
2c770 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72  f the column for
2c780 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69   which informati
2c790 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20  on.** should be 
2c7a0 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c  returned. ^The l
2c7b0 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f  eftmost column o
2c7c0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
2c7d0 20 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30   has the index 0
2c7e0 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72  ..** ^The number
2c7f0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
2c800 68 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65  he result can be
2c810 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e   determined usin
2c820 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  g.** [sqlite3_co
2c830 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a  lumn_count()]..*
2c840 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20  *.** If the SQL 
2c850 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e  statement does n
2c860 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69  ot currently poi
2c870 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f  nt to a valid ro
2c880 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20  w, or if the.** 
2c890 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20  column index is 
2c8a0 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68  out of range, th
2c8b0 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65  e result is unde
2c8c0 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20  fined..** These 
2c8d0 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c  routines may onl
2c8e0 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e  y be called when
2c8f0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
2c900 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
2c910 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
2c920 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
2c930 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68  E_ROW] and neith
2c940 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  er.** [sqlite3_r
2c950 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c  eset()] nor [sql
2c960 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2c970 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65   have been calle
2c980 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a  d subsequently..
2c990 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65  ** If any of the
2c9a0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
2c9b0 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71  called after [sq
2c9c0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
2c9d0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  r.** [sqlite3_fi
2c9e0 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74  nalize()] or aft
2c9f0 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  er [sqlite3_step
2ca00 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  ()] has returned
2ca10 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74  .** something ot
2ca20 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
2ca30 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c  _ROW], the resul
2ca40 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
2ca50 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33  ..** If [sqlite3
2ca60 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c  _step()] or [sql
2ca70 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
2ca80 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2ca90 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c  ze()].** are cal
2caa0 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65  led from a diffe
2cab0 72 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c  rent thread whil
2cac0 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72  e any of these r
2cad0 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70  outines.** are p
2cae0 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65  ending, then the
2caf0 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
2cb00 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
2cb10 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
2cb20 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65  n_type() routine
2cb30 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20   returns the.** 
2cb40 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20  [SQLITE_INTEGER 
2cb50 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d  | datatype code]
2cb60 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c   for the initial
2cb70 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66   data type.** of
2cb80 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75   the result colu
2cb90 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e  mn.  ^The return
2cba0 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20  ed value is one 
2cbb0 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  of [SQLITE_INTEG
2cbc0 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ER],.** [SQLITE_
2cbd0 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  FLOAT], [SQLITE_
2cbe0 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42  TEXT], [SQLITE_B
2cbf0 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  LOB], or [SQLITE
2cc00 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c  _NULL].  The val
2cc10 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  ue.** returned b
2cc20 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
2cc30 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20  _type() is only 
2cc40 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f  meaningful if no
2cc50 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73   type.** convers
2cc60 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72  ions have occurr
2cc70 65 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20  ed as described 
2cc80 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20  below.  After a 
2cc90 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c  type conversion,
2cca0 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65  .** the value re
2ccb0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
2ccc0 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
2ccd0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46  is undefined.  F
2cce0 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e  uture.** version
2ccf0 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20  s of SQLite may 
2cd00 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76  change the behav
2cd10 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63  ior of sqlite3_c
2cd20 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20  olumn_type().** 
2cd30 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65  following a type
2cd40 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a   conversion..**.
2cd50 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2cd60 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55  t is a BLOB or U
2cd70 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e  TF-8 string then
2cd80 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
2cd90 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72  umn_bytes().** r
2cda0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
2cdb0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2cdc0 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20  es in that BLOB 
2cdd0 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  or string..** ^I
2cde0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2cdf0 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c  a UTF-16 string,
2ce00 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
2ce10 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e  lumn_bytes() con
2ce20 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72  verts.** the str
2ce30 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64  ing to UTF-8 and
2ce40 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68   then returns th
2ce50 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2ce60 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  s..** ^If the re
2ce70 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69  sult is a numeri
2ce80 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c  c value then sql
2ce90 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2cea0 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c  s() uses.** [sql
2ceb0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
2cec0 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74   to convert that
2ced0 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d   value to a UTF-
2cee0 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74  8 string and ret
2cef0 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  urns.** the numb
2cf00 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
2cf10 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e  hat string..** ^
2cf20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2cf30 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69   NULL, then sqli
2cf40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2cf50 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e  () returns zero.
2cf60 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  .**.** ^If the r
2cf70 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20  esult is a BLOB 
2cf80 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  or UTF-16 string
2cf90 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
2cfa0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2cfb0 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65  ().** routine re
2cfc0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
2cfd0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
2cfe0 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  t BLOB or string
2cff0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
2d000 75 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20 73  ult is a UTF-8 s
2d010 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69  tring, then sqli
2d020 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2d030 31 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a  16() converts.**
2d040 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55   the string to U
2d050 54 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72  TF-16 and then r
2d060 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
2d070 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  r of bytes..** ^
2d080 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2d090 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65   a numeric value
2d0a0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
2d0b0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75  lumn_bytes16() u
2d0c0 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ses.** [sqlite3_
2d0d0 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63  snprintf()] to c
2d0e0 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75  onvert that valu
2d0f0 65 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74  e to a UTF-16 st
2d100 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
2d110 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
2d120 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
2d130 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
2d140 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c  he result is NUL
2d150 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  L, then sqlite3_
2d160 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2d170 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a   returns zero..*
2d180 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73  *.** ^The values
2d190 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
2d1a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2d1b0 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73  es()] and .** [s
2d1c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2d1d0 74 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20  tes16()] do not 
2d1e0 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f  include the zero
2d1f0 20 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20   terminators at 
2d200 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68  the end.** of th
2d210 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20  e string.  ^For 
2d220 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c  clarity: the val
2d230 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ues returned by.
2d240 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
2d250 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20  mn_bytes()] and 
2d260 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2d270 62 79 74 65 73 31 36 28 29 5d 20 61 72 65 20 74  bytes16()] are t
2d280 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
2d290 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72  bytes in the str
2d2a0 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d  ing, not the num
2d2b0 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
2d2c0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67  s..**.** ^String
2d2d0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  s returned by sq
2d2e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2d2f0 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
2d300 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c  column_text16(),
2d310 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73  .** even empty s
2d320 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61  trings, are alwa
2d330 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  ys zero-terminat
2d340 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e  ed.  ^The return
2d350 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  .** value from s
2d360 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2d370 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d  ob() for a zero-
2d380 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61  length BLOB is a
2d390 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
2d3a0 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74  *.** ^The object
2d3b0 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
2d3c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
2d3d0 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b  ue()] is an.** [
2d3e0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2d3f0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2d400 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74  t.  An unprotect
2d410 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2d420 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f   object.** may o
2d430 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68  nly be used with
2d440 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76   [sqlite3_bind_v
2d450 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  alue()] and [sql
2d460 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
2d470 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20  e()]..** If the 
2d480 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
2d490 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2d4a0 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ct returned by.*
2d4b0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2d4c0 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73  n_value()] is us
2d4d0 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20  ed in any other 
2d4e0 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63  way, including c
2d4f0 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69  alls.** to routi
2d500 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65  nes like [sqlite
2d510 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20  3_value_int()], 
2d520 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
2d530 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73  ext()],.** or [s
2d540 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
2d550 65 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20  es()], then the 
2d560 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
2d570 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  fined..**.** The
2d580 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65  se routines atte
2d590 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  mpt to convert t
2d5a0 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61  he value where a
2d5b0 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f  ppropriate.  ^Fo
2d5c0 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66  r.** example, if
2d5d0 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65   the internal re
2d5e0 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20  presentation is 
2d5f0 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74  FLOAT and a text
2d600 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65   result.** is re
2d610 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65  quested, [sqlite
2d620 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73  3_snprintf()] is
2d630 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79   used internally
2d640 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a   to perform the.
2d650 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75  ** conversion au
2d660 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28  tomatically.  ^(
2d670 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61  The following ta
2d680 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20  ble details the 
2d690 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74  conversions.** t
2d6a0 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a  hat are applied:
2d6b0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
2d6c0 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f  te>.** <table bo
2d6d0 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72  rder="1">.** <tr
2d6e0 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62  ><th> Internal<b
2d6f0 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75  r>Type <th> Requ
2d700 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74  ested<br>Type <t
2d710 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a  h>  Conversion.*
2d720 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  *.** <tr><td>  N
2d730 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  ULL    <td> INTE
2d740 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  GER   <td> Resul
2d750 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74  t is 0.** <tr><t
2d760 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
2d770 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
2d780 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a  Result is 0.0.**
2d790 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
2d7a0 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
2d7b0 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
2d7c0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
2d7d0 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
2d7e0 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
2d7f0 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
2d800 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
2d810 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
2d820 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  R  <td>  FLOAT  
2d830 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66    <td> Convert f
2d840 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66  rom integer to f
2d850 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  loat.** <tr><td>
2d860 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
2d870 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53   TEXT    <td> AS
2d880 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  CII rendering of
2d890 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20   the integer.** 
2d8a0 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
2d8b0 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
2d8c0 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e   <td> Same as IN
2d8d0 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c  TEGER->TEXT.** <
2d8e0 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
2d8f0 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
2d900 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f  <td> Convert fro
2d910 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67  m float to integ
2d920 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  er.** <tr><td>  
2d930 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54  FLOAT   <td>   T
2d940 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49  EXT    <td> ASCI
2d950 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  I rendering of t
2d960 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e  he float.** <tr>
2d970 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
2d980 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
2d990 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d  > Same as FLOAT-
2d9a0 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64  >TEXT.** <tr><td
2d9b0 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
2d9c0 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 55  INTEGER   <td> U
2d9d0 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72  se atoi().** <tr
2d9e0 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
2d9f0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
2da00 64 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a  d> Use atof().**
2da10 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
2da20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
2da30 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65    <td> No change
2da40 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
2da50 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  OB    <td> INTEG
2da60 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  ER   <td> Conver
2da70 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75  t to TEXT then u
2da80 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72  se atoi().** <tr
2da90 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
2daa0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
2dab0 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45  d> Convert to TE
2dac0 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66  XT then use atof
2dad0 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
2dae0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54  BLOB    <td>   T
2daf0 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20  EXT    <td> Add 
2db00 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  a zero terminato
2db10 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c  r if needed.** <
2db20 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f  /table>.** </blo
2db30 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
2db40 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65   The table above
2db50 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65   makes reference
2db60 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c   to standard C l
2db70 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73  ibrary functions
2db80 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61   atoi().** and a
2db90 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64  tof().  SQLite d
2dba0 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75  oes not really u
2dbb0 73 65 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  se these functio
2dbc0 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a  ns.  It has its.
2dbd0 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e  ** own equivalen
2dbe0 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69  t internal routi
2dbf0 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29  nes.  The atoi()
2dc00 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65   and atof() name
2dc10 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e  s are.** used in
2dc20 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62   the table for b
2dc30 72 65 76 69 74 79 20 61 6e 64 20 62 65 63 61 75  revity and becau
2dc40 73 65 20 74 68 65 79 20 61 72 65 20 66 61 6d 69  se they are fami
2dc50 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20  liar to most.** 
2dc60 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a  C programmers..*
2dc70 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77  *.** Note that w
2dc80 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73  hen type convers
2dc90 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e  ions occur, poin
2dca0 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79  ters returned by
2dcb0 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20   prior.** calls 
2dcc0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
2dcd0 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65  n_blob(), sqlite
2dce0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
2dcf0 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74   and/or.** sqlit
2dd00 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2dd10 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69  () may be invali
2dd20 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63  dated..** Type c
2dd30 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70  onversions and p
2dd40 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74  ointer invalidat
2dd50 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72  ions might occur
2dd60 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f  .** in the follo
2dd70 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a  wing cases:.**.*
2dd80 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  * <ul>.** <li> T
2dd90 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
2dda0 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64  nt is a BLOB and
2ddb0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2ddc0 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20  text() or.**    
2ddd0 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
2dde0 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c  _text16() is cal
2ddf0 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72  led.  A zero-ter
2de00 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a  minator might.**
2de10 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65        need to be
2de20 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74   added to the st
2de30 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c  ring.</li>.** <l
2de40 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
2de50 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20  ontent is UTF-8 
2de60 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33  text and sqlite3
2de70 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2de80 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
2de90 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2dea0 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  16() is called. 
2deb0 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73   The content mus
2dec0 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a  t be converted.*
2ded0 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36  *      to UTF-16
2dee0 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  .</li>.** <li> T
2def0 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
2df00 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78  nt is UTF-16 tex
2df10 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  t and sqlite3_co
2df20 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a  lumn_bytes() or.
2df30 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
2df40 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73  column_text() is
2df50 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f   called.  The co
2df60 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f  ntent must be co
2df70 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20  nverted.**      
2df80 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a  to UTF-8.</li>.*
2df90 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43  * </ul>.**.** ^C
2dfa0 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65  onversions betwe
2dfb0 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20  en UTF-16be and 
2dfc0 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77  UTF-16le are alw
2dfd0 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63  ays done in plac
2dfe0 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20  e and do.** not 
2dff0 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69  invalidate a pri
2e000 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75  or pointer, thou
2e010 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65  gh of course the
2e020 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
2e030 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74  buffer.** that t
2e040 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72  he prior pointer
2e050 20 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c   references will
2e060 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66   have been modif
2e070 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64  ied.  Other kind
2e080 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69  s.** of conversi
2e090 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70  on are done in p
2e0a0 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20  lace when it is 
2e0b0 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f  possible, but so
2e0c0 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20  metimes they.** 
2e0d0 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65  are not possible
2e0e0 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61   and in those ca
2e0f0 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  ses prior pointe
2e100 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74  rs are invalidat
2e110 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61  ed..**.** The sa
2e120 66 65 73 74 20 61 6e 64 20 65 61 73 69 65 73 74  fest and easiest
2e130 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c   to remember pol
2e140 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65  icy is to invoke
2e150 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a   these routines.
2e160 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65  ** in one of the
2e170 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a   following ways:
2e180 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20  .**.** <ul>.**  
2e190 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
2e1a0 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77  mn_text() follow
2e1b0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
2e1c0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69  lumn_bytes()</li
2e1d0 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
2e1e0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
2e1f0 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
2e200 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2e210 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e  ()</li>.**  <li>
2e220 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2e230 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64  ext16() followed
2e240 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
2e250 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69  mn_bytes16()</li
2e260 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  >.** </ul>.**.**
2e270 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
2e280 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c   you should call
2e290 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2e2a0 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  text(),.** sqlit
2e2b0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
2e2c0 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  , or sqlite3_col
2e2d0 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72  umn_text16() fir
2e2e0 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20  st to force the 
2e2f0 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74  result.** into t
2e300 68 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61  he desired forma
2e310 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73  t, then invoke s
2e320 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2e330 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  tes() or.** sqli
2e340 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2e350 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65  16() to find the
2e360 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73   size of the res
2e370 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78  ult.  Do not mix
2e380 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c   calls.** to sql
2e390 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2e3a0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  () or sqlite3_co
2e3b0 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68  lumn_blob() with
2e3c0 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c   calls to.** sql
2e3d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2e3e0 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f  s16(), and do no
2e3f0 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73  t mix calls to s
2e400 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2e410 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63  xt16().** with c
2e420 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
2e430 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a  column_bytes()..
2e440 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74  **.** ^The point
2e450 65 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 65  ers returned are
2e460 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74   valid until a t
2e470 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f  ype conversion o
2e480 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63  ccurs as.** desc
2e490 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20  ribed above, or 
2e4a0 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73  until [sqlite3_s
2e4b0 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  tep()] or [sqlit
2e4c0 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a  e3_reset()] or.*
2e4d0 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
2e4e0 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ize()] is called
2e4f0 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73  .  ^The memory s
2e500 70 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c  pace used to hol
2e510 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64  d strings.** and
2e520 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20   BLOBs is freed 
2e530 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
2e540 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61  Do <b>not</b> pa
2e550 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20  ss the pointers 
2e560 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c  returned.** [sql
2e570 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
2e580 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f  ()], [sqlite3_co
2e590 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74  lumn_text()], et
2e5a0 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69  c. into.** [sqli
2e5b0 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a  te3_free()]..**.
2e5c0 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79  ** ^(If a memory
2e5d0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
2e5e0 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20  r occurs during 
2e5f0 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  the evaluation o
2e600 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73  f any.** of thes
2e610 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65  e routines, a de
2e620 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72  fault value is r
2e630 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65  eturned.  The de
2e640 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69  fault value.** i
2e650 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74  s either the int
2e660 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61  eger 0, the floa
2e670 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65  ting point numbe
2e680 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c  r 0.0, or a NULL
2e690 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75  .** pointer.  Su
2e6a0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
2e6b0 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  o [sqlite3_errco
2e6c0 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  de()] will retur
2e6d0 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  n.** [SQLITE_NOM
2e6e0 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20  EM].)^.*/.const 
2e6f0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
2e700 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65  lumn_blob(sqlite
2e710 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2e720 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
2e730 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c  column_bytes(sql
2e740 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2e750 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
2e760 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2e770 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2e780 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62   int iCol);.doub
2e790 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  le sqlite3_colum
2e7a0 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  n_double(sqlite3
2e7b0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2e7c0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
2e7d0 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65  olumn_int(sqlite
2e7e0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2e7f0 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  l);.sqlite3_int6
2e800 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  4 sqlite3_column
2e810 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73  _int64(sqlite3_s
2e820 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2e830 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20  .const unsigned 
2e840 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2e850 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65  lumn_text(sqlite
2e860 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2e870 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  l);.const void *
2e880 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2e890 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ext16(sqlite3_st
2e8a0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2e8b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
2e8c0 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  mn_type(sqlite3_
2e8d0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2e8e0 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  ;.sqlite3_value 
2e8f0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2e900 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74  value(sqlite3_st
2e910 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2e920 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2e930 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61   Destroy A Prepa
2e940 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  red Statement Ob
2e950 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ject.**.** ^The 
2e960 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2e970 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
2e980 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20  alled to delete 
2e990 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2e9a0 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74  ement]..** ^If t
2e9b0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65  he most recent e
2e9c0 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65  valuation of the
2e9d0 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75   statement encou
2e9e0 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73  ntered no errors
2e9f0 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74  .** or if the st
2ea00 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72  atement is never
2ea10 20 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c   been evaluated,
2ea20 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69   then sqlite3_fi
2ea30 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73  nalize() returns
2ea40 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20  .** SQLITE_OK.  
2ea50 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
2ea60 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  ent evaluation o
2ea70 66 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61  f statement S fa
2ea80 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71  iled, then.** sq
2ea90 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53  lite3_finalize(S
2eaa0 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 61 70  ) returns the ap
2eab0 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72  propriate [error
2eac0 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78   code] or.** [ex
2ead0 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
2eae0 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  e]..**.** ^The s
2eaf0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2eb00 53 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62  S) routine can b
2eb10 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20  e called at any 
2eb20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20  point during.** 
2eb30 74 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f  the life cycle o
2eb40 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  f [prepared stat
2eb50 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66  ement] S:.** bef
2eb60 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20  ore statement S 
2eb70 69 73 20 65 76 65 72 20 65 76 61 6c 75 61 74 65  is ever evaluate
2eb80 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20  d, after.** one 
2eb90 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f  or more calls to
2eba0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2ebb0 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79  )], or after any
2ebc0 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c   call.** to [sql
2ebd0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67  ite3_step()] reg
2ebe0 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
2ebf0 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74  er or not the st
2ec00 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63  atement has.** c
2ec10 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69  ompleted executi
2ec20 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b  on..**.** ^Invok
2ec30 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  ing sqlite3_fina
2ec40 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c  lize() on a NULL
2ec50 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61   pointer is a ha
2ec60 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a  rmless no-op..**
2ec70 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
2ec80 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a  ion must finaliz
2ec90 65 20 65 76 65 72 79 20 5b 70 72 65 70 61 72 65  e every [prepare
2eca0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20  d statement] in 
2ecb0 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a  order to avoid.*
2ecc0 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73  * resource leaks
2ecd0 2e 20 20 49 74 20 69 73 20 61 20 67 72 69 65 76  .  It is a griev
2ece0 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68  ous error for th
2ecf0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f  e application to
2ed00 20 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61   try to use.** a
2ed10 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2ed20 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73  ent after it has
2ed30 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e   been finalized.
2ed40 20 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70    Any use of a p
2ed50 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65  repared.** state
2ed60 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61  ment after it ha
2ed70 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64  s been finalized
2ed80 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75   can result in u
2ed90 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20  ndefined and.** 
2eda0 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61  undesirable beha
2edb0 76 69 6f 72 20 73 75 63 68 20 61 73 20 73 65 67  vior such as seg
2edc0 66 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20  faults and heap 
2edd0 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69  corruption..*/.i
2ede0 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  nt sqlite3_final
2edf0 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ize(sqlite3_stmt
2ee00 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
2ee10 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74   CAPI3REF: Reset
2ee20 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
2ee30 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a  ement Object.**.
2ee40 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
2ee50 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20  eset() function 
2ee60 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73  is called to res
2ee70 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  et a [prepared s
2ee80 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a  tatement].** obj
2ee90 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20  ect back to its 
2eea0 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72  initial state, r
2eeb0 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78  eady to be re-ex
2eec0 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20  ecuted..** ^Any 
2eed0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61  SQL statement va
2eee0 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64  riables that had
2eef0 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f   values bound to
2ef00 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74   them using.** t
2ef10 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
2ef20 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
2ef30 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65  bind_*() API] re
2ef40 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65  tain their value
2ef50 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74  s..** Use [sqlit
2ef60 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
2ef70 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  s()] to reset th
2ef80 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a  e bindings..**.*
2ef90 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
2efa0 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66  reset(S)] interf
2efb0 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b  ace resets the [
2efc0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2efd0 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f  nt] S.** back to
2efe0 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
2eff0 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a  f its program..*
2f000 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  *.** ^If the mos
2f010 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
2f020 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
2f030 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70  )] for the.** [p
2f040 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2f050 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53  t] S returned [S
2f060 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53  QLITE_ROW] or [S
2f070 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20  QLITE_DONE],.** 
2f080 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73  or if [sqlite3_s
2f090 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65  tep(S)] has neve
2f0a0 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61  r before been ca
2f0b0 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68  lled on S,.** th
2f0c0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  en [sqlite3_rese
2f0d0 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53  t(S)] returns [S
2f0e0 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a  QLITE_OK]..**.**
2f0f0 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
2f100 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
2f110 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66  lite3_step(S)] f
2f120 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  or the.** [prepa
2f130 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2f140 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72   indicated an er
2f150 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71  ror, then.** [sq
2f160 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
2f170 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f  returns an appro
2f180 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f  priate [error co
2f190 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  de]..**.** ^The 
2f1a0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
2f1b0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65  )] interface doe
2f1c0 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
2f1d0 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e   values.** of an
2f1e0 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  y [sqlite3_bind_
2f1f0 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f  blob|bindings] o
2f200 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  n the [prepared 
2f210 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f  statement] S..*/
2f220 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73  .int sqlite3_res
2f230 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  et(sqlite3_stmt 
2f240 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
2f250 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65  CAPI3REF: Create
2f260 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c   Or Redefine SQL
2f270 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45   Functions.** KE
2f280 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f  YWORDS: {functio
2f290 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69  n creation routi
2f2a0 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  nes}.** KEYWORDS
2f2b0 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  : {application-d
2f2c0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
2f2d0 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ion}.** KEYWORDS
2f2e0 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  : {application-d
2f2f0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
2f300 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ions}.**.** ^The
2f310 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f  se functions (co
2f320 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e  llectively known
2f330 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72   as "function cr
2f340 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22  eation routines"
2f350 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f  ).** are used to
2f360 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f   add SQL functio
2f370 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73  ns or aggregates
2f380 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20   or to redefine 
2f390 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20  the behavior.** 
2f3a0 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20  of existing SQL 
2f3b0 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67  functions or agg
2f3c0 72 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e  regates.  The on
2f3d0 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73 20 62  ly differences b
2f3e0 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20  etween.** these 
2f3f0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68 65  routines are the
2f400 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65   text encoding e
2f410 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74  xpected for.** t
2f420 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
2f430 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66  ter (the name of
2f440 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65   the function be
2f450 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20  ing created).** 
2f460 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63 65  and the presence
2f470 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61   or absence of a
2f480 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c   destructor call
2f490 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20  back for.** the 
2f4a0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
2f4b0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
2f4c0 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  ^The first param
2f4d0 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 74  eter is the [dat
2f4e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2f4f0 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 53  ] to which the S
2f500 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  QL.** function i
2f510 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20  s to be added.  
2f520 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69  ^If an applicati
2f530 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61  on uses more tha
2f540 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a  n one database.*
2f550 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65  * connection the
2f560 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
2f570 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
2f580 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 65  ons must be adde
2f590 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74  d.** to each dat
2f5a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2f5b0 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a   separately..**.
2f5c0 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  ** ^The second p
2f5d0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
2f5e0 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20  name of the SQL 
2f5f0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63  function to be c
2f600 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64  reated or.** red
2f610 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65  efined.  ^The le
2f620 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65  ngth of the name
2f630 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32   is limited to 2
2f640 35 35 20 62 79 74 65 73 20 69 6e 20 61 20 55 54  55 bytes in a UT
2f650 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74  F-8.** represent
2f660 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65  ation, exclusive
2f670 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72   of the zero-ter
2f680 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20  minator.  ^Note 
2f690 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a  that the name.**
2f6a0 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73   length limit is
2f6b0 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c   in UTF-8 bytes,
2f6c0 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 20   not characters 
2f6d0 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65 73  nor UTF-16 bytes
2f6e0 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65  .  .** ^Any atte
2f6f0 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20  mpt to create a 
2f700 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
2f710 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77  longer name.** w
2f720 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53  ill result in [S
2f730 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65  QLITE_MISUSE] be
2f740 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a  ing returned..**
2f750 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70  .** ^The third p
2f760 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a  arameter (nArg).
2f770 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ** is the number
2f780 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68   of arguments th
2f790 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  at the SQL funct
2f7a0 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
2f7b0 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74  ate takes. ^If t
2f7c0 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73  his parameter is
2f7d0 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51   -1, then the SQ
2f7e0 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
2f7f0 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74   aggregate may t
2f800 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f  ake any number o
2f810 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77  f arguments betw
2f820 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69  een 0 and the li
2f830 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73  mit.** set by [s
2f840 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53  qlite3_limit]([S
2f850 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
2f860 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20  TION_ARG]).  If 
2f870 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72  the third.** par
2f880 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20 74  ameter is less t
2f890 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65  han -1 or greate
2f8a0 72 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20  r than 127 then 
2f8b0 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a  the behavior is.
2f8c0 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  ** undefined..**
2f8d0 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20  .** ^The fourth 
2f8e0 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74  parameter, eText
2f8f0 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77  Rep, specifies w
2f900 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  hat.** [SQLITE_U
2f910 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64  TF8 | text encod
2f920 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75  ing] this SQL fu
2f930 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66  nction prefers f
2f940 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65  or.** its parame
2f950 74 65 72 73 2e 20 20 45 76 65 72 79 20 53 51 4c  ters.  Every SQL
2f960 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
2f970 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 62 65  entation must be
2f980 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a   able to work.**
2f990 20 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46   with UTF-8, UTF
2f9a0 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36  -16le, or UTF-16
2f9b0 62 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d  be.  But some im
2f9c0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61  plementations ma
2f9d0 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66  y be.** more eff
2f9e0 69 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20  icient with one 
2f9f0 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e  encoding than an
2fa00 6f 74 68 65 72 2e 20 20 5e 41 6e 20 61 70 70 6c  other.  ^An appl
2fa10 69 63 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20 69  ication may.** i
2fa20 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72  nvoke sqlite3_cr
2fa30 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20  eate_function() 
2fa40 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
2fa50 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d  e_function16() m
2fa60 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73  ultiple.** times
2fa70 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 66   with the same f
2fa80 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68  unction but with
2fa90 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65   different value
2faa0 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a  s of eTextRep..*
2fab0 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65  * ^When multiple
2fac0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
2fad0 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e   of the same fun
2fae0 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61  ction are availa
2faf0 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77  ble, SQLite.** w
2fb00 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65  ill pick the one
2fb10 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74   that involves t
2fb20 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20  he least amount 
2fb30 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69  of data conversi
2fb40 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20  on..** If there 
2fb50 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65  is only a single
2fb60 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2fb70 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63  which does not c
2fb80 61 72 65 20 77 68 61 74 20 74 65 78 74 0a 2a 2a  are what text.**
2fb90 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65   encoding is use
2fba0 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72  d, then the four
2fbb0 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  th argument shou
2fbc0 6c 64 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e  ld be [SQLITE_AN
2fbd0 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  Y]..**.** ^(The 
2fbe0 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20  fifth parameter 
2fbf0 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20  is an arbitrary 
2fc00 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d  pointer.  The im
2fc10 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
2fc20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  the.** function 
2fc30 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20  can gain access 
2fc40 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20  to this pointer 
2fc50 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75  using [sqlite3_u
2fc60 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a  ser_data()].)^.*
2fc70 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c  *.** ^The sixth,
2fc80 20 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67   seventh and eig
2fc90 68 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20  hth parameters, 
2fca0 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64  xFunc, xStep and
2fcb0 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20   xFinal, are.** 
2fcc0 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61  pointers to C-la
2fcd0 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73  nguage functions
2fce0 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20   that implement 
2fcf0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2fd00 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
2fd10 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20  . ^A scalar SQL 
2fd20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
2fd30 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  s an implementat
2fd40 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63  ion of the xFunc
2fd50 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c  .** callback onl
2fd60 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  y; NULL pointers
2fd70 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20   must be passed 
2fd80 61 73 20 74 68 65 20 78 53 74 65 70 20 61 6e 64  as the xStep and
2fd90 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d   xFinal.** param
2fda0 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65  eters. ^An aggre
2fdb0 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
2fdc0 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d  n requires an im
2fdd0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
2fde0 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69  xStep.** and xFi
2fdf0 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69  nal and NULL poi
2fe00 6e 74 65 72 20 6d 75 73 74 20 62 65 20 70 61 73  nter must be pas
2fe10 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e  sed for xFunc. ^
2fe20 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69  To delete an exi
2fe30 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e  sting.** SQL fun
2fe40 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
2fe50 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f  te, pass NULL po
2fe60 69 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74  inters for all t
2fe70 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  hree function.**
2fe80 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a   callbacks..**.*
2fe90 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68  * ^(If the ninth
2fea0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
2feb0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2fec0 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f  ction_v2() is no
2fed0 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20  t NULL,.** then 
2fee0 69 74 20 69 73 20 64 65 73 74 72 75 63 74 6f 72  it is destructor
2fef0 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61   for the applica
2ff00 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
2ff10 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72  r. .** The destr
2ff20 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64  uctor is invoked
2ff30 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69   when the functi
2ff40 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65  on is deleted, e
2ff50 69 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a  ither by being.*
2ff60 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20  * overloaded or 
2ff70 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  when the databas
2ff80 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  e connection clo
2ff90 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64  ses.)^.** ^The d
2ffa0 65 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73  estructor is als
2ffb0 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65  o invoked if the
2ffc0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69   call to.** sqli
2ffd0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2ffe0 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a  ion_v2() fails..
2fff0 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73  ** ^When the des
30000 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b  tructor callback
30010 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70 61   of the tenth pa
30020 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b  rameter is invok
30030 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73  ed, it.** is pas
30040 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67  sed a single arg
30050 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
30060 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70   copy of the app
30070 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a  lication data .*
30080 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20  * pointer which 
30090 77 61 73 20 74 68 65 20 66 69 66 74 68 20 70 61  was the fifth pa
300a0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
300b0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
300c0 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  on_v2()..**.** ^
300d0 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 20  It is permitted 
300e0 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74  to register mult
300f0 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
30100 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
30110 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69  .** functions wi
30120 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  th the same name
30130 20 62 75 74 20 77 69 74 68 20 65 69 74 68 65 72   but with either
30140 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65   differing numbe
30150 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e  rs of.** argumen
30160 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20  ts or differing 
30170 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
30180 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69  ncodings.  ^SQLi
30190 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74  te will use.** t
301a0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
301b0 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73  n that most clos
301c0 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20  ely matches the 
301d0 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65  way in which the
301e0 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  .** SQL function
301f0 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75   is used.  ^A fu
30200 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
30210 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e  ation with a non
30220 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72  -negative.** nAr
30230 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  g parameter is a
30240 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 68   better match th
30250 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d  an a function im
30260 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74  plementation wit
30270 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20  h.** a negative 
30280 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69  nArg.  ^A functi
30290 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 65  on where the pre
302a0 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
302b0 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20  ding.** matches 
302c0 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 63  the database enc
302d0 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 65  oding is a bette
302e0 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20  r.** match than 
302f0 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  a function where
30300 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73   the encoding is
30310 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a   different.  .**
30320 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65   ^A function whe
30330 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
30340 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 62 65  difference is be
30350 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e  tween UTF16le an
30360 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20  d UTF16be.** is 
30370 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74  a closer match t
30380 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  han a function w
30390 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
303a0 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a  g difference is.
303b0 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38 20  ** between UTF8 
303c0 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a  and UTF16..**.**
303d0 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74   ^Built-in funct
303e0 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72  ions may be over
303f0 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61 70  loaded by new ap
30400 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
30410 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a  d functions..**.
30420 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69  ** ^An applicati
30430 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
30440 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64  ion is permitted
30450 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a   to call other.*
30460 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  * SQLite interfa
30470 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73  ces.  However, s
30480 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e  uch calls must n
30490 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20  ot.** close the 
304a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
304b0 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65  ion nor finalize
304c0 20 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 72   or reset the pr
304d0 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
304e0 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 65  ent in which the
304f0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
30500 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ning..*/.int sql
30510 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
30520 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20  tion(.  sqlite3 
30530 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  *db,.  const cha
30540 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  r *zFunctionName
30550 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
30560 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
30570 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f  void *pApp,.  vo
30580 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
30590 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
305a0 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
305b0 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
305c0 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
305d0 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
305e0 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
305f0 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
30600 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a  e3_context*).);.
30610 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
30620 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20  te_function16(. 
30630 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
30640 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e  const void *zFun
30650 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
30660 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
30670 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
30680 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
30690 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
306a0 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
306b0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
306c0 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
306d0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
306e0 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
306f0 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
30700 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
30710 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  ext*).);.int sql
30720 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
30730 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74  tion_v2(.  sqlit
30740 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20  e3 *db,.  const 
30750 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  char *zFunctionN
30760 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
30770 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
30780 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20  .  void *pApp,. 
30790 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
307a0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
307b0 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
307c0 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
307d0 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
307e0 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
307f0 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
30800 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
30810 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c  lite3_context*),
30820 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f  .  void(*xDestro
30830 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a  y)(void*).);../*
30840 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65  .** CAPI3REF: Te
30850 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a  xt Encodings.**.
30860 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
30870 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72  t define integer
30880 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 72   codes that repr
30890 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75  esent the variou
308a0 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69  s.** text encodi
308b0 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 79  ngs supported by
308c0 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66   SQLite..*/.#def
308d0 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20  ine SQLITE_UTF8 
308e0 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
308f0 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
30900 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64 65 66  LE        2.#def
30910 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
30920 42 45 20 20 20 20 20 20 20 20 33 0a 23 64 65 66  BE        3.#def
30930 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
30940 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f            4    /
30950 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74  * Use native byt
30960 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69  e order */.#defi
30970 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20  ne SQLITE_ANY   
30980 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a           5    /*
30990 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
309a0 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f  function only */
309b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
309c0 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38  UTF16_ALIGNED  8
309d0 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63      /* sqlite3_c
309e0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20  reate_collation 
309f0 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  only */../*.** C
30a00 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61  API3REF: Depreca
30a10 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ted Functions.**
30a20 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a   DEPRECATED.**.*
30a30 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
30a40 73 20 61 72 65 20 5b 64 65 70 72 65 63 61 74 65  s are [deprecate
30a50 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f  d].  In order to
30a60 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63   maintain.** bac
30a70 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
30a80 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20  lity with older 
30a90 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63  code, these func
30aa0 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a  tions continue .
30ab0 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ** to be support
30ac0 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65  ed.  However, ne
30ad0 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  w applications s
30ae0 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74  hould avoid.** t
30af0 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 20  he use of these 
30b00 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68  functions.  To h
30b10 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65  elp encourage pe
30b20 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a  ople to avoid.**
30b30 20 75 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e   using these fun
30b40 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e  ctions, we are n
30b50 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c  ot going to tell
30b60 20 79 6f 75 20 77 68 61 74 20 74 68 65 79 20 64   you what they d
30b70 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51  o..*/.#ifndef SQ
30b80 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43  LITE_OMIT_DEPREC
30b90 41 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52  ATED.SQLITE_DEPR
30ba0 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
30bb0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75  e3_aggregate_cou
30bc0 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  nt(sqlite3_conte
30bd0 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  xt*);.SQLITE_DEP
30be0 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
30bf0 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69  te3_expired(sqli
30c00 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49  te3_stmt*);.SQLI
30c10 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
30c20 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66  t sqlite3_transf
30c30 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69  er_bindings(sqli
30c40 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74  te3_stmt*, sqlit
30c50 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54  e3_stmt*);.SQLIT
30c60 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
30c70 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f   sqlite3_global_
30c80 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53  recover(void);.S
30c90 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
30ca0 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68   void sqlite3_th
30cb0 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69  read_cleanup(voi
30cc0 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  d);.SQLITE_DEPRE
30cd0 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
30ce0 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76  3_memory_alarm(v
30cf0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
30d00 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c  ite3_int64,int),
30d10 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
30d20 20 20 20 20 20 20 20 76 6f 69 64 2a 2c 73 71 6c         void*,sql
30d30 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e  ite3_int64);.#en
30d40 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
30d50 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53  REF: Obtaining S
30d60 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61  QL Function Para
30d70 6d 65 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a 0a  meter Values.**.
30d80 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67  ** The C-languag
30d90 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
30da0 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e   of SQL function
30db0 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
30dc0 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65   uses.** this se
30dd0 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72  t of interface r
30de0 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73  outines to acces
30df0 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  s the parameter 
30e00 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65  values on.** the
30e10 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
30e20 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  regate..**.** Th
30e30 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61  e xFunc (for sca
30e40 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f  lar functions) o
30e50 72 20 78 53 74 65 70 20 28 66 6f 72 20 61 67 67  r xStep (for agg
30e60 72 65 67 61 74 65 73 29 20 70 61 72 61 6d 65 74  regates) paramet
30e70 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  ers.** to [sqlit
30e80 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
30e90 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  on()] and [sqlit
30ea0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
30eb0 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e  on16()].** defin
30ec0 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74  e callbacks that
30ed0 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53   implement the S
30ee0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
30ef0 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20   aggregates..** 
30f00 54 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  The 3rd paramete
30f10 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62  r to these callb
30f20 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79  acks is an array
30f30 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a   of pointers to.
30f40 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  ** [protected sq
30f50 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
30f60 65 63 74 73 2e 20 20 54 68 65 72 65 20 69 73 20  ects.  There is 
30f70 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  one [sqlite3_val
30f80 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a  ue] object for.*
30f90 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74 65 72  * each parameter
30fa0 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63   to the SQL func
30fb0 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75  tion.  These rou
30fc0 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 74  tines are used t
30fd0 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c  o.** extract val
30fe0 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71  ues from the [sq
30ff0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
31000 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ects..**.** Thes
31010 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20  e routines work 
31020 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65  only with [prote
31030 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
31040 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  ue] objects..** 
31050 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75  Any attempt to u
31060 73 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  se these routine
31070 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65  s on an [unprote
31080 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
31090 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65  ue].** object re
310a0 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e  sults in undefin
310b0 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a  ed behavior..**.
310c0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
310d0 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b  es work just lik
310e0 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  e the correspond
310f0 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65  ing [column acce
31100 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a  ss functions].**
31110 20 65 78 63 65 70 74 20 74 68 61 74 20 20 74 68   except that  th
31120 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b  ese routines tak
31130 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74  e a single [prot
31140 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
31150 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70  lue] object.** p
31160 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f  ointer instead o
31170 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  f a [sqlite3_stm
31180 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20  t*] pointer and 
31190 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d  an integer colum
311a0 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20  n number..**.** 
311b0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
311c0 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65  ue_text16() inte
311d0 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20 61  rface extracts a
311e0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a   UTF-16 string.*
311f0 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  * in the native 
31200 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68  byte-order of th
31210 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20  e host machine. 
31220 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
31230 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28  _value_text16be(
31240 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61  ) and sqlite3_va
31250 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69  lue_text16le() i
31260 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74  nterfaces.** ext
31270 72 61 63 74 20 55 54 46 2d 31 36 20 73 74 72 69  ract UTF-16 stri
31280 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61  ngs as big-endia
31290 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64  n and little-end
312a0 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79  ian respectively
312b0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71  ..**.** ^(The sq
312c0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65  lite3_value_nume
312d0 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72  ric_type() inter
312e0 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
312f0 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69   apply.** numeri
31300 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68  c affinity to th
31310 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d  e value.  This m
31320 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74  eans that an att
31330 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20  empt is.** made 
31340 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76  to convert the v
31350 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67  alue to an integ
31360 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70  er or floating p
31370 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63  oint.  If.** suc
31380 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  h a conversion i
31390 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f  s possible witho
313a0 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72  ut loss of infor
313b0 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72  mation (in other
313c0 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68  .** words, if th
313d0 65 20 76 61 6c 75 65 20 69 73 20 61 20 73 74 72  e value is a str
313e0 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c  ing that looks l
313f0 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a  ike a number).**
31400 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72   then the conver
31410 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65  sion is performe
31420 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f  d.  Otherwise no
31430 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75   conversion occu
31440 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  rs..** The [SQLI
31450 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74  TE_INTEGER | dat
31460 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e  atype] after con
31470 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72  version is retur
31480 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65  ned.)^.**.** Ple
31490 61 73 65 20 70 61 79 20 70 61 72 74 69 63 75 6c  ase pay particul
314a0 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20  ar attention to 
314b0 74 68 65 20 66 61 63 74 20 74 68 61 74 20 74 68  the fact that th
314c0 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e  e pointer return
314d0 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ed.** from [sqli
314e0 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29  te3_value_blob()
314f0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
31500 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a  e_text()], or.**
31510 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
31520 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65  text16()] can be
31530 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20   invalidated by 
31540 61 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  a subsequent cal
31550 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
31560 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c  _value_bytes()],
31570 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
31580 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c  bytes16()], [sql
31590 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
315a0 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  )],.** or [sqlit
315b0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
315c0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  )]..**.** These 
315d0 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65  routines must be
315e0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
315f0 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a   same thread as.
31600 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  ** the SQL funct
31610 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65  ion that supplie
31620 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  d the [sqlite3_v
31630 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72  alue*] parameter
31640 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64  s..*/.const void
31650 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
31660 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 6c  blob(sqlite3_val
31670 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
31680 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71  3_value_bytes(sq
31690 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
316a0 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
316b0 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33  _bytes16(sqlite3
316c0 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65  _value*);.double
316d0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64   sqlite3_value_d
316e0 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 61  ouble(sqlite3_va
316f0 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
31700 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c  e3_value_int(sql
31710 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71  ite3_value*);.sq
31720 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
31730 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28  te3_value_int64(
31740 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
31750 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20  .const unsigned 
31760 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 61  char *sqlite3_va
31770 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65 33  lue_text(sqlite3
31780 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
31790 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
317a0 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74  lue_text16(sqlit
317b0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73  e3_value*);.cons
317c0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
317d0 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73  value_text16le(s
317e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
317f0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
31800 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
31810 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  be(sqlite3_value
31820 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
31830 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 74  value_type(sqlit
31840 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
31850 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75  sqlite3_value_nu
31860 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74  meric_type(sqlit
31870 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a  e3_value*);../*.
31880 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74  ** CAPI3REF: Obt
31890 61 69 6e 20 41 67 67 72 65 67 61 74 65 20 46 75  ain Aggregate Fu
318a0 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a  nction Context.*
318b0 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74  *.** Implementat
318c0 69 6f 6e 73 20 6f 66 20 61 67 67 72 65 67 61 74  ions of aggregat
318d0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  e SQL functions 
318e0 75 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74  use this.** rout
318f0 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ine to allocate 
31900 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72 69  memory for stori
31910 6e 67 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a  ng their state..
31920 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
31930 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65   time the sqlite
31940 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
31950 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65  ext(C,N) routine
31960 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66   is called .** f
31970 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
31980 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
31990 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c  on, SQLite.** al
319a0 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d  locates N of mem
319b0 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20  ory, zeroes out 
319c0 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64  that memory, and
319d0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
319e0 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77  er.** to the new
319f0 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63   memory. ^On sec
31a00 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65  ond and subseque
31a10 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73  nt calls to.** s
31a20 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
31a30 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74  _context() for t
31a40 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74  he same aggregat
31a50 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61  e function insta
31a60 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65  nce,.** the same
31a70 20 62 75 66 66 65 72 20 69 73 20 72 65 74 75 72   buffer is retur
31a80 6e 65 64 2e 20 20 53 71 6c 69 74 65 33 5f 61 67  ned.  Sqlite3_ag
31a90 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
31aa0 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a  ) is normally.**
31ab0 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72   called once for
31ac0 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e   each invocation
31ad0 20 6f 66 20 74 68 65 20 78 53 74 65 70 20 63 61   of the xStep ca
31ae0 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68 65 6e 20  llback and then 
31af0 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65  one.** last time
31b00 20 77 68 65 6e 20 74 68 65 20 78 46 69 6e 61 6c   when the xFinal
31b10 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
31b20 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f  oked.  ^(When no
31b30 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61   rows match.** a
31b40 6e 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72  n aggregate quer
31b50 79 2c 20 74 68 65 20 78 53 74 65 70 28 29 20 63  y, the xStep() c
31b60 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 61  allback of the a
31b70 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
31b80 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  n.** implementat
31b90 69 6f 6e 20 69 73 20 6e 65 76 65 72 20 63 61 6c  ion is never cal
31ba0 6c 65 64 20 61 6e 64 20 78 46 69 6e 61 6c 28 29  led and xFinal()
31bb0 20 69 73 20 63 61 6c 6c 65 64 20 65 78 61 63 74   is called exact
31bc0 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74  ly once..** In t
31bd0 68 6f 73 65 20 63 61 73 65 73 2c 20 73 71 6c 69  hose cases, sqli
31be0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
31bf0 6e 74 65 78 74 28 29 20 6d 69 67 68 74 20 62 65  ntext() might be
31c00 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a   called for the.
31c10 2a 2a 20 66 69 72 73 74 20 74 69 6d 65 20 66 72  ** first time fr
31c20 6f 6d 20 77 69 74 68 69 6e 20 78 46 69 6e 61 6c  om within xFinal
31c30 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().)^.**.** ^The
31c40 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
31c50 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20  te_context(C,N) 
31c60 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
31c70 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 0a  a NULL pointer .
31c80 2a 2a 20 77 68 65 6e 20 66 69 72 73 74 20 63 61  ** when first ca
31c90 6c 6c 65 64 20 69 66 20 4e 20 69 73 20 6c 65 73  lled if N is les
31ca0 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  s than or equal 
31cb0 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20  to zero or if a 
31cc0 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
31cd0 74 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e  te error occurs.
31ce0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f  .**.** ^(The amo
31cf0 75 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c 6c  unt of space all
31d00 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  ocated by sqlite
31d10 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
31d20 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64  ext(C,N) is.** d
31d30 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65  etermined by the
31d40 20 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20   N parameter on 
31d50 66 69 72 73 74 20 73 75 63 63 65 73 73 66 75 6c  first successful
31d60 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67   call.  Changing
31d70 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66   the.** value of
31d80 20 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74   N in subsequent
31d90 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
31da0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
31db0 78 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74  xt() within.** t
31dc0 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74  he same aggregat
31dd0 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61  e function insta
31de0 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73  nce will not res
31df0 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a  ize the memory.*
31e00 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 20  * allocation.)^ 
31e10 20 57 69 74 68 69 6e 20 74 68 65 20 78 46 69 6e   Within the xFin
31e20 61 6c 20 63 61 6c 6c 62 61 63 6b 2c 20 69 74 20  al callback, it 
31e30 69 73 20 63 75 73 74 6f 6d 61 72 79 20 74 6f 20  is customary to 
31e40 73 65 74 0a 2a 2a 20 4e 3d 30 20 69 6e 20 63 61  set.** N=0 in ca
31e50 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 61  lls to sqlite3_a
31e60 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
31e70 28 43 2c 4e 29 20 73 6f 20 74 68 61 74 20 6e 6f  (C,N) so that no
31e80 20 0a 2a 2a 20 70 6f 69 6e 74 6c 65 73 73 20 6d   .** pointless m
31e90 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
31ea0 73 20 6f 63 63 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e  s occur..**.** ^
31eb0 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63  SQLite automatic
31ec0 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20 6d  ally frees the m
31ed0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20  emory allocated 
31ee0 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61  by .** sqlite3_a
31ef0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
31f00 28 29 20 77 68 65 6e 20 74 68 65 20 61 67 67 72  () when the aggr
31f10 65 67 61 74 65 20 71 75 65 72 79 20 63 6f 6e 63  egate query conc
31f20 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ludes..**.** The
31f30 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
31f40 20 6d 75 73 74 20 62 65 20 61 20 63 6f 70 79 20   must be a copy 
31f50 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
31f60 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c  e3_context | SQL
31f70 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78   function contex
31f80 74 5d 20 74 68 61 74 20 69 73 20 74 68 65 20 66  t] that is the f
31f90 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a  irst parameter.*
31fa0 2a 20 74 6f 20 74 68 65 20 78 53 74 65 70 20 6f  * to the xStep o
31fb0 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  r xFinal callbac
31fc0 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69  k routine that i
31fd0 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67  mplements the ag
31fe0 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74  gregate.** funct
31ff0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ion..**.** This 
32000 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
32010 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
32020 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
32030 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72  hich.** the aggr
32040 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
32050 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
32060 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
32070 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
32080 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
32090 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b  t*, int nBytes);
320a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
320b0 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f 72 20  : User Data For 
320c0 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
320d0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65  ^The sqlite3_use
320e0 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  r_data() interfa
320f0 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  ce returns a cop
32100 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e  y of.** the poin
32110 74 65 72 20 74 68 61 74 20 77 61 73 20 74 68 65  ter that was the
32120 20 70 55 73 65 72 44 61 74 61 20 70 61 72 61 6d   pUserData param
32130 65 74 65 72 20 28 74 68 65 20 35 74 68 20 70 61  eter (the 5th pa
32140 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74  rameter).** of t
32150 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
32160 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a  te_function()].*
32170 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
32180 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
32190 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ()] routines tha
321a0 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20  t originally.** 
321b0 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61  registered the a
321c0 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
321d0 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  ed function..**.
321e0 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
321f0 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
32200 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
32210 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
32220 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
32230 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
32240 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
32250 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 73  void *sqlite3_us
32260 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f  er_data(sqlite3_
32270 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a  context*);../*.*
32280 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61  * CAPI3REF: Data
32290 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
322a0 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  For Functions.**
322b0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
322c0 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
322d0 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  le() interface r
322e0 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
322f0 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20  .** the pointer 
32300 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  to the [database
32310 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68   connection] (th
32320 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 29  e 1st parameter)
32330 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
32340 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
32350 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ion()].** and [s
32360 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
32370 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74  nction16()] rout
32380 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e  ines that origin
32390 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72  ally.** register
323a0 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ed the applicati
323b0 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on defined funct
323c0 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20  ion..*/.sqlite3 
323d0 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  *sqlite3_context
323e0 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74  _db_handle(sqlit
323f0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f  e3_context*);../
32400 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
32410 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72  unction Auxiliar
32420 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65  y Data.**.** The
32430 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79  se functions may
32440 20 62 65 20 75 73 65 64 20 62 79 20 28 6e 6f 6e   be used by (non
32450 2d 61 67 67 72 65 67 61 74 65 29 20 53 51 4c 20  -aggregate) SQL 
32460 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20  functions to.** 
32470 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61  associate metada
32480 74 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74  ta with argument
32490 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20   values. If the 
324a0 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61  same value is pa
324b0 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69  ssed to.** multi
324c0 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  ple invocations 
324d0 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20  of the same SQL 
324e0 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20  function during 
324f0 71 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c  query execution,
32500 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63   under.** some c
32510 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65  ircumstances the
32520 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61   associated meta
32530 64 61 74 61 20 6d 61 79 20 62 65 20 70 72 65 73  data may be pres
32540 65 72 76 65 64 2e 20 20 41 6e 20 65 78 61 6d 70  erved.  An examp
32550 6c 65 0a 2a 2a 20 6f 66 20 77 68 65 72 65 20 74  le.** of where t
32560 68 69 73 20 6d 69 67 68 74 20 62 65 20 75 73 65  his might be use
32570 66 75 6c 20 69 73 20 69 6e 20 61 20 72 65 67 75  ful is in a regu
32580 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d  lar-expression m
32590 61 74 63 68 69 6e 67 0a 2a 2a 20 66 75 6e 63 74  atching.** funct
325a0 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65  ion. The compile
325b0 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65  d version of the
325c0 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
325d0 69 6f 6e 20 63 61 6e 20 62 65 20 73 74 6f 72 65  ion can be store
325e0 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61  d as.** metadata
325f0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
32600 20 74 68 65 20 70 61 74 74 65 72 6e 20 73 74 72   the pattern str
32610 69 6e 67 2e 20 20 0a 2a 2a 20 54 68 65 6e 20 61  ing.  .** Then a
32620 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 70 61  s long as the pa
32630 74 74 65 72 6e 20 73 74 72 69 6e 67 20 72 65 6d  ttern string rem
32640 61 69 6e 73 20 74 68 65 20 73 61 6d 65 2c 0a 2a  ains the same,.*
32650 2a 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 72  * the compiled r
32660 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
32670 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 20  n can be reused 
32680 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69  on multiple.** i
32690 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
326a0 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 2e  e same function.
326b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
326c0 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
326d0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
326e0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
326f0 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a   the metadata.**
32700 20 61 73 73 6f 63 69 61 74 65 64 20 62 79 20 74   associated by t
32710 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
32720 75 78 64 61 74 61 28 29 20 66 75 6e 63 74 69 6f  uxdata() functio
32730 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68 20 61  n with the Nth a
32740 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65  rgument.** value
32750 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
32760 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
32770 74 69 6f 6e 2e 20 5e 49 66 20 74 68 65 72 65 20  tion. ^If there 
32780 69 73 20 6e 6f 20 6d 65 74 61 64 61 74 61 0a 2a  is no metadata.*
32790 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
327a0 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 61  h the function a
327b0 72 67 75 6d 65 6e 74 2c 20 74 68 69 73 20 73 71  rgument, this sq
327c0 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
327d0 61 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  a() interface.**
327e0 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
327f0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
32800 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  The sqlite3_set_
32810 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29  auxdata(C,N,P,X)
32820 20 69 6e 74 65 72 66 61 63 65 20 73 61 76 65 73   interface saves
32830 20 50 20 61 73 20 6d 65 74 61 64 61 74 61 20 66   P as metadata f
32840 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61  or the N-th.** a
32850 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61  rgument of the a
32860 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
32870 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 53  ed function.  ^S
32880 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c  ubsequent.** cal
32890 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65  ls to sqlite3_ge
328a0 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 29 20 72  t_auxdata(C,N) r
328b0 65 74 75 72 6e 20 50 20 66 72 6f 6d 20 74 68 65  eturn P from the
328c0 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20   most recent.** 
328d0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
328e0 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 63 61 6c  ata(C,N,P,X) cal
328f0 6c 20 69 66 20 74 68 65 20 6d 65 74 61 64 61 74  l if the metadat
32900 61 20 69 73 20 73 74 69 6c 6c 20 76 61 6c 69 64  a is still valid
32910 20 6f 72 0a 2a 2a 20 4e 55 4c 4c 20 69 66 20 74   or.** NULL if t
32920 68 65 20 6d 65 74 61 64 61 74 61 20 68 61 73 20  he metadata has 
32930 62 65 65 6e 20 64 69 73 63 61 72 64 65 64 2e 0a  been discarded..
32940 2a 2a 20 5e 41 66 74 65 72 20 65 61 63 68 20 63  ** ^After each c
32950 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
32960 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50  et_auxdata(C,N,P
32970 2c 58 29 20 77 68 65 72 65 20 58 20 69 73 20 6e  ,X) where X is n
32980 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 53 51 4c 69  ot NULL,.** SQLi
32990 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74  te will invoke t
329a0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 66 75  he destructor fu
329b0 6e 63 74 69 6f 6e 20 58 20 77 69 74 68 20 70 61  nction X with pa
329c0 72 61 6d 65 74 65 72 20 50 20 65 78 61 63 74 6c  rameter P exactl
329d0 79 0a 2a 2a 20 6f 6e 63 65 2c 20 77 68 65 6e 20  y.** once, when 
329e0 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20  the metadata is 
329f0 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20 53 51  discarded..** SQ
32a00 4c 69 74 65 20 69 73 20 66 72 65 65 20 74 6f 20  Lite is free to 
32a10 64 69 73 63 61 72 64 20 74 68 65 20 6d 65 74 61  discard the meta
32a20 64 61 74 61 20 61 74 20 61 6e 79 20 74 69 6d 65  data at any time
32a30 2c 20 69 6e 63 6c 75 64 69 6e 67 3a 20 3c 75 6c  , including: <ul
32a40 3e 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 74  >.** <li> when t
32a50 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
32a60 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65   function parame
32a70 74 65 72 20 63 68 61 6e 67 65 73 2c 20 6f 72 0a  ter changes, or.
32a80 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 5b 73 71  ** <li> when [sq
32a90 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
32aa0 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
32ab0 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ize()] is called
32ac0 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20   for the.**     
32ad0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
32ae0 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20  or.** <li> when 
32af0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
32b00 61 74 61 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ata() is invoked
32b10 20 61 67 61 69 6e 20 6f 6e 20 74 68 65 20 73 61   again on the sa
32b20 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 6f 72  me parameter, or
32b30 0a 2a 2a 20 3c 6c 69 3e 20 64 75 72 69 6e 67 20  .** <li> during 
32b40 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 71 6c  the original sql
32b50 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
32b60 28 29 20 63 61 6c 6c 20 77 68 65 6e 20 61 20 6d  () call when a m
32b70 65 6d 6f 72 79 20 0a 2a 2a 20 20 20 20 20 20 61  emory .**      a
32b80 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20  llocation error 
32b90 6f 63 63 75 72 73 2e 20 3c 2f 75 6c 3e 29 5e 0a  occurs. </ul>)^.
32ba0 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 65 20 6c  **.** Note the l
32bb0 61 73 74 20 62 75 6c 6c 65 74 20 69 6e 20 70 61  ast bullet in pa
32bc0 72 74 69 63 75 6c 61 72 2e 20 20 54 68 65 20 64  rticular.  The d
32bd0 65 73 74 72 75 63 74 6f 72 20 58 20 69 6e 20 0a  estructor X in .
32be0 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  ** sqlite3_set_a
32bf0 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20  uxdata(C,N,P,X) 
32c00 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20  might be called 
32c10 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66  immediately, bef
32c20 6f 72 65 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74  ore the.** sqlit
32c30 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
32c40 20 69 6e 74 65 72 66 61 63 65 20 65 76 65 6e 20   interface even 
32c50 72 65 74 75 72 6e 73 2e 20 20 48 65 6e 63 65 20  returns.  Hence 
32c60 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
32c70 61 74 61 28 29 0a 2a 2a 20 73 68 6f 75 6c 64 20  ata().** should 
32c80 62 65 20 63 61 6c 6c 65 64 20 6e 65 61 72 20 74  be called near t
32c90 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 75  he end of the fu
32ca0 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
32cb0 61 74 69 6f 6e 20 61 6e 64 20 74 68 65 0a 2a 2a  ation and the.**
32cc0 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
32cd0 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  entation should 
32ce0 6e 6f 74 20 6d 61 6b 65 20 61 6e 79 20 75 73 65  not make any use
32cf0 20 6f 66 20 50 20 61 66 74 65 72 0a 2a 2a 20 73   of P after.** s
32d00 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
32d10 74 61 28 29 20 68 61 73 20 62 65 65 6e 20 63 61  ta() has been ca
32d20 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  lled..**.** ^(In
32d30 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64   practice, metad
32d40 61 74 61 20 69 73 20 70 72 65 73 65 72 76 65 64  ata is preserved
32d50 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f   between functio
32d60 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 66  n calls for.** f
32d70 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65  unction paramete
32d80 72 73 20 74 68 61 74 20 61 72 65 20 63 6f 6d 70  rs that are comp
32d90 69 6c 65 2d 74 69 6d 65 20 63 6f 6e 73 74 61 6e  ile-time constan
32da0 74 73 2c 20 69 6e 63 6c 75 64 69 6e 67 20 6c 69  ts, including li
32db0 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20  teral.** values 
32dc0 61 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73 5d  and [parameters]
32dd0 20 61 6e 64 20 65 78 70 72 65 73 73 69 6f 6e 73   and expressions
32de0 20 63 6f 6d 70 6f 73 65 64 20 66 72 6f 6d 20 74   composed from t
32df0 68 65 20 73 61 6d 65 2e 29 5e 0a 2a 2a 0a 2a 2a  he same.)^.**.**
32e00 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
32e10 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
32e20 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
32e30 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
32e40 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
32e50 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
32e60 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65  void *sqlite3_ge
32e70 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65  t_auxdata(sqlite
32e80 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
32e90 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  N);.void sqlite3
32ea0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c  _set_auxdata(sql
32eb0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
32ec0 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69  nt N, void*, voi
32ed0 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a  d (*)(void*));..
32ee0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
32ef0 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e   Constants Defin
32f00 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 74  ing Special Dest
32f10 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 0a  ructor Behavior.
32f20 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20  **.** These are 
32f30 73 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66  special values f
32f40 6f 72 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  or the destructo
32f50 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64  r that is passed
32f60 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69   in as the.** fi
32f70 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  nal argument to 
32f80 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73  routines like [s
32f90 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
32fa0 6f 62 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 20  ob()].  ^If the 
32fb0 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72  destructor.** ar
32fc0 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45  gument is SQLITE
32fd0 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e  _STATIC, it mean
32fe0 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65  s that the conte
32ff0 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f  nt pointer is co
33000 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69  nstant.** and wi
33010 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e  ll never change.
33020 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65    It does not ne
33030 65 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79  ed to be destroy
33040 65 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c  ed.  ^The.** SQL
33050 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61  ITE_TRANSIENT va
33060 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74  lue means that t
33070 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20  he content will 
33080 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e  likely change in
33090 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74  .** the near fut
330a0 75 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c  ure and that SQL
330b0 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20  ite should make 
330c0 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
330d0 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63  copy of.** the c
330e0 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65  ontent before re
330f0 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54  turning..**.** T
33100 68 65 20 74 79 70 65 64 65 66 20 69 73 20 6e 65  he typedef is ne
33110 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20  cessary to work 
33120 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20  around problems 
33130 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b  in certain.** C+
33140 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 0a 2a 2f 0a  + compilers..*/.
33150 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73  typedef void (*s
33160 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
33170 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a  r_type)(void*);.
33180 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
33190 54 41 54 49 43 20 20 20 20 20 20 28 28 73 71 6c  TATIC      ((sql
331a0 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f  ite3_destructor_
331b0 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20  type)0).#define 
331c0 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
331d0 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73     ((sqlite3_des
331e0 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29  tructor_type)-1)
331f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
33200 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20 52 65  : Setting The Re
33210 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46  sult Of An SQL F
33220 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68  unction.**.** Th
33230 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
33240 20 75 73 65 64 20 62 79 20 74 68 65 20 78 46 75   used by the xFu
33250 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c  nc or xFinal cal
33260 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69  lbacks that.** i
33270 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e  mplement SQL fun
33280 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
33290 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b  gates.  See.** [
332a0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
332b0 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  unction()] and [
332c0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
332d0 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20  unction16()].** 
332e0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
332f0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
33300 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
33310 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68  s work very much
33320 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d   like the [param
33330 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61  eter binding] fa
33340 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74  mily of.** funct
33350 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e  ions used to bin
33360 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74  d values to host
33370 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70   parameters in p
33380 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
33390 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20  ts..** Refer to 
333a0 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74  the [SQL paramet
333b0 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  er] documentatio
333c0 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  n for additional
333d0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
333e0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
333f0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69  _result_blob() i
33400 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
33410 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a  e result from.**
33420 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
33430 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
33440 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20   to be the BLOB 
33450 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73  whose content is
33460 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62   pointed.** to b
33470 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  y the second par
33480 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63 68  ameter and which
33490 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67   is N bytes long
334a0 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a   where N is the.
334b0 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  ** third paramet
334c0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
334d0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65  qlite3_result_ze
334e0 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61  roblob() interfa
334f0 63 65 73 20 73 65 74 20 74 68 65 20 72 65 73 75  ces set the resu
33500 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70  lt of.** the app
33510 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
33520 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
33530 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e  a BLOB containin
33540 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79  g all zero.** by
33550 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20  tes and N bytes 
33560 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e  in size, where N
33570 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
33580 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
33590 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
335a0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f  qlite3_result_do
335b0 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  uble() interface
335c0 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74   sets the result
335d0 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c   from.** an appl
335e0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
335f0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
33600 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
33610 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a  value specified.
33620 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 72  ** by its 2nd ar
33630 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gument..**.** ^T
33640 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
33650 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71  t_error() and sq
33660 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
33670 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73  or16() functions
33680 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d  .** cause the im
33690 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75  plemented SQL fu
336a0 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20  nction to throw 
336b0 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a  an exception..**
336c0 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68   ^SQLite uses th
336d0 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64  e string pointed
336e0 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e   to by the.** 2n
336f0 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73  d parameter of s
33700 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
33710 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ror() or sqlite3
33720 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
33730 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74  ).** as the text
33740 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73   of an error mes
33750 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 20 69  sage.  ^SQLite i
33760 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 65 72  nterprets the er
33770 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73  ror.** message s
33780 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74  tring from sqlit
33790 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
337a0 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c  ) as UTF-8. ^SQL
337b0 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74  ite.** interpret
337c0 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f  s the string fro
337d0 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  m sqlite3_result
337e0 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 55 54  _error16() as UT
337f0 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a  F-16 in native.*
33800 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20 5e  * byte order.  ^
33810 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72  If the third par
33820 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
33830 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
33840 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
33850 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
33860 69 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  is negative then
33870 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73   SQLite takes as
33880 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65   the error.** me
33890 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75  ssage all text u
338a0 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69  p through the fi
338b0 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74  rst zero charact
338c0 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74  er..** ^If the t
338d0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
338e0 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
338f0 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73  _error() or.** s
33900 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
33910 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e  ror16() is non-n
33920 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c  egative then SQL
33930 69 74 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d  ite takes that m
33940 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f  any.** bytes (no
33950 74 20 63 68 61 72 61 63 74 65 72 73 29 20 66 72  t characters) fr
33960 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  om the 2nd param
33970 65 74 65 72 20 61 73 20 74 68 65 20 65 72 72 6f  eter as the erro
33980 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54  r message..** ^T
33990 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
339a0 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71  t_error() and sq
339b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
339c0 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  or16().** routin
339d0 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74  es make a privat
339e0 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72  e copy of the er
339f0 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74  ror message text
33a00 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20   before.** they 
33a10 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20  return.  Hence, 
33a20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63  the calling func
33a30 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63  tion can dealloc
33a40 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79  ate or.** modify
33a50 20 74 68 65 20 74 65 78 74 20 61 66 74 65 72 20   the text after 
33a60 74 68 65 79 20 72 65 74 75 72 6e 20 77 69 74 68  they return with
33a70 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68  out harm..** ^Th
33a80 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
33a90 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75  _error_code() fu
33aa0 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74  nction changes t
33ab0 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a  he error code.**
33ac0 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c   returned by SQL
33ad0 69 74 65 20 61 73 20 61 20 72 65 73 75 6c 74 20  ite as a result 
33ae0 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61  of an error in a
33af0 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20   function.  ^By 
33b00 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20  default,.** the 
33b10 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51  error code is SQ
33b20 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20  LITE_ERROR.  ^A 
33b30 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20  subsequent call 
33b40 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  to sqlite3_resul
33b50 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20  t_error().** or 
33b60 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
33b70 72 72 6f 72 31 36 28 29 20 72 65 73 65 74 73 20  rror16() resets 
33b80 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74  the error code t
33b90 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a  o SQLITE_ERROR..
33ba0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
33bb0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
33bc0 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66 61  toobig() interfa
33bd0 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65  ce causes SQLite
33be0 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20   to throw an.** 
33bf0 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e 67  error indicating
33c00 20 74 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f   that a string o
33c10 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f 20 6c 6f  r BLOB is too lo
33c20 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e 74 2e  ng to represent.
33c30 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
33c40 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
33c50 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61  _nomem() interfa
33c60 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65  ce causes SQLite
33c70 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20   to throw an.** 
33c80 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e 67  error indicating
33c90 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61   that a memory a
33ca0 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64  llocation failed
33cb0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
33cc0 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28  ite3_result_int(
33cd0 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
33ce0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
33cf0 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c  e.** of the appl
33d00 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
33d10 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74  function to be t
33d20 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64  he 32-bit signed
33d30 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75   integer.** valu
33d40 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32  e given in the 2
33d50 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  nd argument..** 
33d60 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
33d70 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65  ult_int64() inte
33d80 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
33d90 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f  eturn value.** o
33da0 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
33db0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
33dc0 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d  on to be the 64-
33dd0 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
33de0 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65  er.** value give
33df0 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67  n in the 2nd arg
33e00 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ument..**.** ^Th
33e10 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
33e20 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63  _null() interfac
33e30 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72  e sets the retur
33e40 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68  n value.** of th
33e50 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
33e60 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
33e70 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  o be NULL..**.**
33e80 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
33e90 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c  sult_text(), sql
33ea0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
33eb0 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  16(),.** sqlite3
33ec0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65  _result_text16le
33ed0 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  (), and sqlite3_
33ee0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28  result_text16be(
33ef0 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
33f00 73 65 74 20 74 68 65 20 72 65 74 75 72 6e 20 76  set the return v
33f10 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c  alue of the appl
33f20 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
33f30 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a  function to be.*
33f40 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20  * a text string 
33f50 77 68 69 63 68 20 69 73 20 72 65 70 72 65 73 65  which is represe
33f60 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55  nted as UTF-8, U
33f70 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74  TF-16 native byt
33f80 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d  e order,.** UTF-
33f90 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e  16 little endian
33fa0 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20  , or UTF-16 big 
33fb0 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69  endian, respecti
33fc0 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  vely..** ^SQLite
33fd0 20 74 61 6b 65 73 20 74 68 65 20 74 65 78 74 20   takes the text 
33fe0 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20  result from the 
33ff0 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d  application from
34000 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61  .** the 2nd para
34010 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c  meter of the sql
34020 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
34030 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a  * interfaces..**
34040 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72   ^If the 3rd par
34050 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
34060 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
34070 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
34080 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
34090 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
340a0 72 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d  result text from
340b0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
340c0 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68  er.** through th
340d0 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61  e first zero cha
340e0 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74  racter..** ^If t
340f0 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
34100 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
34110 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
34120 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f  erfaces.** is no
34130 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  n-negative, then
34140 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28   as many bytes (
34150 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20  not characters) 
34160 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70  of the text.** p
34170 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65  ointed to by the
34180 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
34190 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20  re taken as the 
341a0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
341b0 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ned.** function 
341c0 72 65 73 75 6c 74 2e 20 20 49 66 20 74 68 65 20  result.  If the 
341d0 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  3rd parameter is
341e0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
341f0 68 65 6e 20 69 74 0a 2a 2a 20 6d 75 73 74 20 62  hen it.** must b
34200 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73 65  e the byte offse
34210 74 20 69 6e 74 6f 20 74 68 65 20 73 74 72 69 6e  t into the strin
34220 67 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20  g where the NUL 
34230 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64  terminator would
34240 0a 2a 2a 20 61 70 70 65 61 72 20 69 66 20 74 68  .** appear if th
34250 65 20 73 74 72 69 6e 67 20 77 68 65 72 65 20 4e  e string where N
34260 55 4c 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  UL terminated.  
34270 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61  If any NUL chara
34280 63 74 65 72 73 20 6f 63 63 75 72 0a 2a 2a 20 69  cters occur.** i
34290 6e 20 74 68 65 20 73 74 72 69 6e 67 20 61 74 20  n the string at 
342a0 61 20 62 79 74 65 20 6f 66 66 73 65 74 20 74 68  a byte offset th
342b0 61 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  at is less than 
342c0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
342d0 20 33 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65   3rd.** paramete
342e0 72 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  r, then the resu
342f0 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 77 69 6c  lting string wil
34300 6c 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64  l contain embedd
34310 65 64 20 4e 55 4c 73 20 61 6e 64 20 74 68 65 0a  ed NULs and the.
34320 2a 2a 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70  ** result of exp
34330 72 65 73 73 69 6f 6e 73 20 6f 70 65 72 61 74 69  ressions operati
34340 6e 67 20 6f 6e 20 73 74 72 69 6e 67 73 20 77 69  ng on strings wi
34350 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73  th embedded NULs
34360 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
34370 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61  * ^If the 4th pa
34380 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
34390 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
343a0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
343b0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
343c0 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f  ult_blob is a no
343d0 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  n-NULL pointer, 
343e0 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c  then SQLite call
343f0 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69  s that.** functi
34400 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74 72 75  on as the destru
34410 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74  ctor on the text
34420 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20   or BLOB result 
34430 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66  when it has.** f
34440 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68  inished using th
34450 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49  at result..** ^I
34460 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
34470 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
34480 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
34490 69 6e 74 65 72 66 61 63 65 73 20 6f 72 20 74 6f  interfaces or to
344a0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
344b0 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73  lt_blob is the s
344c0 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20  pecial constant 
344d0 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74  SQLITE_STATIC, t
344e0 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73  hen SQLite.** as
344f0 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 74  sumes that the t
34500 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75  ext or BLOB resu
34510 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e  lt is in constan
34520 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73  t space and does
34530 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65   not.** copy the
34540 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
34550 70 61 72 61 6d 65 74 65 72 20 6e 6f 72 20 63 61  parameter nor ca
34560 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  ll a destructor 
34570 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a  on the content.*
34580 2a 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69  * when it has fi
34590 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61  nished using tha
345a0 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66  t result..** ^If
345b0 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
345c0 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
345d0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
345e0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20  nterfaces.** or 
345f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
34600 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69  lob is the speci
34610 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49  al constant SQLI
34620 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20  TE_TRANSIENT.** 
34630 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65  then SQLite make
34640 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
34650 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63  result into spac
34660 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a  e obtained from.
34670 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
34680 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72  _malloc()] befor
34690 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  e it returns..**
346a0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
346b0 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
346c0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
346d0 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20  he result of.** 
346e0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
346f0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
34700 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68   to be a copy th
34710 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65  e.** [unprotecte
34720 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
34730 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65   object specifie
34740 64 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72  d by the 2nd par
34750 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a  ameter.  ^The.**
34760 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34770 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63  value() interfac
34780 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
34790 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  f the [sqlite3_v
347a0 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74  alue].** so that
347b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
347c0 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64 20 69  lue] specified i
347d0 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  n the parameter 
347e0 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a  may change or.**
347f0 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
34800 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65  after sqlite3_re
34810 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74  sult_value() ret
34820 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72  urns without har
34830 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63  m..** ^A [protec
34840 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
34850 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c  e] object may al
34860 77 61 79 73 20 62 65 20 75 73 65 64 20 77 68 65  ways be used whe
34870 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74  re an.** [unprot
34880 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
34890 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72  lue] object is r
348a0 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68  equired, so eith
348b0 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73  er.** kind of [s
348c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
348d0 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73 65 64  ject can be used
348e0 20 77 69 74 68 20 74 68 69 73 20 69 6e 74 65 72   with this inter
348f0 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  face..**.** If t
34900 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
34910 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69  e called from wi
34920 74 68 69 6e 20 74 68 65 20 64 69 66 66 65 72 65  thin the differe
34930 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61  nt thread.** tha
34940 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69  n the one contai
34950 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61  ning the applica
34960 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
34970 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69  ction that recei
34980 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  ved.** the [sqli
34990 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69  te3_context] poi
349a0 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74  nter, the result
349b0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
349c0 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
349d0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c  _result_blob(sql
349e0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
349f0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
34a00 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
34a10 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
34a20 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c  esult_double(sql
34a30 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64  ite3_context*, d
34a40 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c  ouble);.void sql
34a50 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
34a60 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  r(sqlite3_contex
34a70 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  t*, const char*,
34a80 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
34a90 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
34aa0 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  16(sqlite3_conte
34ab0 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
34ac0 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
34ad0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
34ae0 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33  r_toobig(sqlite3
34af0 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64  _context*);.void
34b00 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34b10 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69  error_nomem(sqli
34b20 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76  te3_context*);.v
34b30 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
34b40 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71  lt_error_code(sq
34b50 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
34b60 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
34b70 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71  e3_result_int(sq
34b80 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
34b90 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
34ba0 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28  e3_result_int64(
34bb0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
34bc0 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
34bd0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
34be0 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74  esult_null(sqlit
34bf0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f  e3_context*);.vo
34c00 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
34c10 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63  t_text(sqlite3_c
34c20 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63  ontext*, const c
34c30 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  har*, int, void(
34c40 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
34c50 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34c60 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63  text16(sqlite3_c
34c70 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
34c80 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
34c90 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
34ca0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34cb0 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33  text16le(sqlite3
34cc0 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
34cd0 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64   void*, int,void
34ce0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
34cf0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
34d00 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65  _text16be(sqlite
34d10 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
34d20 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69  t void*, int,voi
34d30 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
34d40 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
34d50 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  t_value(sqlite3_
34d60 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65  context*, sqlite
34d70 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20  3_value*);.void 
34d80 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a  sqlite3_result_z
34d90 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  eroblob(sqlite3_
34da0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29  context*, int n)
34db0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
34dc0 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f  F: Define New Co
34dd0 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65  llating Sequence
34de0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66  s.**.** ^These f
34df0 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c 20 72 65  unctions add, re
34e00 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 66 79 20  move, or modify 
34e10 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61 73  a [collation] as
34e20 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68  sociated.** with
34e30 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
34e40 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69  onnection] speci
34e50 66 69 65 64 20 61 73 20 74 68 65 20 66 69 72 73  fied as the firs
34e60 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  t argument..**.*
34e70 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74  * ^The name of t
34e80 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20  he collation is 
34e90 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a  a UTF-8 string.*
34ea0 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  * for sqlite3_cr
34eb0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
34ec0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65   and sqlite3_cre
34ed0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
34ee0 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d  ().** and a UTF-
34ef0 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74  16 string in nat
34f00 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 66  ive byte order f
34f10 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
34f20 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e  e_collation16().
34f30 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20 6e  .** ^Collation n
34f40 61 6d 65 73 20 74 68 61 74 20 63 6f 6d 70 61 72  ames that compar
34f50 65 20 65 71 75 61 6c 20 61 63 63 6f 72 64 69 6e  e equal accordin
34f60 67 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  g to [sqlite3_st
34f70 72 6e 69 63 6d 70 28 29 5d 20 61 72 65 0a 2a 2a  rnicmp()] are.**
34f80 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 62   considered to b
34f90 65 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e  e the same name.
34fa0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 74 68 69  .**.** ^(The thi
34fb0 72 64 20 61 72 67 75 6d 65 6e 74 20 28 65 54 65  rd argument (eTe
34fc0 78 74 52 65 70 29 20 6d 75 73 74 20 62 65 20 6f  xtRep) must be o
34fd0 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61  ne of the consta
34fe0 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  nts:.** <ul>.** 
34ff0 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46  <li> [SQLITE_UTF
35000 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  8],.** <li> [SQL
35010 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a 2a  ITE_UTF16LE],.**
35020 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54   <li> [SQLITE_UT
35030 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  F16BE],.** <li> 
35040 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20  [SQLITE_UTF16], 
35050 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  or.** <li> [SQLI
35060 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44  TE_UTF16_ALIGNED
35070 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  ]..** </ul>)^.**
35080 20 5e 54 68 65 20 65 54 65 78 74 52 65 70 20 61   ^The eTextRep a
35090 72 67 75 6d 65 6e 74 20 64 65 74 65 72 6d 69 6e  rgument determin
350a0 65 73 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  es the encoding 
350b0 6f 66 20 73 74 72 69 6e 67 73 20 70 61 73 73 65  of strings passe
350c0 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6c 6c  d.** to the coll
350d0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63  ating function c
350e0 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c 6c 62 61  allback, xCallba
350f0 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  ck..** ^The [SQL
35100 49 54 45 5f 55 54 46 31 36 5d 20 61 6e 64 20 5b  ITE_UTF16] and [
35110 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49  SQLITE_UTF16_ALI
35120 47 4e 45 44 5d 20 76 61 6c 75 65 73 20 66 6f 72  GNED] values for
35130 20 65 54 65 78 74 52 65 70 0a 2a 2a 20 66 6f 72   eTextRep.** for
35140 63 65 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65  ce strings to be
35150 20 55 54 46 31 36 20 77 69 74 68 20 6e 61 74 69   UTF16 with nati
35160 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
35170 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55  * ^The [SQLITE_U
35180 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61  TF16_ALIGNED] va
35190 6c 75 65 20 66 6f 72 20 65 54 65 78 74 52 65 70  lue for eTextRep
351a0 20 66 6f 72 63 65 73 20 73 74 72 69 6e 67 73 20   forces strings 
351b0 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20 61  to begin.** on a
351c0 6e 20 65 76 65 6e 20 62 79 74 65 20 61 64 64 72  n even byte addr
351d0 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ess..**.** ^The 
351e0 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c  fourth argument,
351f0 20 70 41 72 67 2c 20 69 73 20 61 6e 20 61 70 70   pArg, is an app
35200 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
35210 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 70 61  inter that is pa
35220 73 73 65 64 0a 2a 2a 20 74 68 72 6f 75 67 68 20  ssed.** through 
35230 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
35240 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 6f 6c  ument to the col
35250 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
35260 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  callback..**.** 
35270 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d  ^The fifth argum
35280 65 6e 74 2c 20 78 43 61 6c 6c 62 61 63 6b 2c 20  ent, xCallback, 
35290 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
352a0 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  the collating fu
352b0 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74  nction..** ^Mult
352c0 69 70 6c 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66  iple collating f
352d0 75 6e 63 74 69 6f 6e 73 20 63 61 6e 20 62 65 20  unctions can be 
352e0 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67  registered using
352f0 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62   the same name b
35300 75 74 0a 2a 2a 20 77 69 74 68 20 64 69 66 66 65  ut.** with diffe
35310 72 65 6e 74 20 65 54 65 78 74 52 65 70 20 70 61  rent eTextRep pa
35320 72 61 6d 65 74 65 72 73 20 61 6e 64 20 53 51 4c  rameters and SQL
35330 69 74 65 20 77 69 6c 6c 20 75 73 65 20 77 68 69  ite will use whi
35340 63 68 65 76 65 72 0a 2a 2a 20 66 75 6e 63 74 69  chever.** functi
35350 6f 6e 20 72 65 71 75 69 72 65 73 20 74 68 65 20  on requires the 
35360 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20  least amount of 
35370 64 61 74 61 20 74 72 61 6e 73 66 6f 72 6d 61 74  data transformat
35380 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ion..** ^If the 
35390 78 43 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65  xCallback argume
353a0 6e 74 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20  nt is NULL then 
353b0 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  the collating fu
353c0 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 6c  nction is.** del
353d0 65 74 65 64 2e 20 20 5e 57 68 65 6e 20 61 6c 6c  eted.  ^When all
353e0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
353f0 69 6f 6e 73 20 68 61 76 69 6e 67 20 74 68 65 20  ions having the 
35400 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 64 65  same name are de
35410 6c 65 74 65 64 2c 0a 2a 2a 20 74 68 61 74 20 63  leted,.** that c
35420 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 20 6c  ollation is no l
35430 6f 6e 67 65 72 20 75 73 61 62 6c 65 2e 0a 2a 2a  onger usable..**
35440 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c 61 74 69  .** ^The collati
35450 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c  ng function call
35460 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
35470 77 69 74 68 20 61 20 63 6f 70 79 20 6f 66 20 74  with a copy of t
35480 68 65 20 70 41 72 67 20 0a 2a 2a 20 61 70 70 6c  he pArg .** appl
35490 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
354a0 6e 74 65 72 20 61 6e 64 20 77 69 74 68 20 74 77  nter and with tw
354b0 6f 20 73 74 72 69 6e 67 73 20 69 6e 20 74 68 65  o strings in the
354c0 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66   encoding specif
354d0 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 65 54  ied.** by the eT
354e0 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74 2e  extRep argument.
354f0 20 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20    The collating 
35500 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 72 65  function must re
35510 74 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65 67  turn an.** integ
35520 65 72 20 74 68 61 74 20 69 73 20 6e 65 67 61 74  er that is negat
35530 69 76 65 2c 20 7a 65 72 6f 2c 20 6f 72 20 70 6f  ive, zero, or po
35540 73 69 74 69 76 65 0a 2a 2a 20 69 66 20 74 68 65  sitive.** if the
35550 20 66 69 72 73 74 20 73 74 72 69 6e 67 20 69 73   first string is
35560 20 6c 65 73 73 20 74 68 61 6e 2c 20 65 71 75 61   less than, equa
35570 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72  l to, or greater
35580 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64   than the second
35590 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c  ,.** respectivel
355a0 79 2e 20 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20  y.  A collating 
355b0 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 61 6c  function must al
355c0 77 61 79 73 20 72 65 74 75 72 6e 20 74 68 65 20  ways return the 
355d0 73 61 6d 65 20 61 6e 73 77 65 72 0a 2a 2a 20 67  same answer.** g
355e0 69 76 65 6e 20 74 68 65 20 73 61 6d 65 20 69 6e  iven the same in
355f0 70 75 74 73 2e 20 20 49 66 20 74 77 6f 20 6f 72  puts.  If two or
35600 20 6d 6f 72 65 20 63 6f 6c 6c 61 74 69 6e 67 20   more collating 
35610 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 72 65  functions are re
35620 67 69 73 74 65 72 65 64 0a 2a 2a 20 74 6f 20 74  gistered.** to t
35630 68 65 20 73 61 6d 65 20 63 6f 6c 6c 61 74 69 6f  he same collatio
35640 6e 20 6e 61 6d 65 20 28 75 73 69 6e 67 20 64 69  n name (using di
35650 66 66 65 72 65 6e 74 20 65 54 65 78 74 52 65 70  fferent eTextRep
35660 20 76 61 6c 75 65 73 29 20 74 68 65 6e 20 61 6c   values) then al
35670 6c 0a 2a 2a 20 6d 75 73 74 20 67 69 76 65 20 61  l.** must give a
35680 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 73  n equivalent ans
35690 77 65 72 20 77 68 65 6e 20 69 6e 76 6f 6b 65 64  wer when invoked
356a0 20 77 69 74 68 20 65 71 75 69 76 61 6c 65 6e 74   with equivalent
356b0 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65   strings..** The
356c0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
356d0 69 6f 6e 20 6d 75 73 74 20 6f 62 65 79 20 74 68  ion must obey th
356e0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f 70  e following prop
356f0 65 72 74 69 65 73 20 66 6f 72 20 61 6c 6c 0a 2a  erties for all.*
35700 2a 20 73 74 72 69 6e 67 73 20 41 2c 20 42 2c 20  * strings A, B, 
35710 61 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c  and C:.**.** <ol
35720 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d  >.** <li> If A==
35730 42 20 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a 20  B then B==A..** 
35740 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 61 6e 64  <li> If A==B and
35750 20 42 3d 3d 43 20 74 68 65 6e 20 41 3d 3d 43 2e   B==C then A==C.
35760 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74  .** <li> If A&lt
35770 3b 42 20 54 48 45 4e 20 42 26 67 74 3b 41 2e 0a  ;B THEN B&gt;A..
35780 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b  ** <li> If A&lt;
35790 42 20 61 6e 64 20 42 26 6c 74 3b 43 20 74 68 65  B and B&lt;C the
357a0 6e 20 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f  n A&lt;C..** </o
357b0 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 6f  l>.**.** If a co
357c0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
357d0 20 66 61 69 6c 73 20 61 6e 79 20 6f 66 20 74 68   fails any of th
357e0 65 20 61 62 6f 76 65 20 63 6f 6e 73 74 72 61 69  e above constrai
357f0 6e 74 73 20 61 6e 64 20 74 68 61 74 0a 2a 2a 20  nts and that.** 
35800 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
35810 6f 6e 20 69 73 20 20 72 65 67 69 73 74 65 72 65  on is  registere
35820 64 20 61 6e 64 20 75 73 65 64 2c 20 74 68 65 6e  d and used, then
35830 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
35840 20 53 51 4c 69 74 65 0a 2a 2a 20 69 73 20 75 6e   SQLite.** is un
35850 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
35860 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  The sqlite3_crea
35870 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
35880 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c  ) works like sql
35890 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
358a0 61 74 69 6f 6e 28 29 0a 2a 2a 20 77 69 74 68 20  ation().** with 
358b0 74 68 65 20 61 64 64 69 74 69 6f 6e 20 74 68 61  the addition tha
358c0 74 20 74 68 65 20 78 44 65 73 74 72 6f 79 20 63  t the xDestroy c
358d0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
358e0 65 64 20 6f 6e 20 70 41 72 67 20 77 68 65 6e 0a  ed on pArg when.
358f0 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67  ** the collating
35900 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c   function is del
35910 65 74 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74  eted..** ^Collat
35920 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  ing functions ar
35930 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74  e deleted when t
35940 68 65 79 20 61 72 65 20 6f 76 65 72 72 69 64 64  hey are overridd
35950 65 6e 20 62 79 20 6c 61 74 65 72 0a 2a 2a 20 63  en by later.** c
35960 61 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c 6c  alls to the coll
35970 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66  ation creation f
35980 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e  unctions or when
35990 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73   the.** [databas
359a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73  e connection] is
359b0 20 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73   closed using [s
359c0 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e  qlite3_close()].
359d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 44 65 73  .**.** ^The xDes
359e0 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  troy callback is
359f0 20 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c 6c   <u>not</u> call
35a00 65 64 20 69 66 20 74 68 65 20 0a 2a 2a 20 73 71  ed if the .** sq
35a10 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
35a20 6c 61 74 69 6f 6e 5f 76 32 28 29 20 66 75 6e 63  lation_v2() func
35a30 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 41 70 70  tion fails.  App
35a40 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 69  lications that i
35a50 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
35a60 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
35a70 6e 5f 76 32 28 29 20 77 69 74 68 20 61 20 6e 6f  n_v2() with a no
35a80 6e 2d 4e 55 4c 4c 20 78 44 65 73 74 72 6f 79 20  n-NULL xDestroy 
35a90 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
35aa0 0a 2a 2a 20 63 68 65 63 6b 20 74 68 65 20 72 65  .** check the re
35ab0 74 75 72 6e 20 63 6f 64 65 20 61 6e 64 20 64 69  turn code and di
35ac0 73 70 6f 73 65 20 6f 66 20 74 68 65 20 61 70 70  spose of the app
35ad0 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
35ae0 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6d 73 65 6c  inter.** themsel
35af0 76 65 73 20 72 61 74 68 65 72 20 74 68 61 6e 20  ves rather than 
35b00 65 78 70 65 63 74 69 6e 67 20 53 51 4c 69 74 65  expecting SQLite
35b10 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20 69 74   to deal with it
35b20 20 66 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20 54 68   for them..** Th
35b30 69 73 20 69 73 20 64 69 66 66 65 72 65 6e 74 20  is is different 
35b40 66 72 6f 6d 20 65 76 65 72 79 20 6f 74 68 65 72  from every other
35b50 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
35b60 65 2e 20 20 54 68 65 20 69 6e 63 6f 6e 73 69 73  e.  The inconsis
35b70 74 65 6e 63 79 20 0a 2a 2a 20 69 73 20 75 6e 66  tency .** is unf
35b80 6f 72 74 75 6e 61 74 65 20 62 75 74 20 63 61 6e  ortunate but can
35b90 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20 77  not be changed w
35ba0 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20  ithout breaking 
35bb0 62 61 63 6b 77 61 72 64 73 20 0a 2a 2a 20 63 6f  backwards .** co
35bc0 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a  mpatibility..**.
35bd0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 73  ** See also:  [s
35be0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
35bf0 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 20 5b  _needed()] and [
35c00 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
35c10 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a  n_needed16()]..*
35c20 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  /.int sqlite3_cr
35c30 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a  eate_collation(.
35c40 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63    sqlite3*, .  c
35c50 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
35c60 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  , .  int eTextRe
35c70 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67  p, .  void *pArg
35c80 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72  ,.  int(*xCompar
35c90 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  e)(void*,int,con
35ca0 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  st void*,int,con
35cb0 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74  st void*).);.int
35cc0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
35cd0 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20  collation_v2(.  
35ce0 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e  sqlite3*, .  con
35cf0 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
35d00 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
35d10 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a   .  void *pArg,.
35d20 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29    int(*xCompare)
35d30 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
35d40 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74   void*,int,const
35d50 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28   void*),.  void(
35d60 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a  *xDestroy)(void*
35d70 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
35d80 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
35d90 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  n16(.  sqlite3*,
35da0 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a   .  const void *
35db0 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65  zName,.  int eTe
35dc0 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a  xtRep, .  void *
35dd0 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f  pArg,.  int(*xCo
35de0 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74  mpare)(void*,int
35df0 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74  ,const void*,int
35e00 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b  ,const void*).);
35e10 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
35e20 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64  : Collation Need
35e30 65 64 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a  ed Callbacks.**.
35e40 2a 2a 20 5e 54 6f 20 61 76 6f 69 64 20 68 61 76  ** ^To avoid hav
35e50 69 6e 67 20 74 6f 20 72 65 67 69 73 74 65 72 20  ing to register 
35e60 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  all collation se
35e70 71 75 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61  quences before a
35e80 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e   database.** can
35e90 20 62 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67   be used, a sing
35ea0 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  le callback func
35eb0 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69  tion may be regi
35ec0 73 74 65 72 65 64 20 77 69 74 68 20 74 68 65 0a  stered with the.
35ed0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
35ee0 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20 69  nection] to be i
35ef0 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20  nvoked whenever 
35f00 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c  an undefined col
35f10 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e  lation.** sequen
35f20 63 65 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a  ce is required..
35f30 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 75  **.** ^If the fu
35f40 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73 74  nction is regist
35f50 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 73  ered using the s
35f60 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
35f70 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a 2a  _needed() API,.*
35f80 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70 61 73  * then it is pas
35f90 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f 66  sed the names of
35fa0 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61   undefined colla
35fb0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 61  tion sequences a
35fc0 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63  s strings.** enc
35fd0 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 5e  oded in UTF-8. ^
35fe0 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  If sqlite3_colla
35ff0 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20  tion_needed16() 
36000 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20  is used,.** the 
36010 6e 61 6d 65 73 20 61 72 65 20 70 61 73 73 65 64  names are passed
36020 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61   as UTF-16 in ma
36030 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74  chine native byt
36040 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41 20 63  e order..** ^A c
36050 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 66 75  all to either fu
36060 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20  nction replaces 
36070 74 68 65 20 65 78 69 73 74 69 6e 67 20 63 6f 6c  the existing col
36080 6c 61 74 69 6f 6e 2d 6e 65 65 64 65 64 20 63 61  lation-needed ca
36090 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28  llback..**.** ^(
360a0 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
360b0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68  k is invoked, th
360c0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
360d0 20 70 61 73 73 65 64 20 69 73 20 61 20 63 6f 70   passed is a cop
360e0 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 6f  y.** of the seco
360f0 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  nd argument to s
36100 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
36110 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20  _needed() or.** 
36120 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
36130 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 20 54  n_needed16().  T
36140 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
36150 6e 74 20 69 73 20 74 68 65 20 64 61 74 61 62 61  nt is the databa
36160 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
36170 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67  .  The third arg
36180 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20  ument is one of 
36190 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b  [SQLITE_UTF8], [
361a0 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c  SQLITE_UTF16BE],
361b0 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  .** or [SQLITE_U
361c0 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74  TF16LE], indicat
361d0 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 65 73  ing the most des
361e0 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74  irable form of t
361f0 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20  he collation.** 
36200 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69 6f  sequence functio
36210 6e 20 72 65 71 75 69 72 65 64 2e 20 20 54 68 65  n required.  The
36220 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
36230 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  r is the name of
36240 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64   the.** required
36250 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
36260 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  nce.)^.**.** The
36270 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
36280 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74  on should regist
36290 65 72 20 74 68 65 20 64 65 73 69 72 65 64 20 63  er the desired c
362a0 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a  ollation using.*
362b0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  * [sqlite3_creat
362c0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20  e_collation()], 
362d0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
362e0 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20  collation16()], 
362f0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  or.** [sqlite3_c
36300 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
36310 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  v2()]..*/.int sq
36320 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
36330 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74 65  needed(.  sqlite
36340 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20  3*, .  void*, . 
36350 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73   void(*)(void*,s
36360 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78  qlite3*,int eTex
36370 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a  tRep,const char*
36380 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
36390 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
363a0 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  d16(.  sqlite3*,
363b0 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69   .  void*,.  voi
363c0 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
363d0 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70  e3*,int eTextRep
363e0 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b  ,const void*).);
363f0 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  ..#ifdef SQLITE_
36400 48 41 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a 20  HAS_CODEC./*.** 
36410 53 70 65 63 69 66 79 20 74 68 65 20 6b 65 79 20  Specify the key 
36420 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74 65 64  for an encrypted
36430 20 64 61 74 61 62 61 73 65 2e 20 20 54 68 69 73   database.  This
36440 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20   routine should 
36450 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67  be.** called rig
36460 68 74 20 61 66 74 65 72 20 73 71 6c 69 74 65 33  ht after sqlite3
36470 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54  _open()..**.** T
36480 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65  he code to imple
36490 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73  ment this API is
364a0 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69   not available i
364b0 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c  n the public rel
364c0 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ease.** of SQLit
364d0 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
364e0 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33  3_key(.  sqlite3
364f0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
36500 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
36510 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65  ase to be rekeye
36520 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  d */.  const voi
36530 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65  d *pKey, int nKe
36540 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79  y     /* The key
36550 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
36560 65 33 5f 6b 65 79 5f 76 32 28 0a 20 20 73 71 6c  e3_key_v2(.  sql
36570 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
36580 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
36590 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65  atabase to be re
365a0 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74  keyed */.  const
365b0 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20   char *zDbName, 
365c0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d            /* Nam
365d0 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
365e0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
365f0 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65  d *pKey, int nKe
36600 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79  y     /* The key
36610 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68   */.);../*.** Ch
36620 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f 6e 20  ange the key on 
36630 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  an open database
36640 2e 20 20 49 66 20 74 68 65 20 63 75 72 72 65 6e  .  If the curren
36650 74 20 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f  t database is no
36660 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c 20  t.** encrypted, 
36670 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c  this routine wil
36680 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20 20 49  l encrypt it.  I
36690 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65  f pNew==0 or nNe
366a0 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74  w==0, the.** dat
366b0 61 62 61 73 65 20 69 73 20 64 65 63 72 79 70 74  abase is decrypt
366c0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ed..**.** The co
366d0 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  de to implement 
366e0 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20  this API is not 
366f0 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65  available in the
36700 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a   public release.
36710 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  ** of SQLite..*/
36720 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b  .int sqlite3_rek
36730 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  ey(.  sqlite3 *d
36740 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  b,              
36750 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
36760 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a   to be rekeyed *
36770 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
36780 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20  pKey, int nKey  
36790 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65     /* The new ke
367a0 79 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  y */.);.int sqli
367b0 74 65 33 5f 72 65 6b 65 79 5f 76 32 28 0a 20 20  te3_rekey_v2(.  
367c0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
367d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
367e0 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65  * Database to be
367f0 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f   rekeyed */.  co
36800 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d  nst char *zDbNam
36810 65 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  e,           /* 
36820 4e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  Name of the data
36830 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  base */.  const 
36840 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20  void *pKey, int 
36850 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20  nKey     /* The 
36860 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f  new key */.);../
36870 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65  *.** Specify the
36880 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 20   activation key 
36890 66 6f 72 20 61 20 53 45 45 20 64 61 74 61 62 61  for a SEE databa
368a0 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20  se.  Unless .** 
368b0 61 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20  activated, none 
368c0 6f 66 20 74 68 65 20 53 45 45 20 72 6f 75 74 69  of the SEE routi
368d0 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a  nes will work..*
368e0 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61  /.void sqlite3_a
368f0 63 74 69 76 61 74 65 5f 73 65 65 28 0a 20 20 63  ctivate_see(.  c
36900 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73  onst char *zPass
36910 50 68 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a  Phrase        /*
36920 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61   Activation phra
36930 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a  se */.);.#endif.
36940 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 45  .#ifdef SQLITE_E
36950 4e 41 42 4c 45 5f 43 45 52 4f 44 0a 2f 2a 0a 2a  NABLE_CEROD./*.*
36960 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 61 63  * Specify the ac
36970 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72  tivation key for
36980 20 61 20 43 45 52 4f 44 20 64 61 74 61 62 61 73   a CEROD databas
36990 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61  e.  Unless .** a
369a0 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f  ctivated, none o
369b0 66 20 74 68 65 20 43 45 52 4f 44 20 72 6f 75 74  f the CEROD rout
369c0 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a  ines will work..
369d0 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
369e0 61 63 74 69 76 61 74 65 5f 63 65 72 6f 64 28 0a  activate_cerod(.
369f0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50    const char *zP
36a00 61 73 73 50 68 72 61 73 65 20 20 20 20 20 20 20  assPhrase       
36a10 20 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70   /* Activation p
36a20 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64  hrase */.);.#end
36a30 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  if../*.** CAPI3R
36a40 45 46 3a 20 53 75 73 70 65 6e 64 20 45 78 65 63  EF: Suspend Exec
36a50 75 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72  ution For A Shor
36a60 74 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 65  t Time.**.** The
36a70 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29   sqlite3_sleep()
36a80 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73   function causes
36a90 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 68 72   the current thr
36aa0 65 61 64 20 74 6f 20 73 75 73 70 65 6e 64 20 65  ead to suspend e
36ab0 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20  xecution.** for 
36ac0 61 74 20 6c 65 61 73 74 20 61 20 6e 75 6d 62 65  at least a numbe
36ad0 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
36ae0 73 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 69  s specified in i
36af0 74 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  ts parameter..**
36b00 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 65 72 61  .** If the opera
36b10 74 69 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 73  ting system does
36b20 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 73 6c 65   not support sle
36b30 65 70 20 72 65 71 75 65 73 74 73 20 77 69 74 68  ep requests with
36b40 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20  .** millisecond 
36b50 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c  time resolution,
36b60 20 74 68 65 6e 20 74 68 65 20 74 69 6d 65 20 77   then the time w
36b70 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 75  ill be rounded u
36b80 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 72  p to.** the near
36b90 65 73 74 20 73 65 63 6f 6e 64 2e 20 54 68 65 20  est second. The 
36ba0 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73  number of millis
36bb0 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20  econds of sleep 
36bc0 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75  actually.** requ
36bd0 65 73 74 65 64 20 66 72 6f 6d 20 74 68 65 20 6f  ested from the o
36be0 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
36bf0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
36c00 2a 2a 20 5e 53 51 4c 69 74 65 20 69 6d 70 6c 65  ** ^SQLite imple
36c10 6d 65 6e 74 73 20 74 68 69 73 20 69 6e 74 65 72  ments this inter
36c20 66 61 63 65 20 62 79 20 63 61 6c 6c 69 6e 67 20  face by calling 
36c30 74 68 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20  the xSleep().** 
36c40 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65  method of the de
36c50 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
36c60 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 49 66 20  fs] object.  If 
36c70 74 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74  the xSleep() met
36c80 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 64 65  hod.** of the de
36c90 66 61 75 6c 74 20 56 46 53 20 69 73 20 6e 6f 74  fault VFS is not
36ca0 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 63 6f 72   implemented cor
36cb0 72 65 63 74 6c 79 2c 20 6f 72 20 6e 6f 74 20 69  rectly, or not i
36cc0 6d 70 6c 65 6d 65 6e 74 65 64 20 61 74 0a 2a 2a  mplemented at.**
36cd0 20 61 6c 6c 2c 20 74 68 65 6e 20 74 68 65 20 62   all, then the b
36ce0 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74  ehavior of sqlit
36cf0 65 33 5f 73 6c 65 65 70 28 29 20 6d 61 79 20 64  e3_sleep() may d
36d00 65 76 69 61 74 65 20 66 72 6f 6d 20 74 68 65 20  eviate from the 
36d10 64 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 20 69  description.** i
36d20 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70  n the previous p
36d30 61 72 61 67 72 61 70 68 73 2e 0a 2a 2f 0a 69 6e  aragraphs..*/.in
36d40 74 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28  t sqlite3_sleep(
36d50 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
36d60 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54  I3REF: Name Of T
36d70 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e  he Folder Holdin
36d80 67 20 54 65 6d 70 6f 72 61 72 79 20 46 69 6c 65  g Temporary File
36d90 73 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 69  s.**.** ^(If thi
36da0 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c  s global variabl
36db0 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69  e is made to poi
36dc0 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77  nt to a string w
36dd0 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e  hich is.** the n
36de0 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20  ame of a folder 
36df0 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72  (a.k.a. director
36e00 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d  y), then all tem
36e10 70 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20  porary files.** 
36e20 63 72 65 61 74 65 64 20 62 79 20 53 51 4c 69 74  created by SQLit
36e30 65 20 77 68 65 6e 20 75 73 69 6e 67 20 61 20 62  e when using a b
36e40 75 69 6c 74 2d 69 6e 20 5b 73 71 6c 69 74 65 33  uilt-in [sqlite3
36e50 5f 76 66 73 20 7c 20 56 46 53 5d 0a 2a 2a 20 77  _vfs | VFS].** w
36e60 69 6c 6c 20 62 65 20 70 6c 61 63 65 64 20 69 6e  ill be placed in
36e70 20 74 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e   that directory.
36e80 29 5e 20 20 5e 49 66 20 74 68 69 73 20 76 61 72  )^  ^If this var
36e90 69 61 62 6c 65 0a 2a 2a 20 69 73 20 61 20 4e 55  iable.** is a NU
36ea0 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
36eb0 20 53 51 4c 69 74 65 20 70 65 72 66 6f 72 6d 73   SQLite performs
36ec0 20 61 20 73 65 61 72 63 68 20 66 6f 72 20 61 6e   a search for an
36ed0 20 61 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20   appropriate.** 
36ee0 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 20 64  temporary file d
36ef0 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20  irectory..**.** 
36f00 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
36f10 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79  o read or modify
36f20 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69   this variable i
36f30 6e 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a  n more than one.
36f40 2a 2a 20 74 68 72 65 61 64 20 61 74 20 61 20 74  ** thread at a t
36f50 69 6d 65 2e 20 20 49 74 20 69 73 20 6e 6f 74 20  ime.  It is not 
36f60 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20  safe to read or 
36f70 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69  modify this vari
36f80 61 62 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61  able.** if a [da
36f90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
36fa0 6e 5d 20 69 73 20 62 65 69 6e 67 20 75 73 65 64  n] is being used
36fb0 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
36fc0 65 20 69 6e 20 61 20 73 65 70 61 72 61 74 65 0a  e in a separate.
36fd0 2a 2a 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74  ** thread..** It
36fe0 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61   is intended tha
36ff0 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  t this variable 
37000 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61  be set once.** a
37010 73 20 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73  s part of proces
37020 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  s initialization
37030 20 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20   and before any 
37040 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
37050 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76  .** routines hav
37060 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e  e been called an
37070 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69  d that this vari
37080 61 62 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63 68  able remain unch
37090 61 6e 67 65 64 0a 2a 2a 20 74 68 65 72 65 61 66  anged.** thereaf
370a0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
370b0 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65  [temp_store_dire
370c0 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d 61  ctory pragma] ma
370d0 79 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61  y modify this va
370e0 72 69 61 62 6c 65 20 61 6e 64 20 63 61 75 73 65  riable and cause
370f0 0a 2a 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 20  .** it to point 
37100 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
37110 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
37120 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74  _malloc].  ^Furt
37130 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20  hermore,.** the 
37140 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65  [temp_store_dire
37150 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 6c  ctory pragma] al
37160 77 61 79 73 20 61 73 73 75 6d 65 73 20 74 68 61  ways assumes tha
37170 74 20 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20  t any string.** 
37180 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62  that this variab
37190 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20  le points to is 
371a0 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f  held in memory o
371b0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a  btained from .**
371c0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
371d0 5d 20 61 6e 64 20 74 68 65 20 70 72 61 67 6d 61  ] and the pragma
371e0 20 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20   may attempt to 
371f0 66 72 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 79  free that memory
37200 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  .** using [sqlit
37210 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e  e3_free]..** Hen
37220 63 65 2c 20 69 66 20 74 68 69 73 20 76 61 72 69  ce, if this vari
37230 61 62 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 64  able is modified
37240 20 64 69 72 65 63 74 6c 79 2c 20 65 69 74 68 65   directly, eithe
37250 72 20 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a  r it should be.*
37260 2a 20 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d  * made NULL or m
37270 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
37280 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
37290 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
372a0 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65  lloc].** or else
372b0 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 20   the use of the 
372c0 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65  [temp_store_dire
372d0 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 68  ctory pragma] sh
372e0 6f 75 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e  ould be avoided.
372f0 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74  .**.** <b>Note t
37300 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d  o Windows Runtim
37310 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68  e users:</b>  Th
37320 65 20 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65  e temporary dire
37330 63 74 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65  ctory must be se
37340 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61  t.** prior to ca
37350 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f  lling [sqlite3_o
37360 70 65 6e 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  pen] or [sqlite3
37370 5f 6f 70 65 6e 5f 76 32 5d 2e 20 20 4f 74 68 65  _open_v2].  Othe
37380 72 77 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a  rwise, various.*
37390 2a 20 66 65 61 74 75 72 65 73 20 74 68 61 74 20  * features that 
373a0 72 65 71 75 69 72 65 20 74 68 65 20 75 73 65 20  require the use 
373b0 6f 66 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  of temporary fil
373c0 65 73 20 6d 61 79 20 66 61 69 6c 2e 20 20 48 65  es may fail.  He
373d0 72 65 20 69 73 20 61 6e 0a 2a 2a 20 65 78 61 6d  re is an.** exam
373e0 70 6c 65 20 6f 66 20 68 6f 77 20 74 6f 20 64 6f  ple of how to do
373f0 20 74 68 69 73 20 75 73 69 6e 67 20 43 2b 2b 20   this using C++ 
37400 77 69 74 68 20 74 68 65 20 57 69 6e 64 6f 77 73  with the Windows
37410 20 52 75 6e 74 69 6d 65 3a 0a 2a 2a 0a 2a 2a 20   Runtime:.**.** 
37420 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
37430 3e 0a 2a 2a 20 4c 50 43 57 53 54 52 20 7a 50 61  >.** LPCWSTR zPa
37440 74 68 20 3d 20 57 69 6e 64 6f 77 73 3a 3a 53 74  th = Windows::St
37450 6f 72 61 67 65 3a 3a 41 70 70 6c 69 63 61 74 69  orage::Applicati
37460 6f 6e 44 61 74 61 3a 3a 43 75 72 72 65 6e 74 2d  onData::Current-
37470 3e 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20 20 20  >.** &nbsp;     
37480 54 65 6d 70 6f 72 61 72 79 46 6f 6c 64 65 72 2d  TemporaryFolder-
37490 3e 50 61 74 68 2d 3e 44 61 74 61 28 29 3b 0a 2a  >Path->Data();.*
374a0 2a 20 63 68 61 72 20 7a 50 61 74 68 42 75 66 26  * char zPathBuf&
374b0 23 39 31 3b 4d 41 58 5f 50 41 54 48 20 2b 20 31  #91;MAX_PATH + 1
374c0 26 23 39 33 3b 3b 0a 2a 2a 20 6d 65 6d 73 65 74  &#93;;.** memset
374d0 28 7a 50 61 74 68 42 75 66 2c 20 30 2c 20 73 69  (zPathBuf, 0, si
374e0 7a 65 6f 66 28 7a 50 61 74 68 42 75 66 29 29 3b  zeof(zPathBuf));
374f0 0a 2a 2a 20 57 69 64 65 43 68 61 72 54 6f 4d 75  .** WideCharToMu
37500 6c 74 69 42 79 74 65 28 43 50 5f 55 54 46 38 2c  ltiByte(CP_UTF8,
37510 20 30 2c 20 7a 50 61 74 68 2c 20 2d 31 2c 20 7a   0, zPath, -1, z
37520 50 61 74 68 42 75 66 2c 20 73 69 7a 65 6f 66 28  PathBuf, sizeof(
37530 7a 50 61 74 68 42 75 66 29 2c 0a 2a 2a 20 26 6e  zPathBuf),.** &n
37540 62 73 70 3b 20 20 20 20 20 4e 55 4c 4c 2c 20 4e  bsp;     NULL, N
37550 55 4c 4c 29 3b 0a 2a 2a 20 73 71 6c 69 74 65 33  ULL);.** sqlite3
37560 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 20  _temp_directory 
37570 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  = sqlite3_mprint
37580 66 28 22 25 73 22 2c 20 7a 50 61 74 68 42 75 66  f("%s", zPathBuf
37590 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
375a0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2f 0a 53 51 4c  ockquote>.*/.SQL
375b0 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20  ITE_EXTERN char 
375c0 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69  *sqlite3_temp_di
375d0 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20  rectory;../*.** 
375e0 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f  CAPI3REF: Name O
375f0 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c  f The Folder Hol
37600 64 69 6e 67 20 44 61 74 61 62 61 73 65 20 46 69  ding Database Fi
37610 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74  les.**.** ^(If t
37620 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61  his global varia
37630 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70  ble is made to p
37640 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67  oint to a string
37650 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65   which is.** the
37660 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65   name of a folde
37670 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74  r (a.k.a. direct
37680 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 64  ory), then all d
37690 61 74 61 62 61 73 65 20 66 69 6c 65 73 0a 2a 2a  atabase files.**
376a0 20 73 70 65 63 69 66 69 65 64 20 77 69 74 68 20   specified with 
376b0 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 6e  a relative pathn
376c0 61 6d 65 20 61 6e 64 20 63 72 65 61 74 65 64 20  ame and created 
376d0 6f 72 20 61 63 63 65 73 73 65 64 20 62 79 0a 2a  or accessed by.*
376e0 2a 20 53 51 4c 69 74 65 20 77 68 65 6e 20 75 73  * SQLite when us
376f0 69 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e 20 77  ing a built-in w
37700 69 6e 64 6f 77 73 20 5b 73 71 6c 69 74 65 33 5f  indows [sqlite3_
37710 76 66 73 20 7c 20 56 46 53 5d 20 77 69 6c 6c 20  vfs | VFS] will 
37720 62 65 20 61 73 73 75 6d 65 64 0a 2a 2a 20 74 6f  be assumed.** to
37730 20 62 65 20 72 65 6c 61 74 69 76 65 20 74 6f 20   be relative to 
37740 74 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e 29  that directory.)
37750 5e 20 5e 49 66 20 74 68 69 73 20 76 61 72 69 61  ^ ^If this varia
37760 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 0a 2a 2a  ble is a NULL.**
37770 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53   pointer, then S
37780 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68  QLite assumes th
37790 61 74 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20  at all database 
377a0 66 69 6c 65 73 20 73 70 65 63 69 66 69 65 64 0a  files specified.
377b0 2a 2a 20 77 69 74 68 20 61 20 72 65 6c 61 74 69  ** with a relati
377c0 76 65 20 70 61 74 68 6e 61 6d 65 20 61 72 65 20  ve pathname are 
377d0 72 65 6c 61 74 69 76 65 20 74 6f 20 74 68 65 20  relative to the 
377e0 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72  current director
377f0 79 0a 2a 2a 20 66 6f 72 20 74 68 65 20 70 72 6f  y.** for the pro
37800 63 65 73 73 2e 20 20 4f 6e 6c 79 20 74 68 65 20  cess.  Only the 
37810 77 69 6e 64 6f 77 73 20 56 46 53 20 6d 61 6b 65  windows VFS make
37820 73 20 75 73 65 20 6f 66 20 74 68 69 73 20 67 6c  s use of this gl
37830 6f 62 61 6c 0a 2a 2a 20 76 61 72 69 61 62 6c 65  obal.** variable
37840 3b 20 69 74 20 69 73 20 69 67 6e 6f 72 65 64 20  ; it is ignored 
37850 62 79 20 74 68 65 20 75 6e 69 78 20 56 46 53 2e  by the unix VFS.
37860 0a 2a 2a 0a 2a 2a 20 43 68 61 6e 67 69 6e 67 20  .**.** Changing 
37870 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 69  the value of thi
37880 73 20 76 61 72 69 61 62 6c 65 20 77 68 69 6c 65  s variable while
37890 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
378a0 65 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 6f 70 65  ection is.** ope
378b0 6e 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20  n can result in 
378c0 61 20 63 6f 72 72 75 70 74 20 64 61 74 61 62 61  a corrupt databa
378d0 73 65 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20  se..**.** It is 
378e0 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64  not safe to read
378f0 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20   or modify this 
37900 76 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65  variable in more
37910 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72   than one.** thr
37920 65 61 64 20 61 74 20 61 20 74 69 6d 65 2e 20 20  ead at a time.  
37930 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
37940 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79  o read or modify
37950 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a   this variable.*
37960 2a 20 69 66 20 61 20 5b 64 61 74 61 62 61 73 65  * if a [database
37970 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20   connection] is 
37980 62 65 69 6e 67 20 75 73 65 64 20 61 74 20 74 68  being used at th
37990 65 20 73 61 6d 65 20 74 69 6d 65 20 69 6e 20 61  e same time in a
379a0 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 74 68 72   separate.** thr
379b0 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e  ead..** It is in
379c0 74 65 6e 64 65 64 20 74 68 61 74 20 74 68 69 73  tended that this
379d0 20 76 61 72 69 61 62 6c 65 20 62 65 20 73 65 74   variable be set
379e0 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74   once.** as part
379f0 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74   of process init
37a00 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62  ialization and b
37a10 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65  efore any SQLite
37a20 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f   interface.** ro
37a30 75 74 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e  utines have been
37a40 20 63 61 6c 6c 65 64 20 61 6e 64 20 74 68 61 74   called and that
37a50 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 72   this variable r
37a60 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a  emain unchanged.
37a70 2a 2a 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a  ** thereafter..*
37a80 2a 0a 2a 2a 20 5e 54 68 65 20 5b 64 61 74 61 5f  *.** ^The [data_
37a90 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
37aa0 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69  pragma] may modi
37ab0 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  fy this variable
37ac0 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 74   and cause.** it
37ad0 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d   to point to mem
37ae0 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
37af0 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
37b00 63 5d 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f 72  c].  ^Furthermor
37b10 65 2c 0a 2a 2a 20 74 68 65 20 5b 64 61 74 61 5f  e,.** the [data_
37b20 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
37b30 70 72 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 61  pragma] always a
37b40 73 73 75 6d 65 73 20 74 68 61 74 20 61 6e 79 20  ssumes that any 
37b50 73 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74  string.** that t
37b60 68 69 73 20 76 61 72 69 61 62 6c 65 20 70 6f 69  his variable poi
37b70 6e 74 73 20 74 6f 20 69 73 20 68 65 6c 64 20 69  nts to is held i
37b80 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  n memory obtaine
37b90 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69  d from .** [sqli
37ba0 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20  te3_malloc] and 
37bb0 74 68 65 20 70 72 61 67 6d 61 20 6d 61 79 20 61  the pragma may a
37bc0 74 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74  ttempt to free t
37bd0 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73  hat memory.** us
37be0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  ing [sqlite3_fre
37bf0 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66  e]..** Hence, if
37c00 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69   this variable i
37c10 73 20 6d 6f 64 69 66 69 65 64 20 64 69 72 65 63  s modified direc
37c20 74 6c 79 2c 20 65 69 74 68 65 72 20 69 74 20 73  tly, either it s
37c30 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65  hould be.** made
37c40 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f   NULL or made to
37c50 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79   point to memory
37c60 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
37c70 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a  sqlite3_malloc].
37c80 2a 2a 20 6f 72 20 65 6c 73 65 20 74 68 65 20 75  ** or else the u
37c90 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 5f  se of the [data_
37ca0 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
37cb0 70 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62  pragma] should b
37cc0 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51  e avoided..*/.SQ
37cd0 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72  LITE_EXTERN char
37ce0 20 2a 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 64   *sqlite3_data_d
37cf0 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a  irectory;../*.**
37d00 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 20   CAPI3REF: Test 
37d10 46 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20  For Auto-Commit 
37d20 4d 6f 64 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  Mode.** KEYWORDS
37d30 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  : {autocommit mo
37d40 64 65 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  de}.**.** ^The s
37d50 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63  qlite3_get_autoc
37d60 6f 6d 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63  ommit() interfac
37d70 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  e returns non-ze
37d80 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66  ro or.** zero if
37d90 20 74 68 65 20 67 69 76 65 6e 20 64 61 74 61 62   the given datab
37da0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
37db0 73 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61  s or is not in a
37dc0 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a  utocommit mode,.
37dd0 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  ** respectively.
37de0 20 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f    ^Autocommit mo
37df0 64 65 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61  de is on by defa
37e00 75 6c 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d  ult..** ^Autocom
37e10 6d 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61  mit mode is disa
37e20 62 6c 65 64 20 62 79 20 61 20 5b 42 45 47 49 4e  bled by a [BEGIN
37e30 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20  ] statement..** 
37e40 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65  ^Autocommit mode
37e50 20 69 73 20 72 65 2d 65 6e 61 62 6c 65 64 20 62   is re-enabled b
37e60 79 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20  y a [COMMIT] or 
37e70 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a  [ROLLBACK]..**.*
37e80 2a 20 49 66 20 63 65 72 74 61 69 6e 20 6b 69 6e  * If certain kin
37e90 64 73 20 6f 66 20 65 72 72 6f 72 73 20 6f 63 63  ds of errors occ
37ea0 75 72 20 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e  ur on a statemen
37eb0 74 20 77 69 74 68 69 6e 20 61 20 6d 75 6c 74 69  t within a multi
37ec0 2d 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72  -statement.** tr
37ed0 61 6e 73 61 63 74 69 6f 6e 20 28 65 72 72 6f 72  ansaction (error
37ee0 73 20 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c  s including [SQL
37ef0 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49  ITE_FULL], [SQLI
37f00 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53  TE_IOERR],.** [S
37f10 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53  QLITE_NOMEM], [S
37f20 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64  QLITE_BUSY], and
37f30 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
37f40 50 54 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a  PT]) then the.**
37f50 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67   transaction mig
37f60 68 74 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63  ht be rolled bac
37f70 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  k automatically.
37f80 20 20 54 68 65 20 6f 6e 6c 79 20 77 61 79 20 74    The only way t
37f90 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77 68  o.** find out wh
37fa0 65 74 68 65 72 20 53 51 4c 69 74 65 20 61 75 74  ether SQLite aut
37fb0 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65  omatically rolle
37fc0 64 20 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73  d back the trans
37fd0 61 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20  action after.** 
37fe0 61 6e 20 65 72 72 6f 72 20 69 73 20 74 6f 20 75  an error is to u
37ff0 73 65 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  se this function
38000 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68  ..**.** If anoth
38010 65 72 20 74 68 72 65 61 64 20 63 68 61 6e 67 65  er thread change
38020 73 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74  s the autocommit
38030 20 73 74 61 74 75 73 20 6f 66 20 74 68 65 20 64   status of the d
38040 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
38050 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 73  ction while this
38060 20 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e   routine is runn
38070 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65  ing, then the re
38080 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 73  turn value.** is
38090 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69   undefined..*/.i
380a0 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  nt sqlite3_get_a
380b0 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65  utocommit(sqlite
380c0 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
380d0 33 52 45 46 3a 20 46 69 6e 64 20 54 68 65 20 44  3REF: Find The D
380e0 61 74 61 62 61 73 65 20 48 61 6e 64 6c 65 20 4f  atabase Handle O
380f0 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  f A Prepared Sta
38100 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  tement.**.** ^Th
38110 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e  e sqlite3_db_han
38120 64 6c 65 20 69 6e 74 65 72 66 61 63 65 20 72 65  dle interface re
38130 74 75 72 6e 73 20 74 68 65 20 5b 64 61 74 61 62  turns the [datab
38140 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
38150 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 68 69  handle.** to whi
38160 63 68 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  ch a [prepared s
38170 74 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67  tatement] belong
38180 73 2e 20 20 5e 54 68 65 20 5b 64 61 74 61 62 61  s.  ^The [databa
38190 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a  se connection].*
381a0 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  * returned by sq
381b0 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20  lite3_db_handle 
381c0 69 73 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  is the same [dat
381d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
381e0 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 74 68  ].** that was th
381f0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
38200 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  .** to the [sqli
38210 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
38220 5d 20 63 61 6c 6c 20 28 6f 72 20 69 74 73 20 76  ] call (or its v
38230 61 72 69 61 6e 74 73 29 20 74 68 61 74 20 77 61  ariants) that wa
38240 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72 65  s used to.** cre
38250 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e  ate the statemen
38260 74 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 70  t in the first p
38270 6c 61 63 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  lace..*/.sqlite3
38280 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e   *sqlite3_db_han
38290 64 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  dle(sqlite3_stmt
382a0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
382b0 52 45 46 3a 20 52 65 74 75 72 6e 20 54 68 65 20  REF: Return The 
382c0 46 69 6c 65 6e 61 6d 65 20 46 6f 72 20 41 20 44  Filename For A D
382d0 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
382e0 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  on.**.** ^The sq
382f0 6c 69 74 65 33 5f 64 62 5f 66 69 6c 65 6e 61 6d  lite3_db_filenam
38300 65 28 44 2c 4e 29 20 69 6e 74 65 72 66 61 63 65  e(D,N) interface
38310 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
38320 65 72 20 74 6f 20 61 20 66 69 6c 65 6e 61 6d 65  er to a filename
38330 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
38340 69 74 68 20 64 61 74 61 62 61 73 65 20 4e 20 6f  ith database N o
38350 66 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20  f connection D. 
38360 20 5e 54 68 65 20 6d 61 69 6e 20 64 61 74 61 62   ^The main datab
38370 61 73 65 20 66 69 6c 65 0a 2a 2a 20 68 61 73 20  ase file.** has 
38380 74 68 65 20 6e 61 6d 65 20 22 6d 61 69 6e 22 2e  the name "main".
38390 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f    If there is no
383a0 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
383b0 73 65 20 4e 20 6f 6e 20 74 68 65 20 64 61 74 61  se N on the data
383c0 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
383d0 6f 6e 20 44 2c 20 6f 72 20 69 66 20 64 61 74 61  on D, or if data
383e0 62 61 73 65 20 4e 20 69 73 20 61 20 74 65 6d 70  base N is a temp
383f0 6f 72 61 72 79 20 6f 72 20 69 6e 2d 6d 65 6d 6f  orary or in-memo
38400 72 79 20 64 61 74 61 62 61 73 65 2c 20 74 68 65  ry database, the
38410 6e 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  n.** a NULL poin
38420 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ter is returned.
38430 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 6c 65  .**.** ^The file
38440 6e 61 6d 65 20 72 65 74 75 72 6e 65 64 20 62 79  name returned by
38450 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69   this function i
38460 73 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66 20  s the output of 
38470 74 68 65 0a 2a 2a 20 78 46 75 6c 6c 50 61 74 68  the.** xFullPath
38480 6e 61 6d 65 20 6d 65 74 68 6f 64 20 6f 66 20 74  name method of t
38490 68 65 20 5b 56 46 53 5d 2e 20 20 5e 49 6e 20 6f  he [VFS].  ^In o
384a0 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
384b0 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c  filename.** will
384c0 20 62 65 20 61 6e 20 61 62 73 6f 6c 75 74 65 20   be an absolute 
384d0 70 61 74 68 6e 61 6d 65 2c 20 65 76 65 6e 20 69  pathname, even i
384e0 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 75  f the filename u
384f0 73 65 64 0a 2a 2a 20 74 6f 20 6f 70 65 6e 20 74  sed.** to open t
38500 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 69 67  he database orig
38510 69 6e 61 6c 6c 79 20 77 61 73 20 61 20 55 52 49  inally was a URI
38520 20 6f 72 20 72 65 6c 61 74 69 76 65 20 70 61 74   or relative pat
38530 68 6e 61 6d 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  hname..*/.const 
38540 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 64 62  char *sqlite3_db
38550 5f 66 69 6c 65 6e 61 6d 65 28 73 71 6c 69 74 65  _filename(sqlite
38560 33 20 2a 64 62 2c 20 63 6f 6e 73 74 20 63 68 61  3 *db, const cha
38570 72 20 2a 7a 44 62 4e 61 6d 65 29 3b 0a 0a 2f 2a  r *zDbName);../*
38580 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
38590 74 65 72 6d 69 6e 65 20 69 66 20 61 20 64 61 74  termine if a dat
385a0 61 62 61 73 65 20 69 73 20 72 65 61 64 2d 6f 6e  abase is read-on
385b0 6c 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ly.**.** ^The sq
385c0 6c 69 74 65 33 5f 64 62 5f 72 65 61 64 6f 6e 6c  lite3_db_readonl
385d0 79 28 44 2c 4e 29 20 69 6e 74 65 72 66 61 63 65  y(D,N) interface
385e0 20 72 65 74 75 72 6e 73 20 31 20 69 66 20 74 68   returns 1 if th
385f0 65 20 64 61 74 61 62 61 73 65 20 4e 0a 2a 2a 20  e database N.** 
38600 6f 66 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 20  of connection D 
38610 69 73 20 72 65 61 64 2d 6f 6e 6c 79 2c 20 30 20  is read-only, 0 
38620 69 66 20 69 74 20 69 73 20 72 65 61 64 2f 77 72  if it is read/wr
38630 69 74 65 2c 20 6f 72 20 2d 31 20 69 66 20 4e 20  ite, or -1 if N 
38640 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 6e 61  is not.** the na
38650 6d 65 20 6f 66 20 61 20 64 61 74 61 62 61 73 65  me of a database
38660 20 6f 6e 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44   on connection D
38670 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
38680 5f 64 62 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c  _db_readonly(sql
38690 69 74 65 33 20 2a 64 62 2c 20 63 6f 6e 73 74 20  ite3 *db, const 
386a0 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 29 3b 0a  char *zDbName);.
386b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
386c0 20 46 69 6e 64 20 74 68 65 20 6e 65 78 74 20 70   Find the next p
386d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
386e0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e  t.**.** ^This in
386f0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
38700 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
38710 20 6e 65 78 74 20 5b 70 72 65 70 61 72 65 64 20   next [prepared 
38720 73 74 61 74 65 6d 65 6e 74 5d 20 61 66 74 65 72  statement] after
38730 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f 63 69  .** pStmt associ
38740 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64  ated with the [d
38750 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
38760 6f 6e 5d 20 70 44 62 2e 20 20 5e 49 66 20 70 53  on] pDb.  ^If pS
38770 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 74  tmt is NULL.** t
38780 68 65 6e 20 74 68 69 73 20 69 6e 74 65 72 66 61  hen this interfa
38790 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
387a0 6e 74 65 72 20 74 6f 20 74 68 65 20 66 69 72 73  nter to the firs
387b0 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  t prepared state
387c0 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63 69 61 74  ment.** associat
387d0 65 64 20 77 69 74 68 20 74 68 65 20 64 61 74 61  ed with the data
387e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
387f0 70 44 62 2e 20 20 5e 49 66 20 6e 6f 20 70 72 65  pDb.  ^If no pre
38800 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
38810 2a 2a 20 73 61 74 69 73 66 69 65 73 20 74 68 65  ** satisfies the
38820 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66 20 74   conditions of t
38830 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 69 74 20  his routine, it 
38840 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a  returns NULL..**
38850 0a 2a 2a 20 54 68 65 20 5b 64 61 74 61 62 61 73  .** The [databas
38860 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 6f  e connection] po