/ Hex Artifact Content
Login

Artifact c83230953bb3b8cca7aaa75d408a92b4e271a5f4:


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 74 68  ust not close th
3e90: 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
3ea0: 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65  ection] specifie
3eb0: 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65  d by.**      the
3ec0: 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74   1st parameter t
3ed0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
3ee0: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65   while sqlite3_e
3ef0: 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  xec() is running
3f00: 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70  ..** <li> The ap
3f10: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
3f20: 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51  ot modify the SQ
3f30: 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
3f40: 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20   passed into.** 
3f50: 20 20 20 20 20 74 68 65 20 32 6e 64 20 70 61 72       the 2nd par
3f60: 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65  ameter of sqlite
3f70: 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73  3_exec() while s
3f80: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3f90: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75   running..** </u
3fa0: 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l>.*/.int sqlite
3fb0: 33 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65  3_exec(.  sqlite
3fc0: 33 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  3*,             
3fd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fe0: 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20       /* An open 
3ff0: 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f  database */.  co
4000: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20  nst 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 20 20 20 20 2f 2a 20 53 51 4c 20           /* SQL 
4030: 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20  to be evaluated 
4040: 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62  */.  int (*callb
4050: 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  ack)(void*,int,c
4060: 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20  har**,char**),  
4070: 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63  /* Callback func
4080: 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  tion */.  void *
4090: 2c 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 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75       /* 1st argu
40c0: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b  ment to callback
40d0: 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72   */.  char **err
40e0: 6d 73 67 20 20 20 20 20 20 20 20 20 20 20 20 20  msg             
40f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4100: 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72   /* Error msg wr
4110: 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b  itten here */.);
4120: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
4130: 3a 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a  : Result Codes.*
4140: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49  * KEYWORDS: SQLI
4150: 54 45 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f 64  TE_OK {error cod
4160: 65 7d 20 7b 65 72 72 6f 72 20 63 6f 64 65 73 7d  e} {error codes}
4170: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72  .** KEYWORDS: {r
4180: 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 72 65 73  esult code} {res
4190: 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a  ult codes}.**.**
41a0: 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e   Many SQLite fun
41b0: 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e  ctions return an
41c0: 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20   integer result 
41d0: 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65  code from the se
41e0: 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20  t shown.** here 
41f0: 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69  in order to indi
4200: 63 61 74 65 20 73 75 63 63 65 73 73 20 6f 72 20  cate success or 
4210: 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e  failure..**.** N
4220: 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20 6d  ew error codes m
4230: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
4240: 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
4250: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
4260: 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54  See also: [SQLIT
4270: 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65  E_IOERR_READ | e
4280: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
4290: 6f 64 65 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  odes],.** [sqlit
42a0: 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c  e3_vtab_on_confl
42b0: 69 63 74 28 29 5d 20 5b 53 51 4c 49 54 45 5f 52  ict()] [SQLITE_R
42c0: 4f 4c 4c 42 41 43 4b 20 7c 20 72 65 73 75 6c 74  OLLBACK | result
42d0: 20 63 6f 64 65 73 5d 2e 0a 2a 2f 0a 23 64 65 66   codes]..*/.#def
42e0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20  ine SQLITE_OK   
42f0: 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53          0   /* S
4300: 75 63 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74  uccessful result
4310: 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67   */./* beginning
4320: 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20  -of-error-codes 
4330: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4340: 45 5f 45 52 52 4f 52 20 20 20 20 20 20 20 20 31  E_ERROR        1
4350: 20 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20     /* SQL error 
4360: 6f 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62  or missing datab
4370: 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ase */.#define S
4380: 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20  QLITE_INTERNAL  
4390: 20 20 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e     2   /* Intern
43a0: 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69  al logic error i
43b0: 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66  n SQLite */.#def
43c0: 69 6e 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20  ine SQLITE_PERM 
43d0: 20 20 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41          3   /* A
43e0: 63 63 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e  ccess permission
43f0: 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69   denied */.#defi
4400: 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20  ne SQLITE_ABORT 
4410: 20 20 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61         4   /* Ca
4420: 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72  llback routine r
4430: 65 71 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72  equested an abor
4440: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
4450: 49 54 45 5f 42 55 53 59 20 20 20 20 20 20 20 20  ITE_BUSY        
4460: 20 35 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61   5   /* The data
4470: 62 61 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63  base file is loc
4480: 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ked */.#define S
4490: 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20  QLITE_LOCKED    
44a0: 20 20 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c     6   /* A tabl
44b0: 65 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73  e in the databas
44c0: 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23  e is locked */.#
44d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
44e0: 4d 45 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f  MEM        7   /
44f0: 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69  * A malloc() fai
4500: 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  led */.#define S
4510: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20  QLITE_READONLY  
4520: 20 20 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70     8   /* Attemp
4530: 74 20 74 6f 20 77 72 69 74 65 20 61 20 72 65 61  t to write a rea
4540: 64 6f 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a  donly database *
4550: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4560: 5f 49 4e 54 45 52 52 55 50 54 20 20 20 20 39 20  _INTERRUPT    9 
4570: 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74    /* Operation t
4580: 65 72 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c  erminated by sql
4590: 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
45a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
45b0: 45 5f 49 4f 45 52 52 20 20 20 20 20 20 20 31 30  E_IOERR       10
45c0: 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20     /* Some kind 
45d0: 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f  of disk I/O erro
45e0: 72 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64  r occurred */.#d
45f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52  efine SQLITE_COR
4600: 52 55 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a  RUPT     11   /*
4610: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 64 69   The database di
4620: 73 6b 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66  sk image is malf
4630: 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ormed */.#define
4640: 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44   SQLITE_NOTFOUND
4650: 20 20 20 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e      12   /* Unkn
4660: 6f 77 6e 20 6f 70 63 6f 64 65 20 69 6e 20 73 71  own opcode in sq
4670: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
4680: 6f 6c 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ol() */.#define 
4690: 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20  SQLITE_FULL     
46a0: 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72     13   /* Inser
46b0: 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61  tion failed beca
46c0: 75 73 65 20 64 61 74 61 62 61 73 65 20 69 73 20  use database is 
46d0: 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20  full */.#define 
46e0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
46f0: 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c     14   /* Unabl
4700: 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61  e to open the da
4710: 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23  tabase file */.#
4720: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52  define SQLITE_PR
4730: 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f  OTOCOL    15   /
4740: 2a 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20  * Database lock 
4750: 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a  protocol error *
4760: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4770: 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31 36 20  _EMPTY       16 
4780: 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69 73    /* Database is
4790: 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e   empty */.#defin
47a0: 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20  e SQLITE_SCHEMA 
47b0: 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65       17   /* The
47c0: 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
47d0: 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66   changed */.#def
47e0: 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49  ine SQLITE_TOOBI
47f0: 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53  G      18   /* S
4800: 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78  tring or BLOB ex
4810: 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74  ceeds size limit
4820: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4830: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31  TE_CONSTRAINT  1
4840: 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65  9   /* Abort due
4850: 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 76   to constraint v
4860: 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66  iolation */.#def
4870: 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41  ine SQLITE_MISMA
4880: 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44  TCH    20   /* D
4890: 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63  ata type mismatc
48a0: 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  h */.#define SQL
48b0: 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20  ITE_MISUSE      
48c0: 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20  21   /* Library 
48d0: 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79  used incorrectly
48e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
48f0: 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32  TE_NOLFS       2
4900: 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66  2   /* Uses OS f
4910: 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70  eatures not supp
4920: 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f  orted on host */
4930: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4940: 41 55 54 48 20 20 20 20 20 20 20 20 32 33 20 20  AUTH        23  
4950: 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f   /* Authorizatio
4960: 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66  n denied */.#def
4970: 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41  ine SQLITE_FORMA
4980: 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 41  T      24   /* A
4990: 75 78 69 6c 69 61 72 79 20 64 61 74 61 62 61 73  uxiliary databas
49a0: 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a  e format error *
49b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
49c0: 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32 35 20  _RANGE       25 
49d0: 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74    /* 2nd paramet
49e0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
49f0: 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20  nd out of range 
4a00: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4a10: 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36  E_NOTADB      26
4a20: 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65     /* File opene
4a30: 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20  d that is not a 
4a40: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f  database file */
4a50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4a60: 4e 4f 54 49 43 45 20 20 20 20 20 20 32 37 20 20  NOTICE      27  
4a70: 20 2f 2a 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e   /* Notification
4a80: 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c  s from sqlite3_l
4a90: 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  og() */.#define 
4aa0: 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 20  SQLITE_WARNING  
4ab0: 20 20 20 32 38 20 20 20 2f 2a 20 57 61 72 6e 69     28   /* Warni
4ac0: 6e 67 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ngs from sqlite3
4ad0: 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e  _log() */.#defin
4ae0: 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20  e SQLITE_ROW    
4af0: 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c       100  /* sql
4b00: 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20  ite3_step() has 
4b10: 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64  another row read
4b20: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4b30: 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20  ITE_DONE        
4b40: 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  101  /* sqlite3_
4b50: 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69 73  step() has finis
4b60: 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f  hed executing */
4b70: 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72  ./* end-of-error
4b80: 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  -codes */../*.**
4b90: 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e   CAPI3REF: Exten
4ba0: 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73  ded Result Codes
4bb0: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65  .** KEYWORDS: {e
4bc0: 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
4bd0: 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65 72  de} {extended er
4be0: 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45  ror codes}.** KE
4bf0: 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65  YWORDS: {extende
4c00: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b  d result code} {
4c10: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
4c20: 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  codes}.**.** In 
4c30: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
4c40: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
4c50: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
4c60: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20  eturn one of 26 
4c70: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49  integer.** [SQLI
4c80: 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63  TE_OK | result c
4c90: 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c  odes].  However,
4ca0: 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73 20   experience has 
4cb0: 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79 20  shown that many 
4cc0: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73 75  of.** these resu
4cd0: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f 6f  lt codes are too
4ce0: 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64 2e   coarse-grained.
4cf0: 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 72    They do not pr
4d00: 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68  ovide as.** much
4d10: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
4d20: 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 70  ut problems as p
4d30: 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74  rogrammers might
4d40: 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66   like.  In an ef
4d50: 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65  fort to.** addre
4d60: 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20 76  ss this, newer v
4d70: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4d80: 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38  e (version 3.3.8
4d90: 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c   and later) incl
4da0: 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66  ude.** support f
4db0: 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65  or additional re
4dc0: 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20  sult codes that 
4dd0: 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74  provide more det
4de0: 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f  ailed informatio
4df0: 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72  n.** about error
4e00: 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64 20  s. The extended 
4e10: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4e20: 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
4e30: 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72  bled.** on a per
4e40: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
4e50: 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67  tion basis using
4e60: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
4e70: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
4e80: 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a  _codes()] API..*
4e90: 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65  *.** Some of the
4ea0: 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65 6e   available exten
4eb0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4ec0: 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 72 65   are listed here
4ed0: 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70  ..** One may exp
4ee0: 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ect the number o
4ef0: 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  f extended resul
4f00: 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 69 6e 63  t codes will inc
4f10: 72 65 61 73 65 0a 2a 2a 20 6f 76 65 72 20 74 69  rease.** over ti
4f20: 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68  me.  Software th
4f30: 61 74 20 75 73 65 73 20 65 78 74 65 6e 64 65 64  at uses extended
4f40: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 73 68   result codes sh
4f50: 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20 74  ould expect.** t
4f60: 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75 6c 74  o see new result
4f70: 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75 72 65   codes in future
4f80: 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
4f90: 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  ite..**.** The S
4fa0: 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20  QLITE_OK result 
4fb0: 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  code will never 
4fc0: 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20 49 74  be extended.  It
4fd0: 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20   will always.** 
4fe0: 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e  be exactly zero.
4ff0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
5000: 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20  TE_IOERR_READ   
5010: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5020: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38  TE_IOERR | (1<<8
5030: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5040: 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45  E_IOERR_SHORT_RE
5050: 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  AD        (SQLIT
5060: 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29  E_IOERR | (2<<8)
5070: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5080: 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20  _IOERR_WRITE    
5090: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
50a0: 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29  _IOERR | (3<<8))
50b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
50c0: 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20  IOERR_FSYNC     
50d0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
50e0: 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a  IOERR | (4<<8)).
50f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5100: 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20  OERR_DIR_FSYNC  
5110: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5120: 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23  OERR | (5<<8)).#
5130: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5140: 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20  ERR_TRUNCATE    
5150: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5160: 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64  ERR | (6<<8)).#d
5170: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5180: 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20 20  RR_FSTAT        
5190: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
51a0: 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65  RR | (7<<8)).#de
51b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
51c0: 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_UNLOCK        
51d0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
51e0: 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66  R | (8<<8)).#def
51f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5200: 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  _RDLOCK         
5210: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5220: 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69   | (9<<8)).#defi
5230: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5240: 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20  DELETE          
5250: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5260: 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69  | (10<<8)).#defi
5270: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5280: 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20 20  BLOCKED         
5290: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
52a0: 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69  | (11<<8)).#defi
52b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
52c0: 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20 20  NOMEM           
52d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
52e0: 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 69  | (12<<8)).#defi
52f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5300: 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20 20  ACCESS          
5310: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5320: 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 69  | (13<<8)).#defi
5330: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5340: 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f 43  CHECKRESERVEDLOC
5350: 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20  K (SQLITE_IOERR 
5360: 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 69  | (14<<8)).#defi
5370: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5380: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20  LOCK            
5390: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
53a0: 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 69  | (15<<8)).#defi
53b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
53c0: 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20 20  CLOSE           
53d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
53e0: 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 69  | (16<<8)).#defi
53f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5400: 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20  DIR_CLOSE       
5410: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5420: 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 69  | (17<<8)).#defi
5430: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5440: 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20 20  SHMOPEN         
5450: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5460: 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66 69  | (18<<8)).#defi
5470: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5480: 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20 20  SHMSIZE         
5490: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
54a0: 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66 69  | (19<<8)).#defi
54b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
54c0: 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  SHMLOCK         
54d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
54e0: 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66 69  | (20<<8)).#defi
54f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5500: 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20  SHMMAP          
5510: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5520: 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66 69  | (21<<8)).#defi
5530: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5540: 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20 20  SEEK            
5550: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5560: 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66 69  | (22<<8)).#defi
5570: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5580: 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20 20  DELETE_NOENT    
5590: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
55a0: 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66 69  | (23<<8)).#defi
55b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
55c0: 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20  MMAP            
55d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
55e0: 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66 69  | (24<<8)).#defi
55f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5600: 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20 20  GETTEMPPATH     
5610: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5620: 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66 69  | (25<<8)).#defi
5630: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5640: 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20 20  CONVPATH        
5650: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5660: 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66 69  | (26<<8)).#defi
5670: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44  ne SQLITE_LOCKED
5680: 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20  _SHAREDCACHE    
5690: 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44    (SQLITE_LOCKED
56a0: 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66   |  (1<<8)).#def
56b0: 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f  ine SQLITE_BUSY_
56c0: 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 20  RECOVERY        
56d0: 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20     (SQLITE_BUSY 
56e0: 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65    |  (1<<8)).#de
56f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
5700: 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20 20  _SNAPSHOT       
5710: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
5720: 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64     |  (2<<8)).#d
5730: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
5740: 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20  TOPEN_NOTEMPDIR 
5750: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
5760: 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a  TOPEN | (1<<8)).
5770: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5780: 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20 20  ANTOPEN_ISDIR   
5790: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
57a0: 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29  ANTOPEN | (2<<8)
57b0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
57c0: 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 41  _CANTOPEN_FULLPA
57d0: 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  TH       (SQLITE
57e0: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c 3c  _CANTOPEN | (3<<
57f0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5800: 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e 56  TE_CANTOPEN_CONV
5810: 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49  PATH       (SQLI
5820: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 34  TE_CANTOPEN | (4
5830: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5840: 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54 41  LITE_CORRUPT_VTA
5850: 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  B            (SQ
5860: 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20 28  LITE_CORRUPT | (
5870: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5880: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52  QLITE_READONLY_R
5890: 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28 53  ECOVERY       (S
58a0: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c  QLITE_READONLY |
58b0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
58c0: 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59   SQLITE_READONLY
58d0: 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20  _CANTLOCK       
58e0: 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59  (SQLITE_READONLY
58f0: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
5900: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e  ne SQLITE_READON
5910: 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20  LY_ROLLBACK     
5920: 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e    (SQLITE_READON
5930: 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65  LY | (3<<8)).#de
5940: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52  fine SQLITE_ABOR
5950: 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20  T_ROLLBACK      
5960: 20 20 20 20 28 53 51 4c 49 54 45 5f 41 42 4f 52      (SQLITE_ABOR
5970: 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  T | (2<<8)).#def
5980: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5990: 52 41 49 4e 54 5f 43 48 45 43 4b 20 20 20 20 20  RAINT_CHECK     
59a0: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
59b0: 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38 29 29 0a  RAINT | (1<<8)).
59c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
59d0: 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d 4d 49 54  ONSTRAINT_COMMIT
59e0: 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54 45 5f 43  HOOK   (SQLITE_C
59f0: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 32 3c 3c  ONSTRAINT | (2<<
5a00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5a10: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 4f  TE_CONSTRAINT_FO
5a20: 52 45 49 47 4e 4b 45 59 20 20 20 28 53 51 4c 49  REIGNKEY   (SQLI
5a30: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5a40: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (3<<8)).#define 
5a50: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5a60: 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 28  T_FUNCTION     (
5a70: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5a80: 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66  T | (4<<8)).#def
5a90: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5aa0: 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20  RAINT_NOTNULL   
5ab0: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5ac0: 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38 29 29 0a  RAINT | (5<<8)).
5ad0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5ae0: 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49 4d 41 52  ONSTRAINT_PRIMAR
5af0: 59 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43  YKEY   (SQLITE_C
5b00: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 36 3c 3c  ONSTRAINT | (6<<
5b10: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5b20: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 54 52  TE_CONSTRAINT_TR
5b30: 49 47 47 45 52 20 20 20 20 20 20 28 53 51 4c 49  IGGER      (SQLI
5b40: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5b50: 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (7<<8)).#define 
5b60: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5b70: 54 5f 55 4e 49 51 55 45 20 20 20 20 20 20 20 28  T_UNIQUE       (
5b80: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5b90: 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66  T | (8<<8)).#def
5ba0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5bb0: 52 41 49 4e 54 5f 56 54 41 42 20 20 20 20 20 20  RAINT_VTAB      
5bc0: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5bd0: 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38 29 29 0a  RAINT | (9<<8)).
5be0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5bf0: 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57 49 44 20  ONSTRAINT_ROWID 
5c00: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
5c10: 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31 30 3c 3c  ONSTRAINT |(10<<
5c20: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5c30: 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45  TE_NOTICE_RECOVE
5c40: 52 5f 57 41 4c 20 20 20 20 20 20 28 53 51 4c 49  R_WAL      (SQLI
5c50: 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 31 3c 3c  TE_NOTICE | (1<<
5c60: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5c70: 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45  TE_NOTICE_RECOVE
5c80: 52 5f 52 4f 4c 4c 42 41 43 4b 20 28 53 51 4c 49  R_ROLLBACK (SQLI
5c90: 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 32 3c 3c  TE_NOTICE | (2<<
5ca0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5cb0: 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55 54 4f 49  TE_WARNING_AUTOI
5cc0: 4e 44 45 58 20 20 20 20 20 20 20 28 53 51 4c 49  NDEX       (SQLI
5cd0: 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20 28 31 3c  TE_WARNING | (1<
5ce0: 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  <8))../*.** CAPI
5cf0: 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20  3REF: Flags For 
5d00: 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74  File Open Operat
5d10: 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
5d20: 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65 20   bit values are 
5d30: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
5d40: 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70   in the.** 3rd p
5d50: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
5d60: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
5d70: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e  ()] interface an
5d80: 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20  d.** in the 4th 
5d90: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
5da0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
5db0: 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a  pen] method..*/.
5dc0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5dd0: 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20  PEN_READONLY    
5de0: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31 20       0x00000001 
5df0: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
5e00: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
5e10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5e20: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20  PEN_READWRITE   
5e30: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 20       0x00000002 
5e40: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
5e50: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
5e60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5e70: 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20  PEN_CREATE      
5e80: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 20       0x00000004 
5e90: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
5ea0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
5eb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5ec0: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
5ed0: 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38 20  E    0x00000008 
5ee0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
5ef0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5f00: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20  PEN_EXCLUSIVE   
5f10: 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 20       0x00000010 
5f20: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
5f30: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5f40: 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20 20  PEN_AUTOPROXY   
5f50: 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30 20       0x00000020 
5f60: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
5f70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5f80: 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20 20  PEN_URI         
5f90: 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30 20       0x00000040 
5fa0: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
5fb0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
5fc0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5fd0: 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20  PEN_MEMORY      
5fe0: 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30 20       0x00000080 
5ff0: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
6000: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
6010: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6020: 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20  PEN_MAIN_DB     
6030: 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30 20       0x00000100 
6040: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
6050: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6060: 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20  PEN_TEMP_DB     
6070: 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30 20       0x00000200 
6080: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
6090: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
60a0: 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42  PEN_TRANSIENT_DB
60b0: 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 20       0x00000400 
60c0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
60d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
60e0: 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c  PEN_MAIN_JOURNAL
60f0: 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30 20       0x00000800 
6100: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
6110: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6120: 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c  PEN_TEMP_JOURNAL
6130: 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30 20       0x00001000 
6140: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
6150: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6160: 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20  PEN_SUBJOURNAL  
6170: 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30 20       0x00002000 
6180: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
6190: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
61a0: 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e  PEN_MASTER_JOURN
61b0: 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30 20  AL   0x00004000 
61c0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
61d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
61e0: 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20  PEN_NOMUTEX     
61f0: 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30 20       0x00008000 
6200: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
6210: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
6220: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6230: 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20  PEN_FULLMUTEX   
6240: 20 20 20 20 20 30 78 30 30 30 31 30 30 30 30 20       0x00010000 
6250: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
6260: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
6270: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6280: 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20  PEN_SHAREDCACHE 
6290: 20 20 20 20 20 30 78 30 30 30 32 30 30 30 30 20       0x00020000 
62a0: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
62b0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
62c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
62d0: 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
62e0: 20 20 20 20 20 30 78 30 30 30 34 30 30 30 30 20       0x00040000 
62f0: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
6300: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
6310: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6320: 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20 20  PEN_WAL         
6330: 20 20 20 20 20 30 78 30 30 30 38 30 30 30 30 20       0x00080000 
6340: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
6350: 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 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 20 20 20 30 78 30 30 46 30 30 30 30 30        0x00F00000
6380: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
6390: 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 72  REF: Device Char
63a0: 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a  acteristics.**.*
63b0: 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61  * The xDeviceCha
63c0: 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74  racteristics met
63d0: 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  hod of the [sqli
63e0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
63f0: 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ** object return
6400: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
6410: 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f  ch is a vector o
6420: 66 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76  f these.** bit v
6430: 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e 67  alues expressing
6440: 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73   I/O characteris
6450: 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73  tics of the mass
6460: 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69   storage.** devi
6470: 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68  ce that holds th
6480: 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65 20  e file that the 
6490: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
64a0: 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74  ods].** refers t
64b0: 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  o..**.** The SQL
64c0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
64d0: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
64e0: 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20  that all writes 
64f0: 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61  of.** any size a
6500: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
6510: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6520: 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a  MICnnn values.**
6530: 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65   mean that write
6540: 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74  s of blocks that
6550: 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69   are nnn bytes i
6560: 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72  n size and.** ar
6570: 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
6580: 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73  address which is
6590: 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74   an integer mult
65a0: 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61  iple of.** nnn a
65b0: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
65c0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
65d0: 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d  E_APPEND value m
65e0: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65  eans.** that whe
65f0: 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  n data is append
6600: 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68  ed to a file, th
6610: 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  e data is append
6620: 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e  ed.** first then
6630: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
6640: 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65   file is extende
6650: 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68  d, never the oth
6660: 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64  er.** way around
6670: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
6680: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70  CAP_SEQUENTIAL p
6690: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
66a0: 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  at.** informatio
66b0: 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20  n is written to 
66c0: 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65  disk in the same
66d0: 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a   order as calls.
66e0: 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 20  ** to xWrite(). 
66f0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6700: 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  P_POWERSAFE_OVER
6710: 57 52 49 54 45 20 70 72 6f 70 65 72 74 79 20 6d  WRITE property m
6720: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66 74  eans that.** aft
6730: 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77  er reboot follow
6740: 69 6e 67 20 61 20 63 72 61 73 68 20 6f 72 20 70  ing a crash or p
6750: 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f  ower loss, the o
6760: 6e 6c 79 20 62 79 74 65 73 20 69 6e 20 61 0a 2a  nly bytes in a.*
6770: 2a 20 66 69 6c 65 20 74 68 61 74 20 77 65 72 65  * file that were
6780: 20 77 72 69 74 74 65 6e 20 61 74 20 74 68 65 20   written at the 
6790: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65  application leve
67a0: 6c 20 6d 69 67 68 74 20 68 61 76 65 20 63 68 61  l might have cha
67b0: 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74  nged.** and that
67c0: 20 61 64 6a 61 63 65 6e 74 20 62 79 74 65 73 2c   adjacent bytes,
67d0: 20 65 76 65 6e 20 62 79 74 65 73 20 77 69 74 68   even bytes with
67e0: 69 6e 20 74 68 65 20 73 61 6d 65 20 73 65 63 74  in the same sect
67f0: 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e  or are.** guaran
6800: 74 65 65 64 20 74 6f 20 62 65 20 75 6e 63 68 61  teed to be uncha
6810: 6e 67 65 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  nged..*/.#define
6820: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6830: 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20 20 20  OMIC            
6840: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a       0x00000001.
6850: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6860: 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20  OCAP_ATOMIC512  
6870: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6880: 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53  000002.#define S
6890: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
68a0: 49 43 31 4b 20 20 20 20 20 20 20 20 20 20 20 20  IC1K            
68b0: 20 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64     0x00000004.#d
68c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
68d0: 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20  AP_ATOMIC2K     
68e0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
68f0: 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c  0008.#define SQL
6900: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6910: 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  4K              
6920: 20 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66   0x00000010.#def
6930: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6940: 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20  _ATOMIC8K       
6950: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6960: 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  20.#define SQLIT
6970: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36  E_IOCAP_ATOMIC16
6980: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  K              0
6990: 78 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e  x00000040.#defin
69a0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
69b0: 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20  TOMIC32K        
69c0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30        0x00000080
69d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
69e0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20  IOCAP_ATOMIC64K 
69f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6a00: 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20  0000100.#define 
6a10: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
6a20: 45 5f 41 50 50 45 4e 44 20 20 20 20 20 20 20 20  E_APPEND        
6a30: 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23      0x00000200.#
6a40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6a50: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20  CAP_SEQUENTIAL  
6a60: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6a70: 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00400.#define SQ
6a80: 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c  LITE_IOCAP_UNDEL
6a90: 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e  ETABLE_WHEN_OPEN
6aa0: 20 20 30 78 30 30 30 30 30 38 30 30 0a 23 64 65    0x00000800.#de
6ab0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6ac0: 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  P_POWERSAFE_OVER
6ad0: 57 52 49 54 45 20 20 20 20 30 78 30 30 30 30 31  WRITE    0x00001
6ae0: 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  000../*.** CAPI3
6af0: 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e  REF: File Lockin
6b00: 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53  g Levels.**.** S
6b10: 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f  QLite uses one o
6b20: 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  f these integer 
6b30: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65  values as the se
6b40: 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  cond.** argument
6b50: 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b   to calls it mak
6b60: 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28  es to the xLock(
6b70: 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20  ) and xUnlock() 
6b80: 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e  methods.** of an
6b90: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
6ba0: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f  hods] object..*/
6bb0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6bc0: 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20  LOCK_NONE       
6bd0: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
6be0: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20  ITE_LOCK_SHARED 
6bf0: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
6c00: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53   SQLITE_LOCK_RES
6c10: 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 65  ERVED      2.#de
6c20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
6c30: 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33  _PENDING       3
6c40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6c50: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20  LOCK_EXCLUSIVE  
6c60: 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     4../*.** CAPI
6c70: 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a  3REF: Synchroniz
6c80: 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73  ation Type Flags
6c90: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69  .**.** When SQLi
6ca0: 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78  te invokes the x
6cb0: 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66  Sync() method of
6cc0: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
6cd0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
6ce0: 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d  ct it uses a com
6cf0: 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74  bination of.** t
6d00: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c  hese integer val
6d10: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ues as the secon
6d20: 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
6d30: 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54  * When the SQLIT
6d40: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
6d50: 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74  flag is used, it
6d60: 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a   means that the.
6d70: 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  ** sync operatio
6d80: 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  n only needs to 
6d90: 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61  flush data to ma
6da0: 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f  ss storage.  Ino
6db0: 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  de.** informatio
6dc0: 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c  n need not be fl
6dd0: 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c 6f  ushed. If the lo
6de0: 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f 66  wer four bits of
6df0: 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75   the flag.** equ
6e00: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  al SQLITE_SYNC_N
6e10: 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e  ORMAL, that mean
6e20: 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20  s to use normal 
6e30: 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63  fsync() semantic
6e40: 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77  s..** If the low
6e50: 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 71 75  er four bits equ
6e60: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  al SQLITE_SYNC_F
6e70: 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a  ULL, that means.
6e80: 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53  ** to use Mac OS
6e90: 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e   X style fullsyn
6ea0: 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79  c instead of fsy
6eb0: 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e  nc()..**.** Do n
6ec0: 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65 20 53  ot confuse the S
6ed0: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
6ee0: 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e  L and SQLITE_SYN
6ef0: 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20  C_FULL flags.** 
6f00: 77 69 74 68 20 74 68 65 20 5b 50 52 41 47 4d 41  with the [PRAGMA
6f10: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f   synchronous]=NO
6f20: 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d 41  RMAL and [PRAGMA
6f30: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 55   synchronous]=FU
6f40: 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e 20  LL.** settings. 
6f50: 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f 75   The [synchronou
6f60: 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65 72 6d  s pragma] determ
6f70: 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c 73 20  ines when calls 
6f80: 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63 20  to the.** xSync 
6f90: 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 75 72  VFS method occur
6fa0: 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75 6e 69   and applies uni
6fb0: 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 61 6c  formly across al
6fc0: 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20  l platforms..** 
6fd0: 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  The SQLITE_SYNC_
6fe0: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54  NORMAL and SQLIT
6ff0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67  E_SYNC_FULL flag
7000: 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f 77 0a  s determine how.
7010: 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f 72 20  ** energetic or 
7020: 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72 63  rigorous or forc
7030: 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20 6f 70  eful the sync op
7040: 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61 6e 64  erations are and
7050: 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 20  .** only make a 
7060: 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d 61  difference on Ma
7070: 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20 64 65  c OSX for the de
7080: 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63 6f 64  fault SQLite cod
7090: 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61 72  e..** (Third-par
70a0: 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ty VFS implement
70b0: 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c 73  ations might als
70c0: 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69  o make the disti
70d0: 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65  nction.** betwee
70e0: 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  n SQLITE_SYNC_NO
70f0: 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f  RMAL and SQLITE_
7100: 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20 61  SYNC_FULL, but a
7110: 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65 72  mong the.** oper
7120: 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20 6e 61  ating systems na
7130: 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74 65 64  tively supported
7140: 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c 79   by SQLite, only
7150: 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72 65   Mac OSX.** care
7160: 73 20 61 62 6f 75 74 20 74 68 65 20 64 69 66 66  s about the diff
7170: 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 66  erence.).*/.#def
7180: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
7190: 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78  NORMAL        0x
71a0: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
71b0: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20  LITE_SYNC_FULL  
71c0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33 0a          0x00003.
71d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
71e0: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20  YNC_DATAONLY    
71f0: 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a    0x00010../*.**
7200: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
7210: 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c  terface Open Fil
7220: 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41  e Handle.**.** A
7230: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  n [sqlite3_file]
7240: 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
7250: 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  ts an open file 
7260: 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69  in the .** [sqli
7270: 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74  te3_vfs | OS int
7280: 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20 20  erface layer].  
7290: 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e  Individual OS in
72a0: 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65  terface.** imple
72b0: 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a  mentations will.
72c0: 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c  ** want to subcl
72d0: 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20  ass this object 
72e0: 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64  by appending add
72f0: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a  itional fields.*
7300: 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20  * for their own 
7310: 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f  use.  The pMetho
7320: 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f  ds entry is a po
7330: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b  inter to an.** [
7340: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7350: 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20  ds] object that 
7360: 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20  defines methods 
7370: 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a  for performing.*
7380: 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73  * I/O operations
7390: 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c   on the open fil
73a0: 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  e..*/.typedef st
73b0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c  ruct sqlite3_fil
73c0: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a  e sqlite3_file;.
73d0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66  struct sqlite3_f
73e0: 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74  ile {.  const st
73f0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
7400: 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64  methods *pMethod
7410: 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66  s;  /* Methods f
7420: 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  or an open file 
7430: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
7440: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
7450: 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c  ace File Virtual
7460: 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a   Methods Object.
7470: 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65  **.** Every file
7480: 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b   opened by the [
7490: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
74a0: 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61  n] method popula
74b0: 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74  tes an.** [sqlit
74c0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
74d0: 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e  (or, more common
74e0: 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f  ly, a subclass o
74f0: 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
7500: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20  3_file] object) 
7510: 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74  with a pointer t
7520: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
7530: 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a   this object..**
7540: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66   This object def
7550: 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73  ines the methods
7560: 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d   used to perform
7570: 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69   various operati
7580: 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74  ons.** against t
7590: 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70  he open file rep
75a0: 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 65 20  resented by the 
75b0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
75c0: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  bject..**.** If 
75d0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
75e0: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 73  .xOpen] method s
75f0: 65 74 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ets the sqlite3_
7600: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c  file.pMethods el
7610: 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 6e  ement .** to a n
7620: 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c  on-NULL pointer,
7630: 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
7640: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 6c  3_io_methods.xCl
7650: 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61  ose method.** ma
7660: 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 76 65  y be invoked eve
7670: 6e 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74 65  n if the [sqlite
7680: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65 70  3_vfs.xOpen] rep
7690: 6f 72 74 65 64 20 74 68 61 74 20 69 74 20 66 61  orted that it fa
76a0: 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e  iled.  The.** on
76b0: 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76 65 6e  ly way to preven
76c0: 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c 6f  t a call to xClo
76d0: 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66  se following a f
76e0: 61 69 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f 76  ailed [sqlite3_v
76f0: 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20  fs.xOpen].** is 
7700: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33  for the [sqlite3
7710: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20 73  _vfs.xOpen] to s
7720: 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  et the sqlite3_f
7730: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65  ile.pMethods ele
7740: 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e  ment.** to NULL.
7750: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73  .**.** The flags
7760: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79   argument to xSy
7770: 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66  nc may be one of
7780: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f   [SQLITE_SYNC_NO
7790: 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  RMAL] or.** [SQL
77a0: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20  ITE_SYNC_FULL]. 
77b0: 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69 63   The first choic
77c0: 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20  e is the normal 
77d0: 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20  fsync()..** The 
77e0: 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73  second choice is
77f0: 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c   a Mac OS X styl
7800: 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65  e fullsync.  The
7810: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41   [SQLITE_SYNC_DA
7820: 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20  TAONLY].** flag 
7830: 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20 74  may be ORed in t
7840: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20  o indicate that 
7850: 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66  only the data of
7860: 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64   the file.** and
7870: 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 6e   not its inode n
7880: 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63 65  eeds to be synce
7890: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74  d..**.** The int
78a0: 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78  eger values to x
78b0: 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f  Lock() and xUnlo
78c0: 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a  ck() are one of.
78d0: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
78e0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e  [SQLITE_LOCK_NON
78f0: 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  E],.** <li> [SQL
7900: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d  ITE_LOCK_SHARED]
7910: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
7920: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d  E_LOCK_RESERVED]
7930: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
7940: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c  E_LOCK_PENDING],
7950: 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c   or.** <li> [SQL
7960: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
7970: 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  VE]..** </ul>.**
7980: 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73   xLock() increas
7990: 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e  es the lock. xUn
79a0: 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65 73  lock() decreases
79b0: 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68   the lock..** Th
79c0: 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 65 64  e xCheckReserved
79d0: 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 68  Lock() method ch
79e0: 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e 79  ecks whether any
79f0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
7a00: 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20  tion,.** either 
7a10: 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73 20  in this process 
7a20: 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72  or in some other
7a30: 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c   process, is hol
7a40: 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 44 2c  ding a RESERVED,
7a50: 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20  .** PENDING, or 
7a60: 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f  EXCLUSIVE lock o
7a70: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20  n the file.  It 
7a80: 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20  returns true.** 
7a90: 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65  if such a lock e
7aa0: 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20  xists and false 
7ab0: 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a  otherwise..**.**
7ac0: 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   The xFileContro
7ad0: 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20  l() method is a 
7ae0: 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63  generic interfac
7af0: 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75  e that allows cu
7b00: 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c  stom.** VFS impl
7b10: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64  ementations to d
7b20: 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20  irectly control 
7b30: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69  an open file usi
7b40: 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
7b50: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
7b60: 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54  )] interface.  T
7b70: 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61  he second "op" a
7b80: 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a  rgument is an.**
7b90: 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e   integer opcode.
7ba0: 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75    The third argu
7bb0: 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69  ment is a generi
7bc0: 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64  c pointer intend
7bd0: 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74  ed to.** point t
7be0: 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74 68  o a structure th
7bf0: 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61  at may contain a
7c00: 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63  rguments or spac
7c10: 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a  e in which to.**
7c20: 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76 61   write return va
7c30: 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c  lues.  Potential
7c40: 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43   uses for xFileC
7c50: 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62  ontrol() might b
7c60: 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74  e.** functions t
7c70: 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e  o enable blockin
7c80: 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d  g locks with tim
7c90: 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65  eouts, to change
7ca0: 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20   the.** locking 
7cb0: 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65 78  strategy (for ex
7cc0: 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74  ample to use dot
7cd0: 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f  -file locks), to
7ce0: 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75   inquire.** abou
7cf0: 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 20  t the status of 
7d00: 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72  a lock, or to br
7d10: 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e  eak stale locks.
7d20: 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20    The SQLite.** 
7d30: 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 61 6c  core reserves al
7d40: 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74  l opcodes less t
7d50: 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20  han 100 for its 
7d60: 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 53  own use..** A [S
7d70: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b  QLITE_FCNTL_LOCK
7d80: 53 54 41 54 45 20 7c 20 6c 69 73 74 20 6f 66 20  STATE | list of 
7d90: 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68  opcodes] less th
7da0: 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61  an 100 is availa
7db0: 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ble..** Applicat
7dc0: 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65  ions that define
7dd0: 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43   a custom xFileC
7de0: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68  ontrol method sh
7df0: 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73  ould use opcodes
7e00: 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e  .** greater than
7e10: 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f   100 to avoid co
7e20: 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 20 69 6d  nflicts.  VFS im
7e30: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68  plementations sh
7e40: 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  ould.** return [
7e50: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d  SQLITE_NOTFOUND]
7e60: 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f   for file contro
7e70: 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 74 20 74  l opcodes that t
7e80: 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65  hey do not.** re
7e90: 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54  cognize..**.** T
7ea0: 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29  he xSectorSize()
7eb0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
7ec0: 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20  the sector size 
7ed0: 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65  of the.** device
7ee0: 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20   that underlies 
7ef0: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73  the file.  The s
7f00: 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68  ector size is th
7f10: 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69  e.** minimum wri
7f20: 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70  te that can be p
7f30: 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74  erformed without
7f40: 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f   disturbing.** o
7f50: 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68  ther bytes in th
7f60: 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65  e file.  The xDe
7f70: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
7f80: 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20  ics().** method 
7f90: 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65  returns a bit ve
7fa0: 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20  ctor describing 
7fb0: 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65  behaviors of the
7fc0: 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64  .** underlying d
7fd0: 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  evice:.**.** <ul
7fe0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
7ff0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a  E_IOCAP_ATOMIC].
8000: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8010: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d  IOCAP_ATOMIC512]
8020: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8030: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d  _IOCAP_ATOMIC1K]
8040: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8050: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d  _IOCAP_ATOMIC2K]
8060: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8070: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d  _IOCAP_ATOMIC4K]
8080: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8090: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d  _IOCAP_ATOMIC8K]
80a0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
80b0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b  _IOCAP_ATOMIC16K
80c0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
80d0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32  E_IOCAP_ATOMIC32
80e0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
80f0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
8100: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
8110: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
8120: 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  PPEND].** <li> [
8130: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
8140: 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c  UENTIAL].** </ul
8150: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  >.**.** The SQLI
8160: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
8170: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
8180: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f  hat all writes o
8190: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72  f.** any size ar
81a0: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
81b0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
81c0: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20  ICnnn values.** 
81d0: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73  mean that writes
81e0: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20   of blocks that 
81f0: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e  are nnn bytes in
8200: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65   size and.** are
8210: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61   aligned to an a
8220: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20  ddress which is 
8230: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69  an integer multi
8240: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72  ple of.** nnn ar
8250: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
8260: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
8270: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65  _APPEND value me
8280: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e  ans.** that when
8290: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
82a0: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65  d to a file, the
82b0: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
82c0: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20  d.** first then 
82d0: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
82e0: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64  file is extended
82f0: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65  , never the othe
8300: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e  r.** way around.
8310: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
8320: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72  AP_SEQUENTIAL pr
8330: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
8340: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  t.** information
8350: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64   is written to d
8360: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20  isk in the same 
8370: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a  order as calls.*
8380: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a  * to xWrite()..*
8390: 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20  *.** If xRead() 
83a0: 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49  returns SQLITE_I
83b0: 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20  OERR_SHORT_READ 
83c0: 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c  it must also fil
83d0: 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65  l.** in the unre
83e0: 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74  ad portions of t
83f0: 68 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a  he buffer with z
8400: 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61  eros.  A VFS tha
8410: 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65  t.** fails to ze
8420: 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65  ro-fill short re
8430: 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74  ads might seem t
8440: 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72  o work.  However
8450: 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20  ,.** failure to 
8460: 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20  zero-fill short 
8470: 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74  reads will event
8480: 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a  ually lead to.**
8490: 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70   database corrup
84a0: 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  tion..*/.typedef
84b0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
84c0: 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74  io_methods sqlit
84d0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73  e3_io_methods;.s
84e0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
84f0: 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74  _methods {.  int
8500: 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74   iVersion;.  int
8510: 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74   (*xClose)(sqlit
8520: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
8530: 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65   (*xRead)(sqlite
8540: 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20  3_file*, void*, 
8550: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65  int iAmt, sqlite
8560: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a  3_int64 iOfst);.
8570: 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28    int (*xWrite)(
8580: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63  sqlite3_file*, c
8590: 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20  onst void*, int 
85a0: 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e  iAmt, sqlite3_in
85b0: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e  t64 iOfst);.  in
85c0: 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73  t (*xTruncate)(s
85d0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
85e0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65  lite3_int64 size
85f0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63  );.  int (*xSync
8600: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8610: 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69   int flags);.  i
8620: 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28  nt (*xFileSize)(
8630: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
8640: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53  qlite3_int64 *pS
8650: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c  ize);.  int (*xL
8660: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
8670: 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20  e*, int);.  int 
8680: 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74  (*xUnlock)(sqlit
8690: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a  e3_file*, int);.
86a0: 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65    int (*xCheckRe
86b0: 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69  servedLock)(sqli
86c0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a  te3_file*, int *
86d0: 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20  pResOut);.  int 
86e0: 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28  (*xFileControl)(
86f0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8700: 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72  nt op, void *pAr
8710: 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63  g);.  int (*xSec
8720: 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33  torSize)(sqlite3
8730: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
8740: 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65  *xDeviceCharacte
8750: 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33  ristics)(sqlite3
8760: 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65  _file*);.  /* Me
8770: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
8780: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f  valid for versio
8790: 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  n 1 */.  int (*x
87a0: 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f  ShmMap)(sqlite3_
87b0: 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20  file*, int iPg, 
87c0: 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76  int pgsz, int, v
87d0: 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b  oid volatile**);
87e0: 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63  .  int (*xShmLoc
87f0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
8800: 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e  , int offset, in
8810: 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b  t n, int flags);
8820: 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61  .  void (*xShmBa
8830: 72 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66  rrier)(sqlite3_f
8840: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ile*);.  int (*x
8850: 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65  ShmUnmap)(sqlite
8860: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c  3_file*, int del
8870: 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d  eteFlag);.  /* M
8880: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
8890: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
88a0: 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  on 2 */.  int (*
88b0: 78 46 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f  xFetch)(sqlite3_
88c0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
88d0: 6e 74 36 34 20 69 4f 66 73 74 2c 20 69 6e 74 20  nt64 iOfst, int 
88e0: 69 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29  iAmt, void **pp)
88f0: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66 65 74  ;.  int (*xUnfet
8900: 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ch)(sqlite3_file
8910: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
8920: 20 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70 29   iOfst, void *p)
8930: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
8940: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
8950: 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a  or version 3 */.
8960: 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20    /* Additional 
8970: 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61  methods may be a
8980: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
8990: 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f  eleases */.};../
89a0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
89b0: 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e  tandard File Con
89c0: 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 0a  trol Opcodes.**.
89d0: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  ** These integer
89e0: 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f   constants are o
89f0: 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78  pcodes for the x
8a00: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
8a10: 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  od.** of the [sq
8a20: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
8a30: 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72  ] object and for
8a40: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
8a50: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a  le_control()].**
8a60: 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
8a70: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
8a80: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f  NTL_LOCKSTATE] o
8a90: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f  pcode is used fo
8aa0: 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68  r debugging.  Th
8ab0: 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75  is.** opcode cau
8ac0: 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e  ses the xFileCon
8ad0: 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77  trol method to w
8ae0: 72 69 74 65 20 74 68 65 20 63 75 72 72 65 6e 74  rite the current
8af0: 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65   state of.** the
8b00: 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53   lock (one of [S
8b10: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d  QLITE_LOCK_NONE]
8b20: 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  , [SQLITE_LOCK_S
8b30: 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  HARED],.** [SQLI
8b40: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44  TE_LOCK_RESERVED
8b50: 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ], [SQLITE_LOCK_
8b60: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51  PENDING], or [SQ
8b70: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
8b80: 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e  IVE]).** into an
8b90: 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 74 68   integer that th
8ba0: 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20  e pArg argument 
8bb0: 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20  points to. This 
8bc0: 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73  capability.** is
8bd0: 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73   used during tes
8be0: 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65  ting and only ne
8bf0: 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72  eds to be suppor
8c00: 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f  ted when SQLITE_
8c10: 54 45 53 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e  TEST.** is defin
8c20: 65 64 2e 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  ed..** <ul>.** <
8c30: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
8c40: 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a  L_SIZE_HINT]].**
8c50: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
8c60: 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70  TL_SIZE_HINT] op
8c70: 63 6f 64 65 20 69 73 20 75 73 65 64 20 62 79 20  code is used by 
8c80: 53 51 4c 69 74 65 20 74 6f 20 67 69 76 65 20 74  SQLite to give t
8c90: 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20  he VFS.** layer 
8ca0: 61 20 68 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61  a hint of how la
8cb0: 72 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  rge the database
8cc0: 20 66 69 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20   file will grow 
8cd0: 74 6f 20 62 65 20 64 75 72 69 6e 67 20 74 68 65  to be during the
8ce0: 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74 72 61 6e  .** current tran
8cf0: 73 61 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 68  saction.  This h
8d00: 69 6e 74 20 69 73 20 6e 6f 74 20 67 75 61 72 61  int is not guara
8d10: 6e 74 65 65 64 20 74 6f 20 62 65 20 61 63 63 75  nteed to be accu
8d20: 72 61 74 65 20 62 75 74 20 69 74 0a 2a 2a 20 69  rate but it.** i
8d30: 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20  s often close.  
8d40: 54 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 56  The underlying V
8d50: 46 53 20 6d 69 67 68 74 20 63 68 6f 6f 73 65 20  FS might choose 
8d60: 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74 65 20 64  to preallocate d
8d70: 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20  atabase.** file 
8d80: 73 70 61 63 65 20 62 61 73 65 64 20 6f 6e 20 74  space based on t
8d90: 68 69 73 20 68 69 6e 74 20 69 6e 20 6f 72 64 65  his hint in orde
8da0: 72 20 74 6f 20 68 65 6c 70 20 77 72 69 74 65 73  r to help writes
8db0: 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   to the database
8dc0: 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20 66 61 73  .** file run fas
8dd0: 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ter..**.** <li>[
8de0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48  [SQLITE_FCNTL_CH
8df0: 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68  UNK_SIZE]].** Th
8e00: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
8e10: 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f  CHUNK_SIZE] opco
8e20: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65  de is used to re
8e30: 71 75 65 73 74 20 74 68 61 74 20 74 68 65 20 56  quest that the V
8e40: 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e  FS.** extends an
8e50: 64 20 74 72 75 6e 63 61 74 65 73 20 74 68 65 20  d truncates the 
8e60: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 6e  database file in
8e70: 20 63 68 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a   chunks of a siz
8e80: 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62  e specified.** b
8e90: 79 20 74 68 65 20 75 73 65 72 2e 20 54 68 65 20  y the user. The 
8ea0: 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20  fourth argument 
8eb0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  to [sqlite3_file
8ec0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75  _control()] shou
8ed0: 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20  ld .** point to 
8ee0: 61 6e 20 69 6e 74 65 67 65 72 20 28 74 79 70 65  an integer (type
8ef0: 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67   int) containing
8f00: 20 74 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73   the new chunk-s
8f10: 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f  ize to use.** fo
8f20: 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20  r the nominated 
8f30: 64 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61  database. Alloca
8f40: 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 66 69  ting database fi
8f50: 6c 65 20 73 70 61 63 65 20 69 6e 20 6c 61 72 67  le space in larg
8f60: 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61 79  e.** chunks (say
8f70: 20 31 4d 42 20 61 74 20 61 20 74 69 6d 65 29 2c   1MB at a time),
8f80: 20 6d 61 79 20 72 65 64 75 63 65 20 66 69 6c 65   may reduce file
8f90: 2d 73 79 73 74 65 6d 20 66 72 61 67 6d 65 6e 74  -system fragment
8fa0: 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70  ation and.** imp
8fb0: 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65  rove performance
8fc0: 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d 73   on some systems
8fd0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
8fe0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f  LITE_FCNTL_FILE_
8ff0: 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65  POINTER]].** The
9000: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46   [SQLITE_FCNTL_F
9010: 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63  ILE_POINTER] opc
9020: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f  ode is used to o
9030: 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a  btain a pointer.
9040: 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ** to the [sqlit
9050: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
9060: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
9070: 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74  a particular dat
9080: 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
9090: 69 6f 6e 2e 20 20 53 65 65 20 74 68 65 20 5b 73  ion.  See the [s
90a0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
90b0: 72 6f 6c 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61  rol()] documenta
90c0: 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 61 64 64 69  tion for.** addi
90d0: 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
90e0: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  on..**.** <li>[[
90f0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
9100: 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 5e  C_OMITTED]].** ^
9110: 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  (The [SQLITE_FCN
9120: 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d  TL_SYNC_OMITTED]
9130: 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72   opcode is gener
9140: 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  ated internally 
9150: 62 79 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64  by.** SQLite and
9160: 20 73 65 6e 74 20 74 6f 20 61 6c 6c 20 56 46 53   sent to all VFS
9170: 65 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 61  es in place of a
9180: 20 63 61 6c 6c 20 74 6f 20 74 68 65 20 78 53 79   call to the xSy
9190: 6e 63 20 6d 65 74 68 6f 64 0a 2a 2a 20 77 68 65  nc method.** whe
91a0: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
91b0: 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 73 20 5b 50  onnection has [P
91c0: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
91d0: 73 5d 20 73 65 74 20 74 6f 20 4f 46 46 2e 29 5e  s] set to OFF.)^
91e0: 0a 2a 2a 20 53 6f 6d 65 20 73 70 65 63 69 61 6c  .** Some special
91f0: 69 7a 65 64 20 56 46 53 65 73 20 6e 65 65 64 20  ized VFSes need 
9200: 74 68 69 73 20 73 69 67 6e 61 6c 20 69 6e 20 6f  this signal in o
9210: 72 64 65 72 20 74 6f 20 6f 70 65 72 61 74 65 20  rder to operate 
9220: 63 6f 72 72 65 63 74 6c 79 0a 2a 2a 20 77 68 65  correctly.** whe
9230: 6e 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72  n [PRAGMA synchr
9240: 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41 20 73  onous | PRAGMA s
9250: 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20  ynchronous=OFF] 
9260: 69 73 20 73 65 74 2c 20 62 75 74 20 6d 6f 73 74  is set, but most
9270: 20 0a 2a 2a 20 56 46 53 65 73 20 64 6f 20 6e 6f   .** VFSes do no
9280: 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e  t need this sign
9290: 61 6c 20 61 6e 64 20 73 68 6f 75 6c 64 20 73 69  al and should si
92a0: 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68  lently ignore th
92b0: 69 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a 20 41 70  is opcode..** Ap
92c0: 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
92d0: 64 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69  d not call [sqli
92e0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
92f0: 28 29 5d 20 77 69 74 68 20 74 68 69 73 0a 2a 2a  ()] with this.**
9300: 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67   opcode as doing
9310: 20 73 6f 20 6d 61 79 20 64 69 73 72 75 70 74 20   so may disrupt 
9320: 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66  the operation of
9330: 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64   the specialized
9340: 20 56 46 53 65 73 0a 2a 2a 20 74 68 61 74 20 64   VFSes.** that d
9350: 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a  o require it.  .
9360: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9370: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41  TE_FCNTL_WIN32_A
9380: 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68  V_RETRY]].** ^Th
9390: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
93a0: 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 20  WIN32_AV_RETRY] 
93b0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
93c0: 6f 20 63 6f 6e 66 69 67 75 72 65 20 61 75 74 6f  o configure auto
93d0: 6d 61 74 69 63 0a 2a 2a 20 72 65 74 72 79 20 63  matic.** retry c
93e0: 6f 75 6e 74 73 20 61 6e 64 20 69 6e 74 65 72 76  ounts and interv
93f0: 61 6c 73 20 66 6f 72 20 63 65 72 74 61 69 6e 20  als for certain 
9400: 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69  disk I/O operati
9410: 6f 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77  ons for the.** w
9420: 69 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20  indows [VFS] in 
9430: 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65  order to provide
9440: 20 72 6f 62 75 73 74 6e 65 73 73 20 69 6e 20 74   robustness in t
9450: 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a  he presence of.*
9460: 2a 20 61 6e 74 69 2d 76 69 72 75 73 20 70 72 6f  * anti-virus pro
9470: 67 72 61 6d 73 2e 20 20 42 79 20 64 65 66 61 75  grams.  By defau
9480: 6c 74 2c 20 74 68 65 20 77 69 6e 64 6f 77 73 20  lt, the windows 
9490: 56 46 53 20 77 69 6c 6c 20 72 65 74 72 79 20 66  VFS will retry f
94a0: 69 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c  ile read,.** fil
94b0: 65 20 77 72 69 74 65 2c 20 61 6e 64 20 66 69 6c  e write, and fil
94c0: 65 20 64 65 6c 65 74 65 20 6f 70 65 72 61 74 69  e delete operati
94d0: 6f 6e 73 20 75 70 20 74 6f 20 31 30 20 74 69 6d  ons up to 10 tim
94e0: 65 73 2c 20 77 69 74 68 20 61 20 64 65 6c 61 79  es, with a delay
94f0: 0a 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73  .** of 25 millis
9500: 65 63 6f 6e 64 73 20 62 65 66 6f 72 65 20 74 68  econds before th
9510: 65 20 66 69 72 73 74 20 72 65 74 72 79 20 61 6e  e first retry an
9520: 64 20 77 69 74 68 20 74 68 65 20 64 65 6c 61 79  d with the delay
9530: 20 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62   increasing.** b
9540: 79 20 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20  y an additional 
9550: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  25 milliseconds 
9560: 77 69 74 68 20 65 61 63 68 20 73 75 62 73 65 71  with each subseq
9570: 75 65 6e 74 20 72 65 74 72 79 2e 20 20 54 68 69  uent retry.  Thi
9580: 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f  s.** opcode allo
9590: 77 73 20 74 68 65 73 65 20 74 77 6f 20 76 61 6c  ws these two val
95a0: 75 65 73 20 28 31 30 20 72 65 74 72 69 65 73 20  ues (10 retries 
95b0: 61 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f  and 25 milliseco
95c0: 6e 64 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a  nds of delay).**
95d0: 20 74 6f 20 62 65 20 61 64 6a 75 73 74 65 64 2e   to be adjusted.
95e0: 20 20 54 68 65 20 76 61 6c 75 65 73 20 61 72 65    The values are
95f0: 20 63 68 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c   changed for all
9600: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
9610: 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20  tions.** within 
9620: 74 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73  the same process
9630: 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  .  The argument 
9640: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
9650: 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 0a  an array of two.
9660: 2a 2a 20 69 6e 74 65 67 65 72 73 20 77 68 65 72  ** integers wher
9670: 65 20 74 68 65 20 66 69 72 73 74 20 69 6e 74 65  e the first inte
9680: 67 65 72 20 69 20 74 68 65 20 6e 65 77 20 72 65  ger i the new re
9690: 74 72 79 20 63 6f 75 6e 74 20 61 6e 64 20 74 68  try count and th
96a0: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65  e second.** inte
96b0: 67 65 72 20 69 73 20 74 68 65 20 64 65 6c 61 79  ger is the delay
96c0: 2e 20 20 49 66 20 65 69 74 68 65 72 20 69 6e 74  .  If either int
96d0: 65 67 65 72 20 69 73 20 6e 65 67 61 74 69 76 65  eger is negative
96e0: 2c 20 74 68 65 6e 20 74 68 65 20 73 65 74 74 69  , then the setti
96f0: 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61  ng.** is not cha
9700: 6e 67 65 64 20 62 75 74 20 69 6e 73 74 65 61 64  nged but instead
9710: 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65   the prior value
9720: 20 6f 66 20 74 68 61 74 20 73 65 74 74 69 6e 67   of that setting
9730: 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69   is written.** i
9740: 6e 74 6f 20 74 68 65 20 61 72 72 61 79 20 65 6e  nto the array en
9750: 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68  try, allowing th
9760: 65 20 63 75 72 72 65 6e 74 20 72 65 74 72 79 20  e current retry 
9770: 73 65 74 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a  settings to be.*
9780: 2a 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20  * interrogated. 
9790: 20 54 68 65 20 7a 44 62 4e 61 6d 65 20 70 61 72   The zDbName par
97a0: 61 6d 65 74 65 72 20 69 73 20 69 67 6e 6f 72 65  ameter is ignore
97b0: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  d..**.** <li>[[S
97c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
97d0: 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68  IST_WAL]].** ^Th
97e0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
97f0: 50 45 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63  PERSIST_WAL] opc
9800: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73  ode is used to s
9810: 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a  et or query the.
9820: 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 5b 57  ** persistent [W
9830: 41 4c 20 7c 20 57 72 69 74 65 20 41 68 65 61 64  AL | Write Ahead
9840: 20 4c 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20 20   Log] setting.  
9850: 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20  By default, the 
9860: 61 75 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69  auxiliary.** wri
9870: 74 65 20 61 68 65 61 64 20 6c 6f 67 20 61 6e 64  te ahead log and
9880: 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66   shared memory f
9890: 69 6c 65 73 20 75 73 65 64 20 66 6f 72 20 74 72  iles used for tr
98a0: 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f  ansaction contro
98b0: 6c 0a 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61 74  l.** are automat
98c0: 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 77  ically deleted w
98d0: 68 65 6e 20 74 68 65 20 6c 61 74 65 73 74 20 63  hen the latest c
98e0: 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68 65  onnection to the
98f0: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f   database.** clo
9900: 73 65 73 2e 20 20 53 65 74 74 69 6e 67 20 70 65  ses.  Setting pe
9910: 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64  rsistent WAL mod
9920: 65 20 63 61 75 73 65 73 20 74 68 6f 73 65 20 66  e causes those f
9930: 69 6c 65 73 20 74 6f 20 70 65 72 73 69 73 74 20  iles to persist 
9940: 61 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20  after.** close. 
9950: 20 50 65 72 73 69 73 74 69 6e 67 20 74 68 65 20   Persisting the 
9960: 66 69 6c 65 73 20 69 73 20 75 73 65 66 75 6c 20  files is useful 
9970: 77 68 65 6e 20 6f 74 68 65 72 20 70 72 6f 63 65  when other proce
9980: 73 73 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74  sses that do not
9990: 0a 2a 2a 20 68 61 76 65 20 77 72 69 74 65 20 70  .** have write p
99a0: 65 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65  ermission on the
99b0: 20 64 69 72 65 63 74 6f 72 79 20 63 6f 6e 74 61   directory conta
99c0: 69 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61  ining the databa
99d0: 73 65 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20  se file want.** 
99e0: 74 6f 20 72 65 61 64 20 74 68 65 20 64 61 74 61  to read the data
99f0: 62 61 73 65 20 66 69 6c 65 2c 20 61 73 20 74 68  base file, as th
9a00: 65 20 57 41 4c 20 61 6e 64 20 73 68 61 72 65 64  e WAL and shared
9a10: 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75   memory files mu
9a20: 73 74 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f  st exist.** in o
9a30: 72 64 65 72 20 66 6f 72 20 74 68 65 20 64 61 74  rder for the dat
9a40: 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 61 64  abase to be read
9a50: 61 62 6c 65 2e 20 20 54 68 65 20 66 6f 75 72 74  able.  The fourt
9a60: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  h parameter to.*
9a70: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  * [sqlite3_file_
9a80: 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74  control()] for t
9a90: 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c  his opcode shoul
9aa0: 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74  d be a pointer t
9ab0: 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a  o an integer..**
9ac0: 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 69 73   That integer is
9ad0: 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 70 65   0 to disable pe
9ae0: 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64  rsistent WAL mod
9af0: 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65  e or 1 to enable
9b00: 20 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57   persistent.** W
9b10: 41 4c 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65  AL mode.  If the
9b20: 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20   integer is -1, 
9b30: 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77  then it is overw
9b40: 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20  ritten with the 
9b50: 63 75 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70  current.** WAL p
9b60: 65 72 73 69 73 74 65 6e 63 65 20 73 65 74 74 69  ersistence setti
9b70: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ng..**.** <li>[[
9b80: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57  SQLITE_FCNTL_POW
9b90: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
9ba0: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
9bb0: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
9bc0: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70  FE_OVERWRITE] op
9bd0: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
9be0: 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65  set or query the
9bf0: 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 22  .** persistent "
9c00: 70 6f 77 65 72 73 61 66 65 2d 6f 76 65 72 77 72  powersafe-overwr
9c10: 69 74 65 22 20 6f 72 20 22 50 53 4f 57 22 20 73  ite" or "PSOW" s
9c20: 65 74 74 69 6e 67 2e 20 20 54 68 65 20 50 53 4f  etting.  The PSO
9c30: 57 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74  W setting.** det
9c40: 65 72 6d 69 6e 65 73 20 74 68 65 20 5b 53 51 4c  ermines the [SQL
9c50: 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53  ITE_IOCAP_POWERS
9c60: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 62  AFE_OVERWRITE] b
9c70: 69 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65  it of the.** xDe
9c80: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
9c90: 69 63 73 20 6d 65 74 68 6f 64 73 2e 20 54 68 65  ics methods. The
9ca0: 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
9cb0: 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  r to.** [sqlite3
9cc0: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
9cd0: 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65   for this opcode
9ce0: 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69   should be a poi
9cf0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
9d00: 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65  er..** That inte
9d10: 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61  ger is 0 to disa
9d20: 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20  ble zero-damage 
9d30: 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61  mode or 1 to ena
9d40: 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a  ble zero-damage.
9d50: 2a 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65  ** mode.  If the
9d60: 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20   integer is -1, 
9d70: 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77  then it is overw
9d80: 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20  ritten with the 
9d90: 63 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d  current.** zero-
9da0: 64 61 6d 61 67 65 20 6d 6f 64 65 20 73 65 74 74  damage mode sett
9db0: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ing..**.** <li>[
9dc0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56  [SQLITE_FCNTL_OV
9dd0: 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68  ERWRITE]].** ^Th
9de0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
9df0: 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64  OVERWRITE] opcod
9e00: 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20  e is invoked by 
9e10: 53 51 4c 69 74 65 20 61 66 74 65 72 20 6f 70 65  SQLite after ope
9e20: 6e 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65 20  ning.** a write 
9e30: 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69  transaction to i
9e40: 6e 64 69 63 61 74 65 20 74 68 61 74 2c 20 75 6e  ndicate that, un
9e50: 6c 65 73 73 20 69 74 20 69 73 20 72 6f 6c 6c 65  less it is rolle
9e60: 64 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a  d back for some.
9e70: 2a 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65 20 65  ** reason, the e
9e80: 6e 74 69 72 65 20 64 61 74 61 62 61 73 65 20 66  ntire database f
9e90: 69 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76 65 72  ile will be over
9ea0: 77 72 69 74 74 65 6e 20 62 79 20 74 68 65 20 63  written by the c
9eb0: 75 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73  urrent .** trans
9ec0: 61 63 74 69 6f 6e 2e 20 54 68 69 73 20 69 73 20  action. This is 
9ed0: 75 73 65 64 20 62 79 20 56 41 43 55 55 4d 20 6f  used by VACUUM o
9ee0: 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  perations..**.**
9ef0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9f00: 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a  NTL_VFSNAME]].**
9f10: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
9f20: 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63  NTL_VFSNAME] opc
9f30: 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ode can be used 
9f40: 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6e 61  to obtain the na
9f50: 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56  mes of.** all [V
9f60: 46 53 65 73 5d 20 69 6e 20 74 68 65 20 56 46 53  FSes] in the VFS
9f70: 20 73 74 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d   stack.  The nam
9f80: 65 73 20 61 72 65 20 6f 66 20 61 6c 6c 20 56 46  es are of all VF
9f90: 53 20 73 68 69 6d 73 20 61 6e 64 20 74 68 65 0a  S shims and the.
9fa0: 2a 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d  ** final bottom-
9fb0: 6c 65 76 65 6c 20 56 46 53 20 61 72 65 20 77 72  level VFS are wr
9fc0: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72  itten into memor
9fd0: 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
9fe0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
9ff0: 6c 6f 63 28 29 5d 20 61 6e 64 20 74 68 65 20 72  loc()] and the r
a000: 65 73 75 6c 74 20 69 73 20 73 74 6f 72 65 64 20  esult is stored 
a010: 69 6e 20 74 68 65 20 63 68 61 72 2a 20 76 61 72  in the char* var
a020: 69 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68  iable.** that th
a030: 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
a040: 65 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66  er of [sqlite3_f
a050: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70  ile_control()] p
a060: 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65  oints to..** The
a070: 20 63 61 6c 6c 65 72 20 69 73 20 72 65 73 70 6f   caller is respo
a080: 6e 73 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69  nsible for freei
a090: 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79 20 77 68  ng the memory wh
a0a0: 65 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77 69 74  en done.  As wit
a0b0: 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f  h.** all file-co
a0c0: 6e 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74  ntrol actions, t
a0d0: 68 65 72 65 20 69 73 20 6e 6f 20 67 75 61 72 61  here is no guara
a0e0: 6e 74 65 65 20 74 68 61 74 20 74 68 69 73 20 77  ntee that this w
a0f0: 69 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20  ill actually.** 
a100: 64 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20 43 61  do anything.  Ca
a110: 6c 6c 65 72 73 20 73 68 6f 75 6c 64 20 69 6e 69  llers should ini
a120: 74 69 61 6c 69 7a 65 20 74 68 65 20 63 68 61 72  tialize the char
a130: 2a 20 76 61 72 69 61 62 6c 65 20 74 6f 20 61 20  * variable to a 
a140: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  NULL.** pointer 
a150: 69 6e 20 63 61 73 65 20 74 68 69 73 20 66 69 6c  in case this fil
a160: 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74  e-control is not
a170: 20 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54   implemented.  T
a180: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  his file-control
a190: 0a 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65 64 20  .** is intended 
a1a0: 66 6f 72 20 64 69 61 67 6e 6f 73 74 69 63 20 75  for diagnostic u
a1b0: 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c  se only..**.** <
a1c0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
a1d0: 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57  L_PRAGMA]].** ^W
a1e0: 68 65 6e 65 76 65 72 20 61 20 5b 50 52 41 47 4d  henever a [PRAGM
a1f0: 41 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  A] statement is 
a200: 70 61 72 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49  parsed, an [SQLI
a210: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
a220: 20 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f   .** file contro
a230: 6c 20 69 73 20 73 65 6e 74 20 74 6f 20 74 68 65  l is sent to the
a240: 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66   open [sqlite3_f
a250: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72  ile] object corr
a260: 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20  esponding.** to 
a270: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
a280: 65 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 70  e to which the p
a290: 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20  ragma statement 
a2a0: 72 65 66 65 72 73 2e 20 5e 54 68 65 20 61 72 67  refers. ^The arg
a2b0: 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20  ument.** to the 
a2c0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
a2d0: 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72  AGMA] file contr
a2e0: 6f 6c 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  ol is an array o
a2f0: 66 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f  f.** pointers to
a300: 20 73 74 72 69 6e 67 73 20 28 63 68 61 72 2a 2a   strings (char**
a310: 29 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 73  ) in which the s
a320: 65 63 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66  econd element of
a330: 20 74 68 65 20 61 72 72 61 79 0a 2a 2a 20 69 73   the array.** is
a340: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
a350: 20 70 72 61 67 6d 61 20 61 6e 64 20 74 68 65 20   pragma and the 
a360: 74 68 69 72 64 20 65 6c 65 6d 65 6e 74 20 69 73  third element is
a370: 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f   the argument to
a380: 20 74 68 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f   the.** pragma o
a390: 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 70 72  r NULL if the pr
a3a0: 61 67 6d 61 20 68 61 73 20 6e 6f 20 61 72 67 75  agma has no argu
a3b0: 6d 65 6e 74 2e 20 20 5e 54 68 65 20 68 61 6e 64  ment.  ^The hand
a3c0: 6c 65 72 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53  ler for an.** [S
a3d0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
a3e0: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  MA] file control
a3f0: 20 63 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20   can optionally 
a400: 6d 61 6b 65 20 74 68 65 20 66 69 72 73 74 20 65  make the first e
a410: 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65  lement.** of the
a420: 20 63 68 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74   char** argument
a430: 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69   point to a stri
a440: 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ng obtained from
a450: 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74   [sqlite3_mprint
a460: 66 28 29 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65  f()].** or the e
a470: 71 75 69 76 61 6c 65 6e 74 20 61 6e 64 20 74 68  quivalent and th
a480: 61 74 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62  at string will b
a490: 65 63 6f 6d 65 20 74 68 65 20 72 65 73 75 6c 74  ecome the result
a4a0: 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 6f   of the pragma o
a4b0: 72 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d  r.** the error m
a4c0: 65 73 73 61 67 65 20 69 66 20 74 68 65 20 70 72  essage if the pr
a4d0: 61 67 6d 61 20 66 61 69 6c 73 2e 20 5e 49 66 20  agma fails. ^If 
a4e0: 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  the.** [SQLITE_F
a4f0: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c  CNTL_PRAGMA] fil
a500: 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e  e control return
a510: 73 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  s [SQLITE_NOTFOU
a520: 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c  ND], then normal
a530: 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72   .** [PRAGMA] pr
a540: 6f 63 65 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75  ocessing continu
a550: 65 73 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51  es.  ^If the [SQ
a560: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
a570: 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72  A].** file contr
a580: 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ol returns [SQLI
a590: 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65  TE_OK], then the
a5a0: 20 70 61 72 73 65 72 20 61 73 73 75 6d 65 73 20   parser assumes 
a5b0: 74 68 61 74 20 74 68 65 0a 2a 2a 20 56 46 53 20  that the.** VFS 
a5c0: 68 61 73 20 68 61 6e 64 6c 65 64 20 74 68 65 20  has handled the 
a5d0: 50 52 41 47 4d 41 20 69 74 73 65 6c 66 20 61 6e  PRAGMA itself an
a5e0: 64 20 74 68 65 20 70 61 72 73 65 72 20 67 65 6e  d the parser gen
a5f0: 65 72 61 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a  erates a no-op.*
a600: 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  * prepared state
a610: 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 5b  ment.  ^If the [
a620: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
a630: 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  GMA] file contro
a640: 6c 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79  l returns.** any
a650: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6f 74 68   result code oth
a660: 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
a670: 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e  OK] or [SQLITE_N
a680: 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20 6d  OTFOUND], that m
a690: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68 65  eans.** that the
a6a0: 20 56 46 53 20 65 6e 63 6f 75 6e 74 65 72 65 64   VFS encountered
a6b0: 20 61 6e 20 65 72 72 6f 72 20 77 68 69 6c 65 20   an error while 
a6c0: 68 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50 52  handling the [PR
a6d0: 41 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a 2a  AGMA] and the.**
a6e0: 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 20   compilation of 
a6f0: 74 68 65 20 50 52 41 47 4d 41 20 66 61 69 6c 73  the PRAGMA fails
a700: 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20   with an error. 
a710: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
a720: 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66  NTL_PRAGMA].** f
a730: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 75  ile control occu
a740: 72 73 20 61 74 20 74 68 65 20 62 65 67 69 6e 6e  rs at the beginn
a750: 69 6e 67 20 6f 66 20 70 72 61 67 6d 61 20 73 74  ing of pragma st
a760: 61 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69 73  atement analysis
a770: 20 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69 73   and so.** it is
a780: 20 61 62 6c 65 20 74 6f 20 6f 76 65 72 72 69 64   able to overrid
a790: 65 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41 47  e built-in [PRAG
a7a0: 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  MA] statements..
a7b0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
a7c0: 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e  TE_FCNTL_BUSYHAN
a7d0: 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  DLER]].** ^The [
a7e0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53  SQLITE_FCNTL_BUS
a7f0: 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c  YHANDLER].** fil
a800: 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62 65  e-control may be
a810: 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69   invoked by SQLi
a820: 74 65 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61  te on the databa
a830: 73 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a 2a  se file handle.*
a840: 2a 20 73 68 6f 72 74 6c 79 20 61 66 74 65 72 20  * shortly after 
a850: 69 74 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20  it is opened in 
a860: 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65  order to provide
a870: 20 61 20 63 75 73 74 6f 6d 20 56 46 53 20 77 69   a custom VFS wi
a880: 74 68 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20  th access.** to 
a890: 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  the connections 
a8a0: 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c  busy-handler cal
a8b0: 6c 62 61 63 6b 2e 20 54 68 65 20 61 72 67 75 6d  lback. The argum
a8c0: 65 6e 74 20 69 73 20 6f 66 20 74 79 70 65 20 28  ent is of type (
a8d0: 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e  void **).** - an
a8e0: 20 61 72 72 61 79 20 6f 66 20 74 77 6f 20 28 76   array of two (v
a8f0: 6f 69 64 20 2a 29 20 76 61 6c 75 65 73 2e 20 54  oid *) values. T
a900: 68 65 20 66 69 72 73 74 20 28 76 6f 69 64 20 2a  he first (void *
a910: 29 20 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e 74  ) actually point
a920: 73 0a 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74 69  s.** to a functi
a930: 6f 6e 20 6f 66 20 74 79 70 65 20 28 69 6e 74 20  on of type (int 
a940: 28 2a 29 28 76 6f 69 64 20 2a 29 29 2e 20 49 6e  (*)(void *)). In
a950: 20 6f 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b 65   order to invoke
a960: 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73   the connections
a970: 0a 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65 72  .** busy-handler
a980: 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  , this function 
a990: 73 68 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b 65  should be invoke
a9a0: 64 20 77 69 74 68 20 74 68 65 20 73 65 63 6f 6e  d with the secon
a9b0: 64 20 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a  d (void *) in.**
a9c0: 20 74 68 65 20 61 72 72 61 79 20 61 73 20 74 68   the array as th
a9d0: 65 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e  e only argument.
a9e0: 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 6e   If it returns n
a9f0: 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68  on-zero, then th
aa00: 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 73  e operation.** s
aa10: 68 6f 75 6c 64 20 62 65 20 72 65 74 72 69 65 64  hould be retried
aa20: 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20  . If it returns 
aa30: 7a 65 72 6f 2c 20 74 68 65 20 63 75 73 74 6f 6d  zero, the custom
aa40: 20 56 46 53 20 73 68 6f 75 6c 64 20 61 62 61 6e   VFS should aban
aa50: 64 6f 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65  don the.** curre
aa60: 6e 74 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a  nt operation..**
aa70: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
aa80: 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e  _FCNTL_TEMPFILEN
aa90: 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63  AME]].** ^Applic
aaa0: 61 74 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b 65  ation can invoke
aab0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   the [SQLITE_FCN
aac0: 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d  TL_TEMPFILENAME]
aad0: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a   file-control.**
aae0: 20 74 6f 20 68 61 76 65 20 53 51 4c 69 74 65 20   to have SQLite 
aaf0: 67 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74 65  generate a.** te
ab00: 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65  mporary filename
ab10: 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20   using the same 
ab20: 61 6c 67 6f 72 69 74 68 6d 20 74 68 61 74 20 69  algorithm that i
ab30: 73 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67 65  s followed to ge
ab40: 6e 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72  nerate.** tempor
ab50: 61 72 79 20 66 69 6c 65 6e 61 6d 65 73 20 66 6f  ary filenames fo
ab60: 72 20 54 45 4d 50 20 74 61 62 6c 65 73 20 61 6e  r TEMP tables an
ab70: 64 20 6f 74 68 65 72 20 69 6e 74 65 72 6e 61 6c  d other internal
ab80: 20 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20 61   uses.  The.** a
ab90: 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62  rgument should b
aba0: 65 20 61 20 63 68 61 72 2a 2a 20 77 68 69 63 68  e a char** which
abb0: 20 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64 20   will be filled 
abc0: 77 69 74 68 20 74 68 65 20 66 69 6c 65 6e 61 6d  with the filenam
abd0: 65 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e 74  e.** written int
abe0: 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
abf0: 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
ac00: 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20  malloc()].  The 
ac10: 63 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a 2a  caller should.**
ac20: 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33   invoke [sqlite3
ac30: 5f 66 72 65 65 28 29 5d 20 6f 6e 20 74 68 65 20  _free()] on the 
ac40: 72 65 73 75 6c 74 20 74 6f 20 61 76 6f 69 64 20  result to avoid 
ac50: 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a  a memory leak..*
ac60: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
ac70: 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a  E_FCNTL_MMAP_SIZ
ac80: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
ac90: 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49  TE_FCNTL_MMAP_SI
aca0: 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  ZE] file control
acb0: 20 69 73 20 75 73 65 64 20 74 6f 20 71 75 65 72   is used to quer
acc0: 79 20 6f 72 20 73 65 74 20 74 68 65 0a 2a 2a 20  y or set the.** 
acd0: 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
ace0: 66 20 62 79 74 65 73 20 74 68 61 74 20 77 69 6c  f bytes that wil
acf0: 6c 20 62 65 20 75 73 65 64 20 66 6f 72 20 6d 65  l be used for me
ad00: 6d 6f 72 79 2d 6d 61 70 70 65 64 20 49 2f 4f 2e  mory-mapped I/O.
ad10: 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74  .** The argument
ad20: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
ad30: 20 61 20 76 61 6c 75 65 20 6f 66 20 74 79 70 65   a value of type
ad40: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 74   sqlite3_int64 t
ad50: 68 61 74 0a 2a 2a 20 69 73 20 61 6e 20 61 64 76  hat.** is an adv
ad60: 69 73 6f 72 79 20 6d 61 78 69 6d 75 6d 20 6e 75  isory maximum nu
ad70: 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
ad80: 20 74 68 65 20 66 69 6c 65 20 74 6f 20 6d 65 6d   the file to mem
ad90: 6f 72 79 20 6d 61 70 2e 20 20 54 68 65 0a 2a 2a  ory map.  The.**
ada0: 20 70 6f 69 6e 74 65 72 20 69 73 20 6f 76 65 72   pointer is over
adb0: 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65  written with the
adc0: 20 6f 6c 64 20 76 61 6c 75 65 2e 20 20 54 68 65   old value.  The
add0: 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 68   limit is not ch
ade0: 61 6e 67 65 64 20 69 66 0a 2a 2a 20 74 68 65 20  anged if.** the 
adf0: 76 61 6c 75 65 20 6f 72 69 67 69 6e 61 6c 6c 79  value originally
ae00: 20 70 6f 69 6e 74 65 64 20 74 6f 20 69 73 20 6e   pointed to is n
ae10: 65 67 61 74 69 76 65 2c 20 61 6e 64 20 73 6f 20  egative, and so 
ae20: 74 68 65 20 63 75 72 72 65 6e 74 20 6c 69 6d 69  the current limi
ae30: 74 20 0a 2a 2a 20 63 61 6e 20 62 65 20 71 75 65  t .** can be que
ae40: 72 69 65 64 20 62 79 20 70 61 73 73 69 6e 67 20  ried by passing 
ae50: 69 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  in a pointer to 
ae60: 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65  a negative numbe
ae70: 72 2e 20 20 54 68 69 73 0a 2a 2a 20 66 69 6c 65  r.  This.** file
ae80: 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64  -control is used
ae90: 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 69   internally to i
aea0: 6d 70 6c 65 6d 65 6e 74 20 5b 50 52 41 47 4d 41  mplement [PRAGMA
aeb0: 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a   mmap_size]..**.
aec0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
aed0: 46 43 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a  FCNTL_TRACE]].**
aee0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
aef0: 54 4c 5f 54 52 41 43 45 5d 20 66 69 6c 65 20 63  TL_TRACE] file c
af00: 6f 6e 74 72 6f 6c 20 70 72 6f 76 69 64 65 73 20  ontrol provides 
af10: 61 64 76 69 73 6f 72 79 20 69 6e 66 6f 72 6d 61  advisory informa
af20: 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65 20 56  tion.** to the V
af30: 46 53 20 61 62 6f 75 74 20 77 68 61 74 20 74 68  FS about what th
af40: 65 20 68 69 67 68 65 72 20 6c 61 79 65 72 73 20  e higher layers 
af50: 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 73 74  of the SQLite st
af60: 61 63 6b 20 61 72 65 20 64 6f 69 6e 67 2e 0a 2a  ack are doing..*
af70: 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74  * This file cont
af80: 72 6f 6c 20 69 73 20 75 73 65 64 20 62 79 20 73  rol is used by s
af90: 6f 6d 65 20 56 46 53 20 61 63 74 69 76 69 74 79  ome VFS activity
afa0: 20 74 72 61 63 69 6e 67 20 5b 73 68 69 6d 73 5d   tracing [shims]
afb0: 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e  ..** The argumen
afc0: 74 20 69 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d  t is a zero-term
afd0: 69 6e 61 74 65 64 20 73 74 72 69 6e 67 2e 20 20  inated string.  
afe0: 48 69 67 68 65 72 20 6c 61 79 65 72 73 20 69 6e  Higher layers in
aff0: 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 73   the.** SQLite s
b000: 74 61 63 6b 20 6d 61 79 20 67 65 6e 65 72 61 74  tack may generat
b010: 65 20 69 6e 73 74 61 6e 63 65 73 20 6f 66 20 74  e instances of t
b020: 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  his file control
b030: 20 69 66 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49   if.** the [SQLI
b040: 54 45 5f 55 53 45 5f 46 43 4e 54 4c 5f 54 52 41  TE_USE_FCNTL_TRA
b050: 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  CE] compile-time
b060: 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c   option is enabl
b070: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 2f 75 6c 3e 0a  ed..**.** </ul>.
b080: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
b090: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
b0a0: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
b0b0: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
b0c0: 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _GET_LOCKPROXYFI
b0d0: 4c 45 20 20 20 20 20 20 20 20 20 20 20 20 20 32  LE             2
b0e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b0f0: 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  SET_LOCKPROXYFIL
b100: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a  E             3.
b110: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
b120: 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20  AST_ERRNO       
b130: 20 20 20 20 20 20 20 20 20 20 20 20 20 34 0a 23               4.#
b140: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
b150: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20  NTL_SIZE_HINT   
b160: 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64              5.#d
b170: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
b180: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20  TL_CHUNK_SIZE   
b190: 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65             6.#de
b1a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
b1b0: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20  L_FILE_POINTER  
b1c0: 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66            7.#def
b1d0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
b1e0: 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20  _SYNC_OMITTED   
b1f0: 20 20 20 20 20 20 20 20 20 38 0a 23 64 65 66 69           8.#defi
b200: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
b210: 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 20 20  WIN32_AV_RETRY  
b220: 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e          9.#defin
b230: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  e SQLITE_FCNTL_P
b240: 45 52 53 49 53 54 5f 57 41 4c 20 20 20 20 20 20  ERSIST_WAL      
b250: 20 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65        10.#define
b260: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56   SQLITE_FCNTL_OV
b270: 45 52 57 52 49 54 45 20 20 20 20 20 20 20 20 20  ERWRITE         
b280: 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20       11.#define 
b290: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
b2a0: 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 20  NAME            
b2b0: 20 20 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53      12.#define S
b2c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45  QLITE_FCNTL_POWE
b2d0: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20  RSAFE_OVERWRITE 
b2e0: 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20 53 51     13.#define SQ
b2f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
b300: 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  A               
b310: 20 20 31 34 0a 23 64 65 66 69 6e 65 20 53 51 4c    14.#define SQL
b320: 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41  ITE_FCNTL_BUSYHA
b330: 4e 44 4c 45 52 20 20 20 20 20 20 20 20 20 20 20  NDLER           
b340: 20 31 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   15.#define SQLI
b350: 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c  TE_FCNTL_TEMPFIL
b360: 45 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20  ENAME           
b370: 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  16.#define SQLIT
b380: 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a  E_FCNTL_MMAP_SIZ
b390: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31  E              1
b3a0: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
b3b0: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 20 20 20 20  _FCNTL_TRACE    
b3c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39                19
b3d0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
b3e0: 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a  : Mutex Handle.*
b3f0: 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d  *.** The mutex m
b400: 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c  odule within SQL
b410: 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c  ite defines [sql
b420: 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62  ite3_mutex] to b
b430: 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74  e an.** abstract
b440: 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65   type for a mute
b450: 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53  x object.  The S
b460: 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72  QLite core never
b470: 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65   looks.** at the
b480: 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73   internal repres
b490: 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b  entation of an [
b4a0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20  sqlite3_mutex]. 
b4b0: 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c   It only.** deal
b4c0: 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20  s with pointers 
b4d0: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
b4e0: 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a  mutex] object..*
b4f0: 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65  *.** Mutexes are
b500: 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b   created using [
b510: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
b520: 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  loc()]..*/.typed
b530: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
b540: 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f  3_mutex sqlite3_
b550: 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  mutex;../*.** CA
b560: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
b570: 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  face Object.**.*
b580: 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
b590: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
b5a0: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
b5b0: 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65  the interface be
b5c0: 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c  tween.** the SQL
b5d0: 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65  ite core and the
b5e0: 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72   underlying oper
b5f0: 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54  ating system.  T
b600: 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74  he "vfs".** in t
b610: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f  he name of the o
b620: 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72  bject stands for
b630: 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73   "virtual file s
b640: 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20  ystem".  See.** 
b650: 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64  the [VFS | VFS d
b660: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f  ocumentation] fo
b670: 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d  r further inform
b680: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ation..**.** The
b690: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56   value of the iV
b6a0: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20  ersion field is 
b6b0: 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20  initially 1 but 
b6c0: 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e  may be larger in
b6d0: 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69  .** future versi
b6e0: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20  ons of SQLite.  
b6f0: 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  Additional field
b700: 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65  s may be appende
b710: 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a  d to this.** obj
b720: 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65  ect when the iVe
b730: 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69  rsion value is i
b740: 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20  ncreased.  Note 
b750: 74 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75  that the structu
b760: 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c  re.** of the sql
b770: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
b780: 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74  changes in the t
b790: 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65  ransaction betwe
b7a0: 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72  en.** SQLite ver
b7b0: 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33  sion 3.5.9 and 3
b7c0: 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65  .6.0 and yet the
b7d0: 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20   iVersion field 
b7e0: 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66  was not.** modif
b7f0: 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ied..**.** The s
b800: 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73  zOsFile field is
b810: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
b820: 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c   subclassed [sql
b830: 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74  ite3_file].** st
b840: 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20  ructure used by 
b850: 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74  this VFS.  mxPat
b860: 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78  hname is the max
b870: 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a  imum length of.*
b880: 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20  * a pathname in 
b890: 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20  this VFS..**.** 
b8a0: 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74  Registered sqlit
b8b0: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61  e3_vfs objects a
b8c0: 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e  re kept on a lin
b8d0: 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20  ked list formed 
b8e0: 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20  by.** the pNext 
b8f0: 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73  pointer.  The [s
b900: 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73  qlite3_vfs_regis
b910: 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ter()].** and [s
b920: 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67  qlite3_vfs_unreg
b930: 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61  ister()] interfa
b940: 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20  ces manage this 
b950: 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72  list.** in a thr
b960: 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54  ead-safe way.  T
b970: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  he [sqlite3_vfs_
b980: 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63  find()] interfac
b990: 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68  e.** searches th
b9a0: 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72  e list.  Neither
b9b0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
b9c0: 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46   code nor the VF
b9d0: 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  S.** implementat
b9e0: 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74  ion should use t
b9f0: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
ba00: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78  ..**.** The pNex
ba10: 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f  t field is the o
ba20: 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65  nly field in the
ba30: 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20   sqlite3_vfs.** 
ba40: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53  structure that S
ba50: 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20  QLite will ever 
ba60: 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20  modify.  SQLite 
ba70: 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73  will only access
ba80: 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68  .** or modify th
ba90: 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68  is field while h
baa0: 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75  olding a particu
bab0: 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78  lar static mutex
bac0: 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
bad0: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65  tion should neve
bae0: 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e  r modify anythin
baf0: 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c  g within the sql
bb00: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65  ite3_vfs.** obje
bb10: 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65  ct once the obje
bb20: 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69  ct has been regi
bb30: 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  stered..**.** Th
bb40: 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f  e zName field ho
bb50: 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  lds the name of 
bb60: 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20  the VFS module. 
bb70: 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a   The name must.*
bb80: 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f  * be unique acro
bb90: 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c  ss all VFS modul
bba0: 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69  es..**.** [[sqli
bbb0: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a  te3_vfs.xOpen]].
bbc0: 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61  ** ^SQLite guara
bbd0: 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 7a  ntees that the z
bbe0: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
bbf0: 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69  er to xOpen.** i
bc00: 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20  s either a NULL 
bc10: 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e  pointer or strin
bc20: 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  g obtained.** fr
bc30: 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65  om xFullPathname
bc40: 28 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f  () with an optio
bc50: 6e 61 6c 20 73 75 66 66 69 78 20 61 64 64 65 64  nal suffix added
bc60: 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69  ..** ^If a suffi
bc70: 78 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68  x is added to th
bc80: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
bc90: 6d 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a  meter, it will.*
bca0: 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73  * consist of a s
bcb0: 69 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63  ingle "-" charac
bcc0: 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  ter followed by 
bcd0: 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20  no more than.** 
bce0: 31 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20  11 alphanumeric 
bcf0: 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61  and/or "-" chara
bd00: 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74  cters..** ^SQLit
bd10: 65 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e  e further guaran
bd20: 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  tees that.** the
bd30: 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20   string will be 
bd40: 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e  valid and unchan
bd50: 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65  ged until xClose
bd60: 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e  () is.** called.
bd70: 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20   Because of the 
bd80: 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63  previous sentenc
bd90: 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  e,.** the [sqlit
bda0: 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66  e3_file] can saf
bdb0: 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e  ely store a poin
bdc0: 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69  ter to the.** fi
bdd0: 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65  lename if it nee
bde0: 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74  ds to remember t
bdf0: 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20  he filename for 
be00: 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20  some reason..** 
be10: 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  If the zFilename
be20: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f   parameter to xO
be30: 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  pen is a NULL po
be40: 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e  inter then xOpen
be50: 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20  .** must invent 
be60: 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72  its own temporar
be70: 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66  y name for the f
be80: 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20  ile.  ^Whenever 
be90: 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d  the .** xFilenam
bea0: 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e  e parameter is N
beb0: 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f  ULL it will also
bec0: 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61   be the case tha
bed0: 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70  t the.** flags p
bee0: 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e  arameter will in
bef0: 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50  clude [SQLITE_OP
bf00: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
bf10: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61  ]..**.** The fla
bf20: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
bf30: 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20  Open() includes 
bf40: 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a  all bits set in.
bf50: 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67  ** the flags arg
bf60: 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
bf70: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f  3_open_v2()].  O
bf80: 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r if [sqlite3_op
bf90: 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c  en()].** or [sql
bfa0: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69  ite3_open16()] i
bfb0: 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61  s used, then fla
bfc0: 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c  gs includes at l
bfd0: 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  east.** [SQLITE_
bfe0: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20  OPEN_READWRITE] 
bff0: 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  | [SQLITE_OPEN_C
c000: 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78  REATE]. .** If x
c010: 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66  Open() opens a f
c020: 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68  ile read-only th
c030: 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74  en it sets *pOut
c040: 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c  Flags to.** incl
c050: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ude [SQLITE_OPEN
c060: 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68  _READONLY].  Oth
c070: 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74  er bits in *pOut
c080: 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74  Flags may be set
c090: 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65  ..**.** ^(SQLite
c0a0: 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f   will also add o
c0b0: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
c0c0: 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65  ing flags to the
c0d0: 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c   xOpen().** call
c0e0: 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  , depending on t
c0f0: 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20  he object being 
c100: 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  opened:.**.** <u
c110: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  l>.** <li>  [SQL
c120: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
c130: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
c140: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
c150: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
c160: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
c170: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
c180: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
c190: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
c1a0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
c1b0: 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20  RANSIENT_DB].** 
c1c0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
c1d0: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a  EN_SUBJOURNAL].*
c1e0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
c1f0: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
c200: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
c210: 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a  QLITE_OPEN_WAL].
c220: 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  ** </ul>)^.**.**
c230: 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d   The file I/O im
c240: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e  plementation can
c250: 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20   use the object 
c260: 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a  type flags to.**
c270: 20 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20   change the way 
c280: 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69  it deals with fi
c290: 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  les.  For exampl
c2a0: 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  e, an applicatio
c2b0: 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e  n.** that does n
c2c0: 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72  ot care about cr
c2d0: 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20  ash recovery or 
c2e0: 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d  rollback might m
c2f0: 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20  ake.** the open 
c300: 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c  of a journal fil
c310: 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74  e a no-op.  Writ
c320: 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e  es to this journ
c330: 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f  al would.** also
c340: 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20   be no-ops, and 
c350: 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72  any attempt to r
c360: 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20  ead the journal 
c370: 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20  would return.** 
c380: 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f  SQLITE_IOERR.  O
c390: 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  r the implementa
c3a0: 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67  tion might recog
c3b0: 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61  nize that a data
c3c0: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c  base.** file wil
c3d0: 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d  l be doing page-
c3e0: 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72  aligned sector r
c3f0: 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20  eads and writes 
c400: 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f  in a random.** o
c410: 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20  rder and set up 
c420: 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65  its I/O subsyste
c430: 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a  m accordingly..*
c440: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68  *.** SQLite migh
c450: 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f  t also add one o
c460: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
c470: 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70  flags to the xOp
c480: 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a  en method:.**.**
c490: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
c4a0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
c4b0: 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69  EONCLOSE].** <li
c4c0: 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  > [SQLITE_OPEN_E
c4d0: 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75  XCLUSIVE].** </u
c4e0: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51  l>.**.** The [SQ
c4f0: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
c500: 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65  ONCLOSE] flag me
c510: 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f  ans the file sho
c520: 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65  uld be.** delete
c530: 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f  d when it is clo
c540: 73 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49  sed.  ^The [SQLI
c550: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
c560: 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62  CLOSE].** will b
c570: 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64  e set for TEMP d
c580: 61 74 61 62 61 73 65 73 20 61 6e 64 20 74 68 65  atabases and the
c590: 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61  ir journals, tra
c5a0: 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61  nsient.** databa
c5b0: 73 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72  ses, and subjour
c5c0: 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nals..**.** ^The
c5d0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58   [SQLITE_OPEN_EX
c5e0: 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73  CLUSIVE] flag is
c5f0: 20 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20   always used in 
c600: 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77  conjunction.** w
c610: 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
c620: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61  OPEN_CREATE] fla
c630: 67 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f 74  g, which are bot
c640: 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e  h directly.** an
c650: 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f  alogous to the O
c660: 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41  _EXCL and O_CREA
c670: 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50  T flags of the P
c680: 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41  OSIX open().** A
c690: 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  PI.  The SQLITE_
c6a0: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66  OPEN_EXCLUSIVE f
c6b0: 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64  lag, when paired
c6c0: 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51   with the .** SQ
c6d0: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
c6e0: 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64  , is used to ind
c6f0: 69 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 20  icate that file 
c700: 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a  should always.**
c710: 20 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64   be created, and
c720: 20 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 65   that it is an e
c730: 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61  rror if it alrea
c740: 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74  dy exists..** It
c750: 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75   is <i>not</i> u
c760: 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20  sed to indicate 
c770: 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20  the file should 
c780: 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f  be opened .** fo
c790: 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65  r exclusive acce
c7a0: 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65  ss..**.** ^At le
c7b0: 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74  ast szOsFile byt
c7c0: 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65  es of memory are
c7d0: 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51   allocated by SQ
c7e0: 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20  Lite.** to hold 
c7f0: 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69  the  [sqlite3_fi
c800: 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61  le] structure pa
c810: 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  ssed as the thir
c820: 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f  d.** argument to
c830: 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70   xOpen.  The xOp
c840: 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e  en method does n
c850: 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c  ot have to.** al
c860: 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63  locate the struc
c870: 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20  ture; it should 
c880: 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e  just fill it in.
c890: 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74    Note that.** t
c8a0: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  he xOpen method 
c8b0: 6d 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c  must set the sql
c8c0: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
c8d0: 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20  ds to either.** 
c8e0: 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33  a valid [sqlite3
c8f0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
c900: 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20  ect or to NULL. 
c910: 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a   xOpen must do.*
c920: 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74  * this even if t
c930: 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20  he open fails.  
c940: 53 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74  SQLite expects t
c950: 68 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hat the sqlite3_
c960: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a  file.pMethods.**
c970: 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65   element will be
c980: 20 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70   valid after xOp
c990: 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72  en returns regar
c9a0: 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63  dless of the suc
c9b0: 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75  cess.** or failu
c9c0: 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20  re of the xOpen 
c9d0: 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71  call..**.** [[sq
c9e0: 6c 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73  lite3_vfs.xAcces
c9f0: 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67  s]].** ^The flag
ca00: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41  s argument to xA
ca10: 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b  ccess() may be [
ca20: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
ca30: 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74  ISTS].** to test
ca40: 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e   for the existen
ca50: 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72  ce of a file, or
ca60: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
ca70: 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a  READWRITE] to.**
ca80: 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20   test whether a 
ca90: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65  file is readable
caa0: 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f   and writable, o
cab0: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  r [SQLITE_ACCESS
cac0: 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73  _READ].** to tes
cad0: 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65  t whether a file
cae0: 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61   is at least rea
caf0: 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c  dable.   The fil
cb00: 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69  e can be a.** di
cb10: 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e  rectory..**.** ^
cb20: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61  SQLite will alwa
cb30: 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c  ys allocate at l
cb40: 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b  east mxPathname+
cb50: 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a  1 bytes for the.
cb60: 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  ** output buffer
cb70: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20   xFullPathname. 
cb80: 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20   The exact size 
cb90: 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  of the output bu
cba0: 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20  ffer.** is also 
cbb0: 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61  passed as a para
cbc0: 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d  meter to both  m
cbd0: 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f  ethods. If the o
cbe0: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
cbf0: 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f  is not large eno
cc00: 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e  ugh, [SQLITE_CAN
cc10: 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65  TOPEN] should be
cc20: 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65   returned. Since
cc30: 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64   this is.** hand
cc40: 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65  led as a fatal e
cc50: 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20  rror by SQLite, 
cc60: 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  vfs implementati
cc70: 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61  ons should endea
cc80: 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e  vor.** to preven
cc90: 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e  t this by settin
cca0: 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20  g mxPathname to 
ccb0: 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c  a sufficiently l
ccc0: 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  arge value..**.*
ccd0: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
cce0: 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78  s(), xSleep(), x
ccf0: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61  CurrentTime(), a
cd00: 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  nd xCurrentTimeI
cd10: 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66  nt64().** interf
cd20: 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72  aces are not str
cd30: 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20  ictly a part of 
cd40: 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20  the filesystem, 
cd50: 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20  but they are.** 
cd60: 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20  included in the 
cd70: 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f  VFS structure fo
cd80: 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a  r completeness..
cd90: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65  ** The xRandomne
cda0: 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74  ss() function at
cdb0: 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e  tempts to return
cdc0: 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a   nBytes bytes.**
cdd0: 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79   of good-quality
cde0: 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f   randomness into
cdf0: 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75   zOut.  The retu
ce00: 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74  rn value is.** t
ce10: 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72  he actual number
ce20: 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e   of bytes of ran
ce30: 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64  domness obtained
ce40: 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28  ..** The xSleep(
ce50: 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20  ) method causes 
ce60: 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65  the calling thre
ce70: 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20  ad to sleep for 
ce80: 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20  at.** least the 
ce90: 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73  number of micros
cea0: 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e  econds given.  ^
ceb0: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  The xCurrentTime
cec0: 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74  ().** method ret
ced0: 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61  urns a Julian Da
cee0: 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65  y Number for the
cef0: 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e   current date an
cf00: 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66  d time as.** a f
cf10: 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
cf20: 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75  lue..** ^The xCu
cf30: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
cf40: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c   method returns,
cf50: 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20   as an integer, 
cf60: 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61  the Julian.** Da
cf70: 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c  y Number multipl
cf80: 69 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20  ied by 86400000 
cf90: 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d  (the number of m
cfa0: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a  illiseconds in .
cfb0: 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79  ** a 24-hour day
cfc0: 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ).  .** ^SQLite 
cfd0: 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75  will use the xCu
cfe0: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
cff0: 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74   method to get t
d000: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61  he current.** da
d010: 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74  te and time if t
d020: 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76  hat method is av
d030: 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72  ailable (if iVer
d040: 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a  sion is 2 or .**
d050: 20 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65   greater and the
d060: 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65   function pointe
d070: 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61  r is not NULL) a
d080: 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63  nd will fall bac
d090: 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74  k.** to xCurrent
d0a0: 54 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65  Time() if xCurre
d0b0: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73  ntTimeInt64() is
d0c0: 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a   unavailable..**
d0d0: 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73  .** ^The xSetSys
d0e0: 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53  temCall(), xGetS
d0f0: 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64  ystemCall(), and
d100: 20 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c   xNestSystemCall
d110: 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
d120: 20 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79   are not used by
d130: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
d140: 2e 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61  .  These optiona
d150: 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  l interfaces are
d160: 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20   provided.** by 
d170: 73 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61  some VFSes to fa
d180: 63 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67  cilitate testing
d190: 20 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64 65   of the VFS code
d1a0: 2e 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20  . By overriding 
d1b0: 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73  .** system calls
d1c0: 20 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20   with functions 
d1d0: 75 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f  under its contro
d1e0: 6c 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72 61  l, a test progra
d1f0: 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74  m can.** simulat
d200: 65 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72  e faults and err
d210: 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68  or conditions th
d220: 61 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69  at would otherwi
d230: 73 65 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a  se be difficult.
d240: 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65  ** or impossible
d250: 20 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65   to induce.  The
d260: 20 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63   set of system c
d270: 61 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65  alls that can be
d280: 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76   overridden.** v
d290: 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56  aries from one V
d2a0: 46 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61  FS to another, a
d2b0: 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73  nd from one vers
d2c0: 69 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ion of the same 
d2d0: 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65  VFS to the.** ne
d2e0: 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  xt.  Application
d2f0: 73 20 74 68 61 74 20 75 73 65 20 74 68 65 73 65  s that use these
d300: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74   interfaces must
d310: 20 62 65 20 70 72 65 70 61 72 65 64 20 66 6f 72   be prepared for
d320: 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f   any.** or all o
d330: 66 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  f these interfac
d340: 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72  es to be NULL or
d350: 20 66 6f 72 20 74 68 65 69 72 20 62 65 68 61 76   for their behav
d360: 69 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a  ior to change.**
d370: 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73   from one releas
d380: 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20  e to the next.  
d390: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73  Applications mus
d3a0: 74 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f  t not attempt to
d3b0: 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f   access.** any o
d3c0: 66 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20  f these methods 
d3d0: 69 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  if the iVersion 
d3e0: 6f 66 20 74 68 65 20 56 46 53 20 69 73 20 6c 65  of the VFS is le
d3f0: 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79  ss than 3..*/.ty
d400: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
d410: 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33  ite3_vfs sqlite3
d420: 5f 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f  _vfs;.typedef vo
d430: 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73  id (*sqlite3_sys
d440: 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b  call_ptr)(void);
d450: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
d460: 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72  vfs {.  int iVer
d470: 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20  sion;           
d480: 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65   /* Structure ve
d490: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75  rsion number (cu
d4a0: 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20  rrently 3) */.  
d4b0: 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20  int szOsFile;   
d4c0: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65           /* Size
d4d0: 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73   of subclassed s
d4e0: 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20  qlite3_file */. 
d4f0: 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b   int mxPathname;
d500: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
d510: 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61  imum file pathna
d520: 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73  me length */.  s
d530: 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78  qlite3_vfs *pNex
d540: 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20  t;      /* Next 
d550: 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a  registered VFS *
d560: 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
d570: 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20  zName;       /* 
d580: 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72  Name of this vir
d590: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
d5a0: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70   */.  void *pApp
d5b0: 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f  Data;          /
d5c0: 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70  * Pointer to app
d5d0: 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69  lication-specifi
d5e0: 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20  c data */.  int 
d5f0: 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  (*xOpen)(sqlite3
d600: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
d610: 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65  r *zName, sqlite
d620: 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20  3_file*,.       
d630: 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67          int flag
d640: 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67  s, int *pOutFlag
d650: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c  s);.  int (*xDel
d660: 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ete)(sqlite3_vfs
d670: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
d680: 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69  Name, int syncDi
d690: 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63  r);.  int (*xAcc
d6a0: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ess)(sqlite3_vfs
d6b0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
d6c0: 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c  Name, int flags,
d6d0: 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a   int *pResOut);.
d6e0: 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74    int (*xFullPat
d6f0: 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76  hname)(sqlite3_v
d700: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
d710: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74  *zName, int nOut
d720: 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20  , char *zOut);. 
d730: 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e   void *(*xDlOpen
d740: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
d750: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
d760: 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28  ename);.  void (
d770: 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74  *xDlError)(sqlit
d780: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79  e3_vfs*, int nBy
d790: 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73  te, char *zErrMs
d7a0: 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78  g);.  void (*(*x
d7b0: 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76  DlSym)(sqlite3_v
d7c0: 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74  fs*,void*, const
d7d0: 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29   char *zSymbol))
d7e0: 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28  (void);.  void (
d7f0: 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74  *xDlClose)(sqlit
d800: 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b  e3_vfs*, void*);
d810: 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d  .  int (*xRandom
d820: 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66  ness)(sqlite3_vf
d830: 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63  s*, int nByte, c
d840: 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e  har *zOut);.  in
d850: 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69  t (*xSleep)(sqli
d860: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69  te3_vfs*, int mi
d870: 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69  croseconds);.  i
d880: 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d  nt (*xCurrentTim
d890: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
d8a0: 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74   double*);.  int
d8b0: 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72   (*xGetLastError
d8c0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
d8d0: 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20  int, char *);.  
d8e0: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
d8f0: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
d900: 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68   version 1 of th
d910: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
d920: 65 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74  ect.  ** definit
d930: 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74  ion.  Those that
d940: 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65   follow are adde
d950: 64 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f  d in version 2 o
d960: 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69  r later.  */.  i
d970: 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d  nt (*xCurrentTim
d980: 65 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f  eInt64)(sqlite3_
d990: 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  vfs*, sqlite3_in
d9a0: 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a  t64*);.  /*.  **
d9b0: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f   The methods abo
d9c0: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f  ve are in versio
d9d0: 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68  ns 1 and 2 of th
d9e0: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
d9f0: 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20  ect..  ** Those 
da00: 62 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65  below are for ve
da10: 72 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61  rsion 3 and grea
da20: 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20  ter..  */.  int 
da30: 28 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c  (*xSetSystemCall
da40: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
da50: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
da60: 65 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61  e, sqlite3_sysca
da70: 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74  ll_ptr);.  sqlit
da80: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28  e3_syscall_ptr (
da90: 2a 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29  *xGetSystemCall)
daa0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
dab0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
dac0: 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  );.  const char 
dad0: 2a 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61  *(*xNextSystemCa
dae0: 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ll)(sqlite3_vfs*
daf0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
db00: 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  ame);.  /*.  ** 
db10: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
db20: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
db30: 73 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66  s 1 through 3 of
db40: 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20   the sqlite_vfs 
db50: 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77  object..  ** New
db60: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
db70: 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72  ppended in figur
db80: 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65  e versions.  The
db90: 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76   iVersion.  ** v
dba0: 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d  alue will increm
dbb0: 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69  ent whenever thi
dbc0: 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f  s happens. .  */
dbd0: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
dbe0: 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74  REF: Flags for t
dbf0: 68 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d  he xAccess VFS m
dc00: 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ethod.**.** Thes
dc10: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
dc20: 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  nts can be used 
dc30: 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72  as the third par
dc40: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ameter to.** the
dc50: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20   xAccess method 
dc60: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76  of an [sqlite3_v
dc70: 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65  fs] object.  The
dc80: 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77  y determine.** w
dc90: 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d  hat kind of perm
dca0: 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63  issions the xAcc
dcb0: 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f  ess method is lo
dcc0: 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69  oking for..** Wi
dcd0: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
dce0: 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63  _EXISTS, the xAc
dcf0: 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73  cess method.** s
dd00: 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65  imply checks whe
dd10: 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78  ther the file ex
dd20: 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51  ists..** With SQ
dd30: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
dd40: 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65  WRITE, the xAcce
dd50: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65  ss method.** che
dd60: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
dd70: 6e 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20  named directory 
dd80: 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65  is both readable
dd90: 20 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a   and writable.**
dda0: 20 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73   (in other words
ddb0: 2c 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62  , if files can b
ddc0: 65 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64  e added, removed
ddd0: 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69  , and renamed wi
dde0: 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65  thin.** the dire
ddf0: 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53  ctory)..** The S
de00: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
de10: 44 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20  DWRITE constant 
de20: 69 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65  is currently use
de30: 64 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a  d only by the.**
de40: 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72   [temp_store_dir
de50: 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20  ectory pragma], 
de60: 74 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c  though this coul
de70: 64 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75  d change in a fu
de80: 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20  ture.** release 
de90: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69  of SQLite..** Wi
dea0: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
deb0: 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65  _READ, the xAcce
dec0: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65  ss method.** che
ded0: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
dee0: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65  file is readable
def0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43  .  The SQLITE_AC
df00: 43 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61  CESS_READ consta
df10: 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74  nt is.** current
df20: 6c 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67  ly unused, thoug
df30: 68 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 73  h it might be us
df40: 65 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 72  ed in a future r
df50: 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c  elease of.** SQL
df60: 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ite..*/.#define 
df70: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
df80: 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e  ISTS    0.#defin
df90: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
dfa0: 52 45 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a  READWRITE 1   /*
dfb0: 20 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 20   Used by PRAGMA 
dfc0: 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
dfd0: 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  tory */.#define 
dfe0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
dff0: 41 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55  AD      2   /* U
e000: 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  nused */../*.** 
e010: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
e020: 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b  for the xShmLock
e030: 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a   VFS method.**.*
e040: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
e050: 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65  constants define
e060: 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63   the various loc
e070: 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a  king operations.
e080: 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68  ** allowed by th
e090: 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  e xShmLock metho
e0a0: 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f  d of [sqlite3_io
e0b0: 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a  _methods].  The.
e0c0: 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65  ** following are
e0d0: 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20   the only legal 
e0e0: 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20  combinations of 
e0f0: 66 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20  flags to the.** 
e100: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a  xShmLock method:
e110: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
e120: 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f  li>  SQLITE_SHM_
e130: 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
e140: 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e  M_SHARED.** <li>
e150: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43    SQLITE_SHM_LOC
e160: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  K | SQLITE_SHM_E
e170: 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e  XCLUSIVE.** <li>
e180: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c    SQLITE_SHM_UNL
e190: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
e1a0: 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20  _SHARED.** <li> 
e1b0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
e1c0: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
e1d0: 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75  EXCLUSIVE.** </u
e1e0: 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e  l>.**.** When un
e1f0: 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d  locking, the sam
e200: 65 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c  e SHARED or EXCL
e210: 55 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20  USIVE flag must 
e220: 62 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a  be supplied as.*
e230: 2a 20 77 61 73 20 67 69 76 65 6e 20 6e 6f 20 74  * was given no t
e240: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
e250: 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54   lock.  .**.** T
e260: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
e270: 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f  od can transitio
e280: 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b  n between unlock
e290: 65 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72  ed and SHARED or
e2a0: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f  .** between unlo
e2b0: 63 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49  cked and EXCLUSI
e2c0: 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74  VE.  It cannot t
e2d0: 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65  ransition betwee
e2e0: 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20  n SHARED.** and 
e2f0: 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64  EXCLUSIVE..*/.#d
e300: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
e310: 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a  _UNLOCK       1.
e320: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
e330: 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  HM_LOCK         
e340: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
e350: 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20  _SHM_SHARED     
e360: 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
e370: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
e380: 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      8../*.** CAP
e390: 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78  I3REF: Maximum x
e3a0: 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a  ShmLock index.**
e3b0: 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b  .** The xShmLock
e3c0: 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69   method on [sqli
e3d0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
e3e0: 6d 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a  may use values.*
e3f0: 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20  * between 0 and 
e400: 74 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64  this upper bound
e410: 20 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 22   as its "offset"
e420: 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68   argument..** Th
e430: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69  e SQLite core wi
e440: 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74  ll never attempt
e450: 20 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72   to acquire or r
e460: 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b  elease a.** lock
e470: 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 73   outside of this
e480: 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e   range.*/.#defin
e490: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f  e SQLITE_SHM_NLO
e4a0: 43 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a  CK        8.../*
e4b0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
e4c0: 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c  itialize The SQL
e4d0: 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a  ite Library.**.*
e4e0: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
e4f0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
e500: 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  ine initializes 
e510: 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69  the.** SQLite li
e520: 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c  brary.  ^The sql
e530: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
e540: 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c  routine.** deall
e550: 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75  ocates any resou
e560: 72 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61  rces that were a
e570: 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69  llocated by sqli
e580: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
e590: 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  ..** These routi
e5a0: 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 64  nes are designed
e5b0: 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65   to aid in proce
e5c0: 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ss initializatio
e5d0: 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77  n and.** shutdow
e5e0: 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79  n on embedded sy
e5f0: 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74  stems.  Workstat
e600: 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  ion applications
e610: 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65   using.** SQLite
e620: 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74   normally do not
e630: 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20   need to invoke 
e640: 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20  either of these 
e650: 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
e660: 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
e670: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
e680: 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22  s an "effective"
e690: 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a   call if it is.*
e6a0: 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65  * the first time
e6b0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
e6c0: 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
e6d0: 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65   during the life
e6e0: 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70  time of.** the p
e6f0: 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74  rocess, or if it
e700: 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69   is the first ti
e710: 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  me sqlite3_initi
e720: 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
e730: 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ed.** following 
e740: 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  a call to sqlite
e750: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e  3_shutdown().  ^
e760: 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69  (Only an effecti
e770: 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71  ve call.** of sq
e780: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
e790: 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74  () does any init
e7a0: 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c  ialization.  All
e7b0: 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20   other calls.** 
e7c0: 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  are harmless no-
e7d0: 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63  ops.)^.**.** A c
e7e0: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
e7f0: 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20  hutdown() is an 
e800: 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c  "effective" call
e810: 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69   if it is the fi
e820: 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73  rst.** call to s
e830: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
e840: 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74  ) since the last
e850: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
e860: 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a  ize().  ^(Only.*
e870: 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63  * an effective c
e880: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
e890: 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61  hutdown() does a
e8a0: 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74  ny deinitializat
e8b0: 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65  ion..** All othe
e8c0: 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f  r valid calls to
e8d0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
e8e0: 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73  n() are harmless
e8f0: 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a   no-ops.)^.**.**
e900: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69   The sqlite3_ini
e910: 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66  tialize() interf
e920: 61 63 65 20 69 73 20 74 68 72 65 61 64 73 61 66  ace is threadsaf
e930: 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73  e, but sqlite3_s
e940: 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20  hutdown().** is 
e950: 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  not.  The sqlite
e960: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74  3_shutdown() int
e970: 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79  erface must only
e980: 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
e990: 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65  a.** single thre
e9a0: 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64  ad.  All open [d
e9b0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
e9c0: 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f  ons] must be clo
e9d0: 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f  sed and all.** o
e9e0: 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f  ther SQLite reso
e9f0: 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 65  urces must be de
ea00: 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20  allocated prior 
ea10: 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73  to invoking.** s
ea20: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
ea30: 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f  )..**.** Among o
ea40: 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71  ther things, ^sq
ea50: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
ea60: 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a  () will invoke.*
ea70: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  * sqlite3_os_ini
ea80: 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c  t().  Similarly,
ea90: 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   ^sqlite3_shutdo
eaa0: 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76  wn().** will inv
eab0: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  oke sqlite3_os_e
eac0: 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nd()..**.** ^The
ead0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
eae0: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65  ize() routine re
eaf0: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
eb00: 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a  ] on success..**
eb10: 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65   ^If for some re
eb20: 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ason, sqlite3_in
eb30: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e  itialize() is un
eb40: 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69  able to initiali
eb50: 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72  ze.** the librar
eb60: 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73  y (perhaps it is
eb70: 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
eb80: 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73  ate a needed res
eb90: 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73  ource such.** as
eba0: 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74   a mutex) it ret
ebb0: 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63  urns an [error c
ebc0: 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20  ode] other than 
ebd0: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a  [SQLITE_OK]..**.
ebe0: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
ebf0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
ec00: 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69  tine is called i
ec10: 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e  nternally by man
ec20: 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74  y other.** SQLit
ec30: 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20  e interfaces so 
ec40: 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74  that an applicat
ec50: 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73  ion usually does
ec60: 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20   not need to.** 
ec70: 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69  invoke sqlite3_i
ec80: 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65  nitialize() dire
ec90: 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70  ctly.  For examp
eca0: 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  le, [sqlite3_ope
ecb0: 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71  n()].** calls sq
ecc0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
ecd0: 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65  () so the SQLite
ece0: 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65   library will be
ecf0: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a   automatically.*
ed00: 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68  * initialized wh
ed10: 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  en [sqlite3_open
ed20: 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66  ()] is called if
ed30: 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69   it has not be i
ed40: 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c  nitialized.** al
ed50: 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72  ready.  ^However
ed60: 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63  , if SQLite is c
ed70: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
ed80: 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55   [SQLITE_OMIT_AU
ed90: 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69  TOINIT].** compi
eda0: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20  le-time option, 
edb0: 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74  then the automat
edc0: 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ic calls to sqli
edd0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
ede0: 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20  .** are omitted 
edf0: 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  and the applicat
ee00: 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71  ion must call sq
ee10: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
ee20: 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70  () directly.** p
ee30: 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e  rior to using an
ee40: 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
ee50: 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d  nterface.  For m
ee60: 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69  aximum portabili
ee70: 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63  ty,.** it is rec
ee80: 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70  ommended that ap
ee90: 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79  plications alway
eea0: 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  s invoke sqlite3
eeb0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a  _initialize().**
eec0: 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20   directly prior 
eed0: 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68  to using any oth
eee0: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
eef0: 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c  ace.  Future rel
ef00: 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69  eases.** of SQLi
ef10: 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74  te may require t
ef20: 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  his.  In other w
ef30: 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69  ords, the behavi
ef40: 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20  or exhibited.** 
ef50: 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
ef60: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51  ompiled with [SQ
ef70: 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e  LITE_OMIT_AUTOIN
ef80: 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65  IT] might become
ef90: 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20   the.** default 
efa0: 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65  behavior in some
efb0: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
efc0: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
efd0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
efe0: 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64  init() routine d
eff0: 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79  oes operating-sy
f000: 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a  stem specific.**
f010: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
f020: 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  of the SQLite li
f030: 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69  brary.  The sqli
f040: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
f050: 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74  routine undoes t
f060: 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c  he effect of sql
f070: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
f080: 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a   Typical tasks.*
f090: 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74  * performed by t
f0a0: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e  hese routines in
f0b0: 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e  clude allocation
f0c0: 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e   or deallocation
f0d0: 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65  .** of static re
f0e0: 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c  sources, initial
f0f0: 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61  ization of globa
f100: 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20  l variables,.** 
f110: 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66  setting up a def
f120: 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
f130: 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65  s] module, or se
f140: 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65  tting up.** a de
f150: 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74  fault configurat
f160: 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ion using [sqlit
f170: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a  e3_config()]..**
f180: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
f190: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
f1a0: 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73   invoke either s
f1b0: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
f1c0: 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  .** or sqlite3_o
f1d0: 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79  s_end() directly
f1e0: 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  .  The applicati
f1f0: 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69  on should only i
f200: 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
f210: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e  _initialize() an
f220: 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  d sqlite3_shutdo
f230: 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74  wn().  The sqlit
f240: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20  e3_os_init().** 
f250: 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c  interface is cal
f260: 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  led automaticall
f270: 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69  y by sqlite3_ini
f280: 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a  tialize() and.**
f290: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
f2a0: 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73  ) is called by s
f2b0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
f2c0: 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a  ).  Appropriate.
f2d0: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
f2e0: 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  ns for sqlite3_o
f2f0: 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c  s_init() and sql
f300: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
f310: 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20   are built into 
f320: 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69  SQLite when it i
f330: 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55  s compiled for U
f340: 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72  nix, Windows, or
f350: 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b   OS/2..** When [
f360: 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20  custom builds | 
f370: 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20  built for other 
f380: 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75  platforms].** (u
f390: 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
f3a0: 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d  _OS_OTHER=1] com
f3b0: 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74  pile-time.** opt
f3c0: 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61  ion) the applica
f3d0: 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79  tion must supply
f3e0: 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c   a suitable impl
f3f0: 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a  ementation for.*
f400: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  * sqlite3_os_ini
f410: 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
f420: 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70  os_end().  An ap
f430: 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69  plication-suppli
f440: 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ed.** implementa
f450: 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  tion of sqlite3_
f460: 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c  os_init() or sql
f470: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
f480: 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51   must return [SQ
f490: 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
f4a0: 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68  ess and some oth
f4b0: 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  er [error code] 
f4c0: 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e  upon.** failure.
f4d0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
f4e0: 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29  initialize(void)
f4f0: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68  ;.int sqlite3_sh
f500: 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e  utdown(void);.in
f510: 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  t sqlite3_os_ini
f520: 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  t(void);.int sql
f530: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64  ite3_os_end(void
f540: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
f550: 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20  EF: Configuring 
f560: 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61  The SQLite Libra
f570: 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ry.**.** The sql
f580: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e  ite3_config() in
f590: 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20  terface is used 
f5a0: 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63  to make global c
f5b0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20  onfiguration.** 
f5c0: 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74  changes to SQLit
f5d0: 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75  e in order to tu
f5e0: 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65  ne SQLite to the
f5f0: 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20   specific needs 
f600: 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
f610: 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61  ation.  The defa
f620: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
f630: 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  n is recommended
f640: 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70   for most.** app
f650: 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f  lications and so
f660: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
f670: 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63   usually not nec
f680: 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a  essary.  It is.*
f690: 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75  * provided to su
f6a0: 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69  pport rare appli
f6b0: 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75  cations with unu
f6c0: 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a  sual needs..**.*
f6d0: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
f6e0: 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
f6f0: 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61   is not threadsa
f700: 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61  fe.  The applica
f710: 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73  tion.** must ins
f720: 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65  ure that no othe
f730: 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
f740: 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20  ces are invoked 
f750: 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65  by other.** thre
f760: 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65  ads while sqlite
f770: 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75  3_config() is ru
f780: 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72 6d  nning.  Furtherm
f790: 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e  ore, sqlite3_con
f7a0: 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c  fig().** may onl
f7b0: 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69  y be invoked pri
f7c0: 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e  or to library in
f7d0: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69  itialization usi
f7e0: 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69  ng.** [sqlite3_i
f7f0: 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20  nitialize()] or 
f800: 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62  after shutdown b
f810: 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  y [sqlite3_shutd
f820: 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73  own()]..** ^If s
f830: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
f840: 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20  is called after 
f850: 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
f860: 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72  ize()] and befor
f870: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68  e.** [sqlite3_sh
f880: 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69  utdown()] then i
f890: 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51  t will return SQ
f8a0: 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20  LITE_MISUSE..** 
f8b0: 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74  Note, however, t
f8c0: 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e  hat ^sqlite3_con
f8d0: 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c  fig() can be cal
f8e0: 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74  led as part of t
f8f0: 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
f900: 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69  tion of an appli
f910: 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b  cation-defined [
f920: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
f930: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  )]..**.** The fi
f940: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
f950: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
f960: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a   is an integer.*
f970: 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  * [configuration
f980: 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65   option] that de
f990: 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74  termines.** what
f9a0: 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c   property of SQL
f9b0: 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e  ite is to be con
f9c0: 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71  figured.  Subseq
f9d0: 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a  uent arguments.*
f9e0: 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67  * vary depending
f9f0: 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 75   on the [configu
fa00: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a  ration option].*
fa10: 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  * in the first a
fa20: 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
fa30: 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61  When a configura
fa40: 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73  tion option is s
fa50: 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  et, sqlite3_conf
fa60: 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51  ig() returns [SQ
fa70: 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66  LITE_OK]..** ^If
fa80: 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75   the option is u
fa90: 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65  nknown or SQLite
faa0: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65   is unable to se
fab0: 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20  t the option.** 
fac0: 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e  then this routin
fad0: 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d  e returns a non-
fae0: 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
faf0: 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
fb00: 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e  3_config(int, ..
fb10: 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
fb20: 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64  REF: Configure d
fb30: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
fb40: 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ons.**.** The sq
fb50: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
fb60: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75  ) interface is u
fb70: 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66  sed to make conf
fb80: 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61  iguration.** cha
fb90: 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62  nges to a [datab
fba0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
fbb0: 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20    The interface 
fbc0: 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a  is similar to.**
fbd0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
fbe0: 28 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20  ()] except that 
fbf0: 74 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c  the changes appl
fc00: 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a  y to a single.**
fc10: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
fc20: 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65  ction] (specifie
fc30: 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  d in the first a
fc40: 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20  rgument)..**.** 
fc50: 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
fc60: 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64  ent to sqlite3_d
fc70: 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e  b_config(D,V,...
fc80: 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51  )  is the.** [SQ
fc90: 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
fca0: 4f 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69 67  OKASIDE | config
fcb0: 75 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20  uration verb] - 
fcc0: 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20  an integer code 
fcd0: 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74  .** that indicat
fce0: 65 73 20 77 68 61 74 20 61 73 70 65 63 74 20 6f  es what aspect o
fcf0: 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  f the [database 
fd00: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62  connection] is b
fd10: 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e  eing configured.
fd20: 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61  .** Subsequent a
fd30: 72 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64 65  rguments vary de
fd40: 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63  pending on the c
fd50: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72  onfiguration ver
fd60: 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20  b..**.** ^Calls 
fd70: 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  to sqlite3_db_co
fd80: 6e 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 51  nfig() return SQ
fd90: 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f  LITE_OK if and o
fda0: 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61  nly if.** the ca
fdb0: 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  ll is considered
fdc0: 20 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a   successful..*/.
fdd0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  int sqlite3_db_c
fde0: 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20  onfig(sqlite3*, 
fdf0: 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f  int op, ...);../
fe00: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
fe10: 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e  emory Allocation
fe20: 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20   Routines.**.** 
fe30: 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
fe40: 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e  his object defin
fe50: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
fe60: 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a   between SQLite.
fe70: 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c  ** and low-level
fe80: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
fe90: 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  on routines..**.
fea0: 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  ** This object i
feb0: 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f  s used in only o
fec0: 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20  ne place in the 
fed0: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
fee0: 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74  ..** A pointer t
fef0: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
ff00: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   this object is 
ff10: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  the argument to.
ff20: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
ff30: 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63  ig()] when the c
ff40: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
ff50: 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54  ion is.** [SQLIT
ff60: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
ff70: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   or [SQLITE_CONF
ff80: 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20  IG_GETMALLOC].  
ff90: 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20  .** By creating 
ffa0: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
ffb0: 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e  his object.** an
ffc0: 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20  d passing it to 
ffd0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d  [sqlite3_config]
ffe0: 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ([SQLITE_CONFIG_
fff0: 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69  MALLOC]).** duri
10000 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
10010 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
10020 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20   can specify an 
10030 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d  alternative.** m
10040 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
10050 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53   subsystem for S
10060 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72  QLite to use for
10070 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64   all of its.** d
10080 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65  ynamic memory ne
10090 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  eds..**.** Note 
100a0 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65  that SQLite come
100b0 73 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b  s with several [
100c0 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
100d0 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74  allocators].** t
100e0 68 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c  hat are perfectl
100f0 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74  y adequate for t
10100 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20  he overwhelming 
10110 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c  majority of appl
10120 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20  ications.** and 
10130 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74  that this object
10140 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20   is only useful 
10150 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69  to a tiny minori
10160 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f  ty of applicatio
10170 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69  ns.** with speci
10180 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c  alized memory al
10190 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65  location require
101a0 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a  ments.  This obj
101b0 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75  ect is.** also u
101c0 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69  sed during testi
101d0 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20  ng of SQLite in 
101e0 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79  order to specify
101f0 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a   an alternative.
10200 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
10210 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74  tor that simulat
10220 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66  es memory out-of
10230 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f  -memory conditio
10240 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74  ns in.** order t
10250 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51  o verify that SQ
10260 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72  Lite recovers gr
10270 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75  acefully from su
10280 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73  ch.** conditions
10290 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c  ..**.** The xMal
102a0 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61  loc, xRealloc, a
102b0 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73  nd xFree methods
102c0 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20   must work like 
102d0 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c  the.** malloc(),
102e0 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66   realloc() and f
102f0 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20  ree() functions 
10300 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72  from the standar
10310 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20  d C library..** 
10320 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65  ^SQLite guarante
10330 65 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f  es that the seco
10340 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
10350 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c  * xRealloc is al
10360 77 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74  ways a value ret
10370 75 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72  urned by a prior
10380 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75   call to xRoundu
10390 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73  p..**.** xSize s
103a0 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65  hould return the
103b0 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20   allocated size 
103c0 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  of a memory allo
103d0 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f  cation.** previo
103e0 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72  usly obtained fr
103f0 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52  om xMalloc or xR
10400 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c  ealloc.  The all
10410 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69  ocated size.** i
10420 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73  s always at leas
10430 74 20 61 73 20 62 69 67 20 61 73 20 74 68 65 20  t as big as the 
10440 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 62  requested size b
10450 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72  ut may be larger
10460 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75  ..**.** The xRou
10470 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75  ndup method retu
10480 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62  rns what would b
10490 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20  e the allocated 
104a0 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d  size of.** a mem
104b0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67  ory allocation g
104c0 69 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61  iven a particula
104d0 72 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65  r requested size
104e0 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a  .  Most memory.*
104f0 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75  * allocators rou
10500 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c  nd up memory all
10510 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73  ocations at leas
10520 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75  t to the next mu
10530 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20  ltiple.** of 8. 
10540 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73   Some allocators
10550 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c   round up to a l
10560 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  arger multiple o
10570 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20  r to a power of 
10580 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f  2..** Every memo
10590 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65  ry allocation re
105a0 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20  quest coming in 
105b0 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33  through [sqlite3
105c0 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72  _malloc()].** or
105d0 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
105e0 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73  c()] first calls
105f0 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78   xRoundup.  If x
10600 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20  Roundup returns 
10610 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73  0, .** that caus
10620 65 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  es the correspon
10630 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ding memory allo
10640 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a  cation to fail..
10650 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20  **.** The xInit 
10660 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a  method initializ
10670 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  es the memory al
10680 6c 6f 63 61 74 6f 72 2e 20 20 46 6f 72 20 65 78  locator.  For ex
10690 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67  ample,.** it mig
106a0 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20  ht allocate any 
106b0 72 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20  require mutexes 
106c0 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e  or initialize in
106d0 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73  ternal data.** s
106e0 74 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20  tructures.  The 
106f0 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64  xShutdown method
10700 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64   is invoked (ind
10710 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b  irectly) by.** [
10720 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
10730 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64  ()] and should d
10740 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65  eallocate any re
10750 73 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64  sources acquired
10760 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54  .** by xInit.  T
10770 68 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e  he pAppData poin
10780 74 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74  ter is used as t
10790 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65  he only paramete
107a0 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e  r to.** xInit an
107b0 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a  d xShutdown..**.
107c0 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20  ** SQLite holds 
107d0 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45  the [SQLITE_MUTE
107e0 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d  X_STATIC_MASTER]
107f0 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20 69   mutex when it i
10800 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49  nvokes.** the xI
10810 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74  nit method, so t
10820 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20  he xInit method 
10830 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65  need not be thre
10840 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20  adsafe.  The.** 
10850 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64  xShutdown method
10860 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20   is only called 
10870 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68  from [sqlite3_sh
10880 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20  utdown()] so it 
10890 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64  does.** not need
108a0 20 74 6f 20 62 65 20 74 68 72 65 61 64 73 61 66   to be threadsaf
108b0 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61  e either.  For a
108c0 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73  ll other methods
108d0 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64  , SQLite.** hold
108e0 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55  s the [SQLITE_MU
108f0 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20  TEX_STATIC_MEM] 
10900 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73  mutex as long as
10910 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
10920 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
10930 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  ] configuration 
10940 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64  option is turned
10950 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74   on (which.** it
10960 20 69 73 20 62 79 20 64 65 66 61 75 6c 74 29 20   is by default) 
10970 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f  and so the metho
10980 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63  ds are automatic
10990 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e  ally serialized.
109a0 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20  .** However, if 
109b0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
109c0 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69 73  EMSTATUS] is dis
109d0 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20  abled, then the 
109e0 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73  other.** methods
109f0 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73   must be threads
10a00 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65  afe or else make
10a10 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e   their own arran
10a20 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73  gements for.** s
10a30 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a  erialization..**
10a40 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
10a50 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e  never invoke xIn
10a60 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f  it() more than o
10a70 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69  nce without an i
10a80 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61  ntervening.** ca
10a90 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28  ll to xShutdown(
10aa0 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  )..*/.typedef st
10ab0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d  ruct sqlite3_mem
10ac0 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33  _methods sqlite3
10ad0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74  _mem_methods;.st
10ae0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d  ruct sqlite3_mem
10af0 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69  _methods {.  voi
10b00 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e  d *(*xMalloc)(in
10b10 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d  t);         /* M
10b20 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
10b30 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76   function */.  v
10b40 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69  oid (*xFree)(voi
10b50 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  d*);          /*
10b60 20 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c   Free a prior al
10b70 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  location */.  vo
10b80 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28  id *(*xRealloc)(
10b90 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20  void*,int);  /* 
10ba0 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61  Resize an alloca
10bb0 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  tion */.  int (*
10bc0 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20  xSize)(void*);  
10bd0 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75           /* Retu
10be0 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61  rn the size of a
10bf0 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  n allocation */.
10c00 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70    int (*xRoundup
10c10 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20  )(int);         
10c20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71   /* Round up req
10c30 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c  uest size to all
10c40 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a  ocation size */.
10c50 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76    int (*xInit)(v
10c60 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
10c70 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74   /* Initialize t
10c80 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
10c90 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a  tor */.  void (*
10ca0 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a  xShutdown)(void*
10cb0 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69  );      /* Deini
10cc0 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f  tialize the memo
10cd0 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a  ry allocator */.
10ce0 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61    void *pAppData
10cf0 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
10d00 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20   /* Argument to 
10d10 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75  xInit() and xShu
10d20 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f  tdown() */.};../
10d30 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
10d40 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74  onfiguration Opt
10d50 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ions.** KEYWORDS
10d60 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  : {configuration
10d70 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54   option}.**.** T
10d80 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
10d90 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65  re the available
10da0 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75   integer configu
10db0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74  ration options t
10dc0 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61  hat.** can be pa
10dd0 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73  ssed as the firs
10de0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
10df0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
10e00 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  g()] interface..
10e10 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67  **.** New config
10e20 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
10e30 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
10e40 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
10e50 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78  of SQLite..** Ex
10e60 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  isting configura
10e70 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67  tion options mig
10e80 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75  ht be discontinu
10e90 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ed.  Application
10ea0 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63  s.** should chec
10eb0 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64  k the return cod
10ec0 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  e from [sqlite3_
10ed0 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b  config()] to mak
10ee0 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74  e sure that.** t
10ef0 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20  he call worked. 
10f00 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
10f10 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
10f20 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a  e will return a.
10f30 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72  ** non-zero [err
10f40 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69  or code] if a di
10f50 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e  scontinued or un
10f60 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67  supported config
10f70 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a  uration option.*
10f80 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  * is invoked..**
10f90 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51  .** <dl>.** [[SQ
10fa0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
10fb0 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53  LETHREAD]] <dt>S
10fc0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
10fd0 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a  GLETHREAD</dt>.*
10fe0 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
10ff0 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
11000 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54  this option.  ^T
11010 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
11020 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e  the.** [threadin
11030 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c  g mode] to Singl
11040 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74  e-thread.  In ot
11050 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69  her words, it di
11060 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75  sables.** all mu
11070 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20  texing and puts 
11080 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f  SQLite into a mo
11090 64 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20  de where it can 
110a0 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20  only be used.** 
110b0 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65  by a single thre
110c0 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65  ad.   ^If SQLite
110d0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
110e0 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
110f0 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
11100 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
11110 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
11120 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
11130 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
11140 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  e to change the 
11150 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
11160 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c   from its defaul
11170 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69  t.** value of Si
11180 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20  ngle-thread and 
11190 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  so [sqlite3_conf
111a0 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ig()] will retur
111b0 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52  n .** [SQLITE_ER
111c0 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77  ROR] if called w
111d0 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ith the SQLITE_C
111e0 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
111f0 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  AD.** configurat
11200 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
11210 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
11220 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
11230 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AD]] <dt>SQLITE_
11240 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
11250 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  AD</dt>.** <dd>T
11260 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
11270 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
11280 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74  tion.  ^This opt
11290 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
112a0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
112b0 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64   to Multi-thread
112c0 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
112d0 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a  s, it disables.*
112e0 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64  * mutexing on [d
112f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
11300 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  on] and [prepare
11310 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a  d statement] obj
11320 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70  ects..** The app
11330 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70  lication is resp
11340 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69  onsible for seri
11350 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74  alizing access t
11360 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  o.** [database c
11370 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20  onnections] and 
11380 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
11390 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65  ents].  But othe
113a0 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65  r mutexes.** are
113b0 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74   enabled so that
113c0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20   SQLite will be 
113d0 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61  safe to use in a
113e0 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a   multi-threaded.
113f0 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61  ** environment a
11400 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f  s long as no two
11410 20 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 74   threads attempt
11420 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65   to use the same
11430 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
11440 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65  nnection] at the
11450 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66   same time.  ^If
11460 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
11470 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
11480 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
11490 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
114a0 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
114b0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
114c0 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
114d0 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20  possible to set 
114e0 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64  the Multi-thread
114f0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
11500 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
11510 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
11520 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
11530 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64  ERROR] if called
11540 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c   with the.** SQL
11550 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
11560 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61  THREAD configura
11570 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64  tion option.</dd
11580 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
11590 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
115a0 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ED]] <dt>SQLITE_
115b0 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
115c0 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
115d0 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
115e0 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
115f0 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
11600 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
11610 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
11620 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49  to Serialized. I
11630 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
11640 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c  his option enabl
11650 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65  es.** all mutexe
11660 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20  s including the 
11670 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74  recursive.** mut
11680 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73  exes on [databas
11690 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
116a0 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
116b0 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
116c0 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20  ** In this mode 
116d0 28 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65  (which is the de
116e0 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74  fault when SQLit
116f0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
11700 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48  th.** [SQLITE_TH
11710 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65  READSAFE=1]) the
11720 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
11730 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69  will itself seri
11740 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20  alize access.** 
11750 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  to [database con
11760 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70  nections] and [p
11770 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
11780 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a  ts] so that the.
11790 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  ** application i
117a0 73 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68  s free to use th
117b0 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
117c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20   connection] or 
117d0 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65  the.** same [pre
117e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
117f0 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68   in different th
11800 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
11810 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53  e time..** ^If S
11820 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
11830 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
11840 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
11850 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
11860 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
11870 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
11880 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
11890 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68  ssible to set th
118a0 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e Serialized [th
118b0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e  reading mode] an
118c0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
118d0 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
118e0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
118f0 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
11900 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
11910 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
11920 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  D configuration 
11930 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  option.</dd>.**.
11940 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
11950 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e  IG_MALLOC]] <dt>
11960 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
11970 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LLOC</dt>.** <dd
11980 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
11990 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
119a0 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
119b0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
119c0 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
119d0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
119e0 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
119f0 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65  ure.  The argume
11a00 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  nt specifies.** 
11a10 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d  alternative low-
11a20 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
11a30 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
11a40 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70   to be used in p
11a50 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d  lace of.** the m
11a60 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
11a70 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20   routines built 
11a80 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e  into SQLite.)^ ^
11a90 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20  SQLite makes.** 
11aa0 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
11ab0 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74  copy of the cont
11ac0 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ent of the [sqli
11ad0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
11ae0 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65   structure.** be
11af0 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65  fore the [sqlite
11b00 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c  3_config()] call
11b10 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a   returns.</dd>.*
11b20 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
11b30 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d  NFIG_GETMALLOC]]
11b40 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
11b50 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74  IG_GETMALLOC</dt
11b60 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
11b70 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
11b80 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
11b90 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
11ba0 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
11bb0 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
11bc0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
11bd0 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
11be0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
11bf0 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63  ethods].** struc
11c00 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77  ture is filled w
11c10 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c  ith the currentl
11c20 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79  y defined memory
11c30 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
11c40 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20  ines.)^.** This 
11c50 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
11c60 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74  ed to overload t
11c70 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72  he default memor
11c80 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
11c90 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20  routines with a 
11ca0 77 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d  wrapper that sim
11cb0 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20  ulations memory 
11cc0 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75  allocation failu
11cd0 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20  re or.** tracks 
11ce0 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f  memory usage, fo
11cf0 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e  r example. </dd>
11d00 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
11d10 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
11d20 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
11d30 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f  NFIG_MEMSTATUS</
11d40 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
11d50 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73  s option takes s
11d60 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f  ingle argument o
11d70 66 20 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 65  f type int, inte
11d80 72 70 72 65 74 65 64 20 61 73 20 61 20 0a 2a 2a  rpreted as a .**
11d90 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20   boolean, which 
11da0 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
11db0 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69  les the collecti
11dc0 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c  on of memory all
11dd0 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74  ocation .** stat
11de0 69 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d  istics. ^(When m
11df0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
11e00 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
11e10 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20 0a 2a  disabled, the .*
11e20 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69  * following SQLi
11e30 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 65  te interfaces be
11e40 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69  come non-operati
11e50 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a  onal:.**   <ul>.
11e60 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
11e70 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
11e80 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
11e90 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
11ea0 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c  water()].**   <l
11eb0 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74  i> [sqlite3_soft
11ec0 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d  _heap_limit64()]
11ed0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
11ee0 74 65 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a  te3_status()].**
11ef0 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d     </ul>)^.** ^M
11f00 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
11f10 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
11f20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  enabled by defau
11f30 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65  lt unless SQLite
11f40 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
11f50 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46  with [SQLITE_DEF
11f60 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d  AULT_MEMSTATUS]=
11f70 30 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  0 in which case 
11f80 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
11f90 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20  tion statistics 
11fa0 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20  are disabled by 
11fb0 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64  default..** </dd
11fc0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
11fd0 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d  _CONFIG_SCRATCH]
11fe0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
11ff0 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e  FIG_SCRATCH</dt>
12000 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
12010 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
12020 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20  a static memory 
12030 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69  buffer that SQLi
12040 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a  te can use for.*
12050 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79  * scratch memory
12060 2e 20 20 54 68 65 72 65 20 61 72 65 20 74 68 72  .  There are thr
12070 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41  ee arguments:  A
12080 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79   pointer an 8-by
12090 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65  te.** aligned me
120a0 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d  mory buffer from
120b0 20 77 68 69 63 68 20 74 68 65 20 73 63 72 61 74   which the scrat
120c0 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77  ch allocations w
120d0 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c  ill be.** drawn,
120e0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63   the size of eac
120f0 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61  h scratch alloca
12100 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e  tion (sz),.** an
12110 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d the maximum nu
12120 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63 68 20  mber of scratch 
12130 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e  allocations (N).
12140 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75    The sz.** argu
12150 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d  ment must be a m
12160 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 0a 2a  ultiple of 16..*
12170 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
12180 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70  ment must be a p
12190 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62  ointer to an 8-b
121a0 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66  yte aligned buff
121b0 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73  er.** of at leas
121c0 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20  t sz*N bytes of 
121d0 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69  memory..** ^SQLi
121e0 74 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d  te will use no m
121f0 6f 72 65 20 74 68 61 6e 20 74 77 6f 20 73 63 72  ore than two scr
12200 61 74 63 68 20 62 75 66 66 65 72 73 20 70 65 72  atch buffers per
12210 20 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a 2a 20   thread.  So.** 
12220 4e 20 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20  N should be set 
12230 74 6f 20 74 77 69 63 65 20 74 68 65 20 65 78 70  to twice the exp
12240 65 63 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75  ected maximum nu
12250 6d 62 65 72 20 6f 66 20 74 68 72 65 61 64 73 2e  mber of threads.
12260 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
12270 20 6e 65 76 65 72 20 72 65 71 75 69 72 65 20 61   never require a
12280 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20   scratch buffer 
12290 74 68 61 74 20 69 73 20 6d 6f 72 65 20 74 68 61  that is more tha
122a0 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65  n 6.** times the
122b0 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 73   database page s
122c0 69 7a 65 2e 20 5e 49 66 20 53 51 4c 69 74 65 20  ize. ^If SQLite 
122d0 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64 64 69  needs needs addi
122e0 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63  tional.** scratc
122f0 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20  h memory beyond 
12300 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64  what is provided
12310 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75   by this configu
12320 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74  ration option, t
12330 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  hen .** [sqlite3
12340 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20  _malloc()] will 
12350 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
12360 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65  n the memory nee
12370 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ded.</dd>.**.** 
12380 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
12390 50 41 47 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e  PAGECACHE]] <dt>
123a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
123b0 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20  GECACHE</dt>.** 
123c0 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
123d0 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74  n specifies a st
123e0 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66  atic memory buff
123f0 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  er that SQLite c
12400 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68  an use for.** th
12410 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20  e database page 
12420 63 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64  cache with the d
12430 65 66 61 75 6c 74 20 70 61 67 65 20 63 61 63 68  efault page cach
12440 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
12450 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66  .  .** This conf
12460 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64  iguration should
12470 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66 20   not be used if 
12480 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
12490 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61  efine page.** ca
124a0 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
124b0 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69  on is loaded usi
124c0 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  ng the SQLITE_CO
124d0 4e 46 49 47 5f 50 43 41 43 48 45 32 20 6f 70 74  NFIG_PCACHE2 opt
124e0 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72  ion..** There ar
124f0 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
12500 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
12510 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 38  : A pointer to 8
12520 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a  -byte aligned.**
12530 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a   memory, the siz
12540 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 62  e of each page b
12550 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20  uffer (sz), and 
12560 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61  the number of pa
12570 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20  ges (N)..** The 
12580 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  sz argument shou
12590 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f  ld be the size o
125a0 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61  f the largest da
125b0 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28  tabase page.** (
125c0 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62  a power of two b
125d0 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33  etween 512 and 3
125e0 32 37 36 38 29 20 70 6c 75 73 20 61 20 6c 69 74  2768) plus a lit
125f0 74 6c 65 20 65 78 74 72 61 20 66 6f 72 20 65 61  tle extra for ea
12600 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65  ch.** page heade
12610 72 2e 20 20 5e 54 68 65 20 70 61 67 65 20 68 65  r.  ^The page he
12620 61 64 65 72 20 73 69 7a 65 20 69 73 20 32 30 20  ader size is 20 
12630 74 6f 20 34 30 20 62 79 74 65 73 20 64 65 70 65  to 40 bytes depe
12640 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20  nding on.** the 
12650 68 6f 73 74 20 61 72 63 68 69 74 65 63 74 75 72  host architectur
12660 65 2e 20 20 5e 49 74 20 69 73 20 68 61 72 6d 6c  e.  ^It is harml
12670 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20  ess, apart from 
12680 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72  the wasted memor
12690 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 7a  y,.** to make sz
126a0 20 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20 6c 61   a little too la
126b0 72 67 65 2e 20 20 54 68 65 20 66 69 72 73 74 0a  rge.  The first.
126c0 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  ** argument shou
126d0 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61  ld point to an a
126e0 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20  llocation of at 
126f0 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73  least sz*N bytes
12700 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e   of memory..** ^
12710 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
12720 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69  the memory provi
12730 64 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ded by the first
12740 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74   argument to sat
12750 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f  isfy its.** memo
12760 72 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65  ry needs for the
12770 20 66 69 72 73 74 20 4e 20 70 61 67 65 73 20 74   first N pages t
12780 68 61 74 20 69 74 20 61 64 64 73 20 74 6f 20 63  hat it adds to c
12790 61 63 68 65 2e 20 20 5e 49 66 20 61 64 64 69 74  ache.  ^If addit
127a0 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61  ional.** page ca
127b0 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65  che memory is ne
127c0 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74  eded beyond what
127d0 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20   is provided by 
127e0 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65  this option, the
127f0 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73  n.** SQLite goes
12800 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   to [sqlite3_mal
12810 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61  loc()] for the a
12820 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67  dditional storag
12830 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68 65 20  e space..** The 
12840 70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65 20 66  pointer in the f
12850 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
12860 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65 64  st.** be aligned
12870 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f   to an 8-byte bo
12880 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71  undary or subseq
12890 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66  uent behavior of
128a0 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20   SQLite.** will 
128b0 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64  be undefined.</d
128c0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
128d0 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20  E_CONFIG_HEAP]] 
128e0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
128f0 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  G_HEAP</dt>.** <
12900 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
12910 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
12920 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
12930 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  r that SQLite wi
12940 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c  ll use.** for al
12950 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63  l of its dynamic
12960 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
12970 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20  on needs beyond 
12980 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a  those provided.*
12990 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45  * for by [SQLITE
129a0 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d  _CONFIG_SCRATCH]
129b0 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   and [SQLITE_CON
129c0 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a  FIG_PAGECACHE]..
129d0 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72  ** There are thr
129e0 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 6e  ee arguments: An
129f0 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20   8-byte aligned 
12a00 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d  pointer to the m
12a10 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75  emory,.** the nu
12a20 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
12a30 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66   the memory buff
12a40 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69  er, and the mini
12a50 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
12a60 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ize..** ^If the 
12a70 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74  first pointer (t
12a80 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  he memory pointe
12a90 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  r) is NULL, then
12aa0 20 53 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a   SQLite reverts.
12ab0 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20  ** to using its 
12ac0 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61  default memory a
12ad0 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79  llocator (the sy
12ae0 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d  stem malloc() im
12af0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a  plementation),.*
12b00 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72  * undoing any pr
12b10 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ior invocation o
12b20 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  f [SQLITE_CONFIG
12b30 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74  _MALLOC].  ^If t
12b40 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69  he.** memory poi
12b50 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  nter is not NULL
12b60 20 61 6e 64 20 65 69 74 68 65 72 20 5b 53 51 4c   and either [SQL
12b70 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59  ITE_ENABLE_MEMSY
12b80 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  S3] or.** [SQLIT
12b90 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35  E_ENABLE_MEMSYS5
12ba0 5d 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74  ] are defined, t
12bb0 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74  hen the alternat
12bc0 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ive memory.** al
12bd0 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67  locator is engag
12be0 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c  ed to handle all
12bf0 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f   of SQLites memo
12c00 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
12c10 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  eds..** The firs
12c20 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d  t pointer (the m
12c30 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d  emory pointer) m
12c40 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74  ust be aligned t
12c50 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62  o an 8-byte.** b
12c60 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65  oundary or subse
12c70 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f  quent behavior o
12c80 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65  f SQLite will be
12c90 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54   undefined..** T
12ca0 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
12cb0 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61  ation size is ca
12cc0 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e 20 52  pped at 2**12. R
12cd0 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73  easonable values
12ce0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69  .** for the mini
12cf0 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
12d00 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74 68 72  ize are 2**5 thr
12d10 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a  ough 2**8.</dd>.
12d20 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
12d30 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64  ONFIG_MUTEX]] <d
12d40 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
12d50 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  MUTEX</dt>.** <d
12d60 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
12d70 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
12d80 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
12d90 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
12da0 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
12db0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
12dc0 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
12dd0 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67  ucture.  The arg
12de0 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a  ument specifies.
12df0 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c  ** alternative l
12e00 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72  ow-level mutex r
12e10 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73  outines to be us
12e20 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74  ed in place.** t
12e30 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  he mutex routine
12e40 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  s built into SQL
12e50 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20  ite.)^  ^SQLite 
12e60 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
12e70 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 6f  the.** content o
12e80 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
12e90 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
12ea0 72 75 63 74 75 72 65 20 62 65 66 6f 72 65 20 74  ructure before t
12eb0 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  he call to.** [s
12ec0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
12ed0 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51   returns. ^If SQ
12ee0 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
12ef0 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
12f00 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
12f10 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
12f20 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
12f30 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
12f40 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75  ** the entire mu
12f50 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d  texing subsystem
12f60 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
12f70 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68   the build and h
12f80 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ence calls to.**
12f90 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
12fa0 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c  ()] with the SQL
12fb0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
12fc0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
12fd0 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65  ption will.** re
12fe0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
12ff0 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  OR].</dd>.**.** 
13000 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
13010 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53  GETMUTEX]] <dt>S
13020 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
13030 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  MUTEX</dt>.** <d
13040 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
13050 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
13060 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
13070 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
13080 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
13090 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
130a0 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
130b0 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20  ucture.  The.** 
130c0 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
130d0 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63  ethods].** struc
130e0 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77  ture is filled w
130f0 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c  ith the currentl
13100 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20  y defined mutex 
13110 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54  routines.)^.** T
13120 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62  his option can b
13130 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f  e used to overlo
13140 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  ad the default m
13150 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  utex allocation.
13160 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68  ** routines with
13170 20 61 20 77 72 61 70 70 65 72 20 75 73 65 64 20   a wrapper used 
13180 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75  to track mutex u
13190 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d  sage for perform
131a0 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e  ance.** profilin
131b0 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f  g or testing, fo
131c0 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66  r example.   ^If
131d0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
131e0 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
131f0 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
13200 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
13210 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
13220 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
13230 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65  en.** the entire
13240 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73   mutexing subsys
13250 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66  tem is omitted f
13260 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e  rom the build an
13270 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f  d hence calls to
13280 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
13290 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20  fig()] with the 
132a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
132b0 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61  TMUTEX configura
132c0 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c  tion option will
132d0 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
132e0 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a  TE_ERROR].</dd>.
132f0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
13300 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
13310 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
13320 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64  FIG_LOOKASIDE</d
13330 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
13340 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  s option takes t
13350 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  wo arguments tha
13360 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  t determine the 
13370 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72  default.** memor
13380 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72  y allocation for
13390 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d   the lookaside m
133a0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
133b0 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61  on each.** [data
133c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
133d0 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 72 67  .  The first arg
133e0 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20  ument is the.** 
133f0 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f  size of each loo
13400 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c  kaside buffer sl
13410 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  ot and the secon
13420 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  d is the number 
13430 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f  of.** slots allo
13440 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61  cated to each da
13450 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
13460 6e 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f 70 74  n.)^  ^(This opt
13470 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
13480 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c  <i>default</i> l
13490 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54  ookaside size. T
134a0 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  he [SQLITE_DBCON
134b0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a  FIG_LOOKASIDE].*
134c0 2a 20 76 65 72 62 20 74 6f 20 5b 73 71 6c 69 74  * verb to [sqlit
134d0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
134e0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63  can be used to c
134f0 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73  hange the lookas
13500 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  ide.** configura
13510 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75  tion on individu
13520 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29  al connections.)
13530 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ^ </dd>.**.** [[
13540 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
13550 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49  ACHE2]] <dt>SQLI
13560 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
13570 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  2</dt>.** <dd> ^
13580 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
13590 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
135a0 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
135b0 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e  pointer to.** an
135c0 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
135d0 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63  _methods2] objec
135e0 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20  t.  This object 
135f0 73 70 65 63 69 66 69 65 73 20 74 68 65 20 69 6e  specifies the in
13600 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20  terface.** to a 
13610 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68  custom page cach
13620 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
13630 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b  .)^  ^SQLite mak
13640 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
13650 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20 75  .** object and u
13660 73 65 73 20 69 74 20 66 6f 72 20 70 61 67 65 20  ses it for page 
13670 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  cache memory all
13680 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a  ocations.</dd>.*
13690 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
136a0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 5d  NFIG_GETPCACHE2]
136b0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
136c0 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 3c 2f  FIG_GETPCACHE2</
136d0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
136e0 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
136f0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
13700 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
13710 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73  nter to an.** [s
13720 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
13730 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20  thods2] object. 
13740 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f   SQLite copies o
13750 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  f the current.**
13760 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c   page cache impl
13770 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20  ementation into 
13780 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c  that object.)^ <
13790 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
137a0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d  ITE_CONFIG_LOG]]
137b0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
137c0 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c  IG_LOG</dt>.** <
137d0 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45 5f 43  dd> The SQLITE_C
137e0 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e  ONFIG_LOG option
137f0 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66   is used to conf
13800 69 67 75 72 65 20 74 68 65 20 53 51 4c 69 74 65  igure the SQLite
13810 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 72 6f  .** global [erro
13820 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65  r log]..** (^The
13830 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
13840 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  OG option takes 
13850 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61  two arguments: a
13860 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a   pointer to a.**
13870 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61   function with a
13880 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20   call signature 
13890 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  of void(*)(void*
138a0 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a  ,int,const char*
138b0 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69  ), .** and a poi
138c0 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49  nter to void. ^I
138d0 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70  f the function p
138e0 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55  ointer is not NU
138f0 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76  LL, it is.** inv
13900 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  oked by [sqlite3
13910 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65  _log()] to proce
13920 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20  ss each logging 
13930 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a  event.  ^If the.
13940 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e  ** function poin
13950 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ter is NULL, the
13960 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d   [sqlite3_log()]
13970 20 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d   interface becom
13980 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e  es a no-op..** ^
13990 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72  The void pointer
139a0 20 74 68 61 74 20 69 73 20 74 68 65 20 73 65 63   that is the sec
139b0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
139c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
139d0 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74  G is.** passed t
139e0 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69  hrough as the fi
139f0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
13a00 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
13a10 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a  -defined logger.
13a20 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e  ** function when
13a30 65 76 65 72 20 74 68 61 74 20 66 75 6e 63 74 69  ever that functi
13a40 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20  on is invoked.  
13a50 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
13a60 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20  meter to.** the 
13a70 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20  logger function 
13a80 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
13a90 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
13aa0 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f   to the correspo
13ab0 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  nding.** [sqlite
13ac0 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e  3_log()] call an
13ad0 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f  d is intended to
13ae0 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f   be a [result co
13af0 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78  de] or an.** [ex
13b00 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
13b10 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64  de].  ^The third
13b20 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65   parameter passe
13b30 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20  d to the logger 
13b40 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67  is.** log messag
13b50 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69  e after formatti
13b60 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f  ng via [sqlite3_
13b70 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20  snprintf()]..** 
13b80 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69  The SQLite loggi
13b90 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ng interface is 
13ba0 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74  not reentrant; t
13bb0 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69  he logger functi
13bc0 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62  on.** supplied b
13bd0 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
13be0 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b  n must not invok
13bf0 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74  e any SQLite int
13c00 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20  erface..** In a 
13c10 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61  multi-threaded a
13c20 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20  pplication, the 
13c30 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
13c40 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75  ned logger.** fu
13c50 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74  nction must be t
13c60 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e  hreadsafe. </dd>
13c70 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
13c80 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74  CONFIG_URI]] <dt
13c90 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55  >SQLITE_CONFIG_U
13ca0 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 69 73  RI.** <dd>^(This
13cb0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
13cc0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
13cd0 6f 66 20 74 79 70 65 20 69 6e 74 2e 20 49 66 20  of type int. If 
13ce0 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 0a 2a  non-zero, then.*
13cf0 2a 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  * URI handling i
13d00 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c  s globally enabl
13d10 65 64 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d  ed. If the param
13d20 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 20 74 68  eter is zero, th
13d30 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 0a  en URI handling.
13d40 2a 2a 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64  ** is globally d
13d50 69 73 61 62 6c 65 64 2e 29 5e 20 5e 49 66 20 55  isabled.)^ ^If U
13d60 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
13d70 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2c  lobally enabled,
13d80 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a   all filenames.*
13d90 2a 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c  * passed to [sql
13da0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
13db0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
13dc0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
13dd0 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63  16()] or.** spec
13de0 69 66 69 65 64 20 61 73 20 70 61 72 74 20 6f 66  ified as part of
13df0 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e   [ATTACH] comman
13e00 64 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  ds are interpret
13e10 65 64 20 61 73 20 55 52 49 73 2c 20 72 65 67 61  ed as URIs, rega
13e20 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65  rdless.** of whe
13e30 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
13e40 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
13e50 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68  ] flag is set wh
13e60 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  en the database.
13e70 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  ** connection is
13e80 20 6f 70 65 6e 65 64 2e 20 5e 49 66 20 69 74 20   opened. ^If it 
13e90 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61  is globally disa
13ea0 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20  bled, filenames 
13eb0 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65  are.** only inte
13ec0 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73 20  rpreted as URIs 
13ed0 69 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50  if the SQLITE_OP
13ee0 45 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 20 73  EN_URI flag is s
13ef0 65 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64  et when the.** d
13f00 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
13f10 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 28  on is opened. ^(
13f20 42 79 20 64 65 66 61 75 6c 74 2c 20 55 52 49 20  By default, URI 
13f30 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
13f40 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64  ally.** disabled
13f50 2e 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61  . The default va
13f60 6c 75 65 20 6d 61 79 20 62 65 20 63 68 61 6e 67  lue may be chang
13f70 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20  ed by compiling 
13f80 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
13f90 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d  ITE_USE_URI] sym
13fa0 62 6f 6c 20 64 65 66 69 6e 65 64 2e 29 5e 0a 2a  bol defined.)^.*
13fb0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
13fc0 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  NFIG_COVERING_IN
13fd0 44 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e 53  DEX_SCAN]] <dt>S
13fe0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56  QLITE_CONFIG_COV
13ff0 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
14000 0a 2a 2a 20 3c 64 64 3e 5e 54 68 69 73 20 6f 70  .** <dd>^This op
14010 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
14020 67 6c 65 20 69 6e 74 65 67 65 72 20 61 72 67 75  gle integer argu
14030 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 69 6e  ment which is in
14040 74 65 72 70 72 65 74 65 64 20 61 73 0a 2a 2a 20  terpreted as.** 
14050 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72 64  a boolean in ord
14060 65 72 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  er to enable or 
14070 64 69 73 61 62 6c 65 20 74 68 65 20 75 73 65 20  disable the use 
14080 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69  of covering indi
14090 63 65 73 20 66 6f 72 0a 2a 2a 20 66 75 6c 6c 20  ces for.** full 
140a0 74 61 62 6c 65 20 73 63 61 6e 73 20 69 6e 20 74  table scans in t
140b0 68 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a  he query optimiz
140c0 65 72 2e 20 20 5e 54 68 65 20 64 65 66 61 75 6c  er.  ^The defaul
140d0 74 20 73 65 74 74 69 6e 67 20 69 73 20 64 65 74  t setting is det
140e0 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68  ermined.** by th
140f0 65 20 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f  e [SQLITE_ALLOW_
14100 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
14110 43 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  CAN] compile-tim
14120 65 20 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20  e option, or is 
14130 22 6f 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74 20  "on".** if that 
14140 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
14150 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a  ion is omitted..
14160 2a 2a 20 54 68 65 20 61 62 69 6c 69 74 79 20 74  ** The ability t
14170 6f 20 64 69 73 61 62 6c 65 20 74 68 65 20 75 73  o disable the us
14180 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e  e of covering in
14190 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74  dices for full t
141a0 61 62 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73  able scans.** is
141b0 20 62 65 63 61 75 73 65 20 73 6f 6d 65 20 69 6e   because some in
141c0 63 6f 72 72 65 63 74 6c 79 20 63 6f 64 65 64 20  correctly coded 
141d0 6c 65 67 61 63 79 20 61 70 70 6c 69 63 61 74 69  legacy applicati
141e0 6f 6e 73 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e  ons might malfun
141f0 63 74 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74 68  ction.** when th
14200 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69  e optimization i
14210 73 20 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76  s enabled.  Prov
14220 69 64 69 6e 67 20 74 68 65 20 61 62 69 6c 69 74  iding the abilit
14230 79 20 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20  y to.** disable 
14240 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  the optimization
14250 20 61 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65   allows the olde
14260 72 2c 20 62 75 67 67 79 20 61 70 70 6c 69 63 61  r, buggy applica
14270 74 69 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72  tion code to wor
14280 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63 68 61  k.** without cha
14290 6e 67 65 20 65 76 65 6e 20 77 69 74 68 20 6e 65  nge even with ne
142a0 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  wer versions of 
142b0 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  SQLite..**.** [[
142c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
142d0 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f  ACHE]] [[SQLITE_
142e0 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
142f0 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
14300 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61  _CONFIG_PCACHE a
14310 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  nd SQLITE_CONFIG
14320 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64  _GETPCACHE.** <d
14330 64 3e 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 73  d> These options
14340 20 61 72 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e   are obsolete an
14350 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  d should not be 
14360 75 73 65 64 20 62 79 20 6e 65 77 20 63 6f 64 65  used by new code
14370 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65 20 72 65  ..** They are re
14380 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77  tained for backw
14390 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
143a0 74 79 20 62 75 74 20 61 72 65 20 6e 6f 77 20 6e  ty but are now n
143b0 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a  o-ops..** </dd>.
143c0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
143d0 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a  ONFIG_SQLLOG]].*
143e0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
143f0 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64  FIG_SQLLOG.** <d
14400 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73  d>This option is
14410 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
14420 69 66 20 73 71 6c 69 74 65 20 69 73 20 63 6f 6d  if sqlite is com
14430 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
14440 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
14450 5f 53 51 4c 4c 4f 47 5d 20 70 72 65 2d 70 72 6f  _SQLLOG] pre-pro
14460 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 64 65 66  cessor macro def
14470 69 6e 65 64 2e 20 54 68 65 20 66 69 72 73 74 20  ined. The first 
14480 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a  argument should.
14490 2a 2a 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  ** be a pointer 
144a0 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66  to a function of
144b0 20 74 79 70 65 20 76 6f 69 64 28 2a 29 28 76 6f   type void(*)(vo
144c0 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e  id*,sqlite3*,con
144d0 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a  st char*, int)..
144e0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 73 68  ** The second sh
144f0 6f 75 6c 64 20 62 65 20 6f 66 20 74 79 70 65 20  ould be of type 
14500 28 76 6f 69 64 2a 29 2e 20 54 68 65 20 63 61 6c  (void*). The cal
14510 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
14520 20 62 79 20 74 68 65 20 6c 69 62 72 61 72 79 0a   by the library.
14530 2a 2a 20 69 6e 20 74 68 72 65 65 20 73 65 70 61  ** in three sepa
14540 72 61 74 65 20 63 69 72 63 75 6d 73 74 61 6e 63  rate circumstanc
14550 65 73 2c 20 69 64 65 6e 74 69 66 69 65 64 20 62  es, identified b
14560 79 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73  y the value pass
14570 65 64 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75  ed as the.** fou
14580 72 74 68 20 70 61 72 61 6d 65 74 65 72 2e 20 49  rth parameter. I
14590 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
145a0 61 6d 65 74 65 72 20 69 73 20 30 2c 20 74 68 65  ameter is 0, the
145b0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
145c0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73  onnection.** pas
145d0 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
145e0 64 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 6a  d argument has j
145f0 75 73 74 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e  ust been opened.
14600 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   The third argum
14610 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f  ent.** points to
14620 20 61 20 62 75 66 66 65 72 20 63 6f 6e 74 61 69   a buffer contai
14630 6e 69 6e 67 20 74 68 65 20 6e 61 6d 65 20 6f 66  ning the name of
14640 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61   the main databa
14650 73 65 20 66 69 6c 65 2e 20 49 66 20 74 68 65 0a  se file. If the.
14660 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  ** fourth parame
14670 74 65 72 20 69 73 20 31 2c 20 74 68 65 6e 20 74  ter is 1, then t
14680 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
14690 20 74 68 61 74 20 74 68 65 20 74 68 69 72 64 20   that the third 
146a0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69  parameter.** poi
146b0 6e 74 73 20 74 6f 20 68 61 73 20 6a 75 73 74 20  nts to has just 
146c0 62 65 65 6e 20 65 78 65 63 75 74 65 64 2e 20 4f  been executed. O
146d0 72 2c 20 69 66 20 74 68 65 20 66 6f 75 72 74 68  r, if the fourth
146e0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 32 2c   parameter is 2,
146f0 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e   then.** the con
14700 6e 65 63 74 69 6f 6e 20 62 65 69 6e 67 20 70 61  nection being pa
14710 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  ssed as the seco
14720 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
14730 62 65 69 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68  being closed. Th
14740 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d  e.** third param
14750 65 74 65 72 20 69 73 20 70 61 73 73 65 64 20 4e  eter is passed N
14760 55 4c 4c 20 49 6e 20 74 68 69 73 20 63 61 73 65  ULL In this case
14770 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 6f 66  .  An example of
14780 20 75 73 69 6e 67 20 74 68 69 73 0a 2a 2a 20 63   using this.** c
14790 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
147a0 69 6f 6e 20 63 61 6e 20 62 65 20 73 65 65 6e 20  ion can be seen 
147b0 69 6e 20 74 68 65 20 22 74 65 73 74 5f 73 71 6c  in the "test_sql
147c0 6c 6f 67 2e 63 22 20 73 6f 75 72 63 65 20 66 69  log.c" source fi
147d0 6c 65 20 69 6e 0a 2a 2a 20 74 68 65 20 63 61 6e  le in.** the can
147e0 6f 6e 69 63 61 6c 20 53 51 4c 69 74 65 20 73 6f  onical SQLite so
147f0 75 72 63 65 20 74 72 65 65 2e 3c 2f 64 64 3e 0a  urce tree.</dd>.
14800 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
14810 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d  ONFIG_MMAP_SIZE]
14820 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
14830 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45  CONFIG_MMAP_SIZE
14840 0a 2a 2a 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f  .** <dd>^SQLITE_
14850 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45  CONFIG_MMAP_SIZE
14860 20 74 61 6b 65 73 20 74 77 6f 20 36 34 2d 62 69   takes two 64-bi
14870 74 20 69 6e 74 65 67 65 72 20 28 73 71 6c 69 74  t integer (sqlit
14880 65 33 5f 69 6e 74 36 34 29 20 76 61 6c 75 65 73  e3_int64) values
14890 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 74 68 65  .** that are the
148a0 20 64 65 66 61 75 6c 74 20 6d 6d 61 70 20 73 69   default mmap si
148b0 7a 65 20 6c 69 6d 69 74 20 28 74 68 65 20 64 65  ze limit (the de
148c0 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 66 6f  fault setting fo
148d0 72 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 6d 6d 61  r.** [PRAGMA mma
148e0 70 5f 73 69 7a 65 5d 29 20 61 6e 64 20 74 68 65  p_size]) and the
148f0 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64   maximum allowed
14900 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74   mmap size limit
14910 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  ..** ^The defaul
14920 74 20 73 65 74 74 69 6e 67 20 63 61 6e 20 62 65  t setting can be
14930 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 65   overridden by e
14940 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
14950 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a  nection using.**
14960 20 65 69 74 68 65 72 20 74 68 65 20 5b 50 52 41   either the [PRA
14970 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63  GMA mmap_size] c
14980 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62 79 20 75 73  ommand, or by us
14990 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ing the.** [SQLI
149a0 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49  TE_FCNTL_MMAP_SI
149b0 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  ZE] file control
149c0 2e 20 20 5e 28 54 68 65 20 6d 61 78 69 6d 75 6d  .  ^(The maximum
149d0 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69   allowed mmap si
149e0 7a 65 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20  ze.** cannot be 
149f0 63 68 61 6e 67 65 64 20 61 74 20 72 75 6e 2d 74  changed at run-t
14a00 69 6d 65 2e 20 20 4e 6f 72 20 6d 61 79 20 74 68  ime.  Nor may th
14a10 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65  e maximum allowe
14a20 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 65  d mmap size.** e
14a30 78 63 65 65 64 20 74 68 65 20 63 6f 6d 70 69 6c  xceed the compil
14a40 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d  e-time maximum m
14a50 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62 79 20  map size set by 
14a60 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d  the.** [SQLITE_M
14a70 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f  AX_MMAP_SIZE] co
14a80 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
14a90 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68  n.)^.** ^If eith
14aa0 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  er argument to t
14ab0 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65  his option is ne
14ac0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61  gative, then tha
14ad0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a  t argument is.**
14ae0 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20   changed to its 
14af0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66  compile-time def
14b00 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  ault..**.** [[SQ
14b10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33  LITE_CONFIG_WIN3
14b20 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20  2_HEAPSIZE]].** 
14b30 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
14b40 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
14b50 0a 2a 2a 20 3c 64 64 3e 5e 54 68 69 73 20 6f 70  .** <dd>^This op
14b60 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61  tion is only ava
14b70 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65  ilable if SQLite
14b80 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72   is compiled for
14b90 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 77 69 74 68   Windows.** with
14ba0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e   the [SQLITE_WIN
14bb0 33 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70  32_MALLOC] pre-p
14bc0 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 64  rocessor macro d
14bd0 65 66 69 6e 65 64 2e 0a 2a 2a 20 53 51 4c 49 54  efined..** SQLIT
14be0 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48  E_CONFIG_WIN32_H
14bf0 45 41 50 53 49 5a 45 20 74 61 6b 65 73 20 61 20  EAPSIZE takes a 
14c00 33 32 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20  32-bit unsigned 
14c10 69 6e 74 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a  integer value.**
14c20 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20   that specifies 
14c30 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65  the maximum size
14c40 20 6f 66 20 74 68 65 20 63 72 65 61 74 65 64 20   of the created 
14c50 68 65 61 70 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  heap..** </dl>.*
14c60 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
14c70 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
14c80 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20  READ  1  /* nil 
14c90 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
14ca0 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
14cb0 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c  READ   2  /* nil
14cc0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
14cd0 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
14ce0 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69  IZED    3  /* ni
14cf0 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
14d00 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
14d10 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73  C        4  /* s
14d20 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
14d30 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
14d40 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
14d50 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a  MALLOC     5  /*
14d60 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
14d70 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
14d80 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
14d90 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20  CRATCH       6  
14da0 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a  /* void*, int sz
14db0 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69  , int N */.#defi
14dc0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
14dd0 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37  _PAGECACHE     7
14de0 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
14df0 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65  sz, int N */.#de
14e00 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
14e10 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20  IG_HEAP         
14e20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   8  /* void*, in
14e30 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e  t nByte, int min
14e40 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
14e50 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
14e60 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f  TUS     9  /* bo
14e70 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  olean */.#define
14e80 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
14e90 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20  UTEX        10  
14ea0 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  /* sqlite3_mutex
14eb0 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
14ec0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
14ed0 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20  IG_GETMUTEX     
14ee0 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d  11  /* sqlite3_m
14ef0 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  utex_methods* */
14f00 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53  ./* previously S
14f10 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55  QLITE_CONFIG_CHU
14f20 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68  NKALLOC 12 which
14f30 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20   is now unused. 
14f40 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  */ .#define SQLI
14f50 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
14f60 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e  IDE    13  /* in
14f70 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  t int */.#define
14f80 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
14f90 43 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20  CACHE       14  
14fa0 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66  /* no-op */.#def
14fb0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
14fc0 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31  G_GETPCACHE    1
14fd0 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23  5  /* no-op */.#
14fe0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
14ff0 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20  NFIG_LOG        
15000 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20    16  /* xFunc, 
15010 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  void* */.#define
15020 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55   SQLITE_CONFIG_U
15030 52 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20  RI          17  
15040 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  /* int */.#defin
15050 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15060 50 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20  PCACHE2      18 
15070 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63   /* sqlite3_pcac
15080 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a  he_methods2* */.
15090 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
150a0 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
150b0 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65     19  /* sqlite
150c0 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
150d0 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  2* */.#define SQ
150e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
150f0 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20  RING_INDEX_SCAN 
15100 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64  20  /* int */.#d
15110 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
15120 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20  FIG_SQLLOG      
15130 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c   21  /* xSqllog,
15140 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e   void* */.#defin
15150 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15160 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20  MMAP_SIZE    22 
15170 20 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36   /* sqlite3_int6
15180 34 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  4, sqlite3_int64
15190 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
151a0 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
151b0 48 45 41 50 53 49 5a 45 20 20 20 20 20 20 32 33  HEAPSIZE      23
151c0 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a    /* int nByte *
151d0 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
151e0 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  F: Database Conn
151f0 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61  ection Configura
15200 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a  tion Options.**.
15210 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
15220 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c  ts are the avail
15230 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  able integer con
15240 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
15250 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62  ns that.** can b
15260 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
15270 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
15280 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
15290 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  db_config()] int
152a0 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65  erface..**.** Ne
152b0 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  w configuration 
152c0 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61  options may be a
152d0 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
152e0 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
152f0 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63  e..** Existing c
15300 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
15310 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69  ions might be di
15320 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70  scontinued.  App
15330 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f  lications.** sho
15340 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65  uld check the re
15350 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b  turn code from [
15360 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
15370 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72  g()] to make sur
15380 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61  e that.** the ca
15390 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65  ll worked.  ^The
153a0 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
153b0 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
153c0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a   will return a.*
153d0 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  * non-zero [erro
153e0 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73  r code] if a dis
153f0 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73  continued or uns
15400 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75  upported configu
15410 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a  ration option.**
15420 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
15430 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53  ** <dl>.** <dt>S
15440 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
15450 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a  OOKASIDE</dt>.**
15460 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
15470 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 61  on takes three a
15480 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
15490 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69  nts that determi
154a0 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b  ne the .** [look
154b0 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  aside memory all
154c0 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72  ocator] configur
154d0 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64  ation for the [d
154e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
154f0 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72  on]..** ^The fir
15500 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65  st argument (the
15510 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
15520 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f   to [sqlite3_db_
15530 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a  config()] is a.*
15540 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d  * pointer to a m
15550 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20  emory buffer to 
15560 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64  use for lookasid
15570 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68  e memory..** ^Th
15580 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
15590 20 61 66 74 65 72 20 74 68 65 20 53 51 4c 49 54   after the SQLIT
155a0 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
155b0 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79  SIDE verb.** may
155c0 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63   be NULL in whic
155d0 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69  h case SQLite wi
155e0 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a  ll allocate the.
155f0 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ** lookaside buf
15600 66 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67  fer itself using
15610 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
15620 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ()]. ^The second
15630 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
15640 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68  .** size of each
15650 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
15660 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68  r slot.  ^The th
15670 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
15680 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
15690 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a   slots.  The siz
156a0 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20  e of the buffer 
156b0 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
156c0 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72  ument must be gr
156d0 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72  eater than.** or
156e0 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72   equal to the pr
156f0 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63  oduct of the sec
15700 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72  ond and third ar
15710 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75  guments.  The bu
15720 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20  ffer.** must be 
15730 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
15740 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20  byte boundary.  
15750 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61  ^If the second a
15760 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51  rgument to.** SQ
15770 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
15780 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61  OKASIDE is not a
15790 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20   multiple of 8, 
157a0 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79  it is internally
157b0 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e  .** rounded down
157c0 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61   to the next sma
157d0 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66  ller multiple of
157e0 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61   8.  ^(The looka
157f0 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63  side memory.** c
15800 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72  onfiguration for
15810 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
15820 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20  ection can only 
15830 62 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20  be changed when 
15840 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  that.** connecti
15850 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e  on is not curren
15860 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73  tly using lookas
15870 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69  ide memory, or i
15880 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a  n other words.**
15890 20 77 68 65 6e 20 74 68 65 20 22 63 75 72 72 65   when the "curre
158a0 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e  nt value" return
158b0 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
158c0 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b  3_db_status](D,[
158d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
158e0 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73  OKASIDE],...) is
158f0 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74   zero..** Any at
15900 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20  tempt to change 
15910 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  the lookaside me
15920 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69  mory configurati
15930 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64  on when lookasid
15940 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69  e.** memory is i
15950 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74 68 65  n use leaves the
15960 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75   configuration u
15970 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74  nchanged and ret
15980 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  urns .** [SQLITE
15990 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a  _BUSY].)^</dd>.*
159a0 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
159b0 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
159c0 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  FKEY</dt>.** <dd
159d0 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69  > ^This option i
159e0 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65  s used to enable
159f0 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20   or disable the 
15a00 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a  enforcement of.*
15a10 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63  * [foreign key c
15a20 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68  onstraints].  Th
15a30 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77  ere should be tw
15a40 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  o additional arg
15a50 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66  uments..** The f
15a60 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
15a70 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
15a80 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  h is 0 to disabl
15a90 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
15aa0 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f  ,.** positive to
15ab0 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72   enable FK enfor
15ac0 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69  cement or negati
15ad0 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65  ve to leave FK e
15ae0 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e  nforcement.** un
15af0 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65  changed.  The se
15b00 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
15b10 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
15b20 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77  n integer into w
15b30 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74  hich.** is writt
15b40 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64  en 0 or 1 to ind
15b50 69 63 61 74 65 20 77 68 65 74 68 65 72 20 46 4b  icate whether FK
15b60 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20   enforcement is 
15b70 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c  off or on.** fol
15b80 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c  lowing this call
15b90 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
15ba0 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61  rameter may be a
15bb0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69   NULL pointer, i
15bc0 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20  n.** which case 
15bd0 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  the FK enforceme
15be0 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f  nt setting is no
15bf0 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e  t reported back.
15c00 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74   </dd>.**.** <dt
15c10 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
15c20 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c  _ENABLE_TRIGGER<
15c30 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
15c40 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  is option is use
15c50 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64  d to enable or d
15c60 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54  isable [CREATE T
15c70 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72  RIGGER | trigger
15c80 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f  s]..** There sho
15c90 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74  uld be two addit
15ca0 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e  ional arguments.
15cb0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
15cc0 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74  gument is an int
15cd0 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20  eger which is 0 
15ce0 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67 67  to disable trigg
15cf0 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65  ers,.** positive
15d00 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67   to enable trigg
15d10 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ers or negative 
15d20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74  to leave the set
15d30 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a  ting unchanged..
15d40 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  ** The second pa
15d50 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
15d60 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
15d70 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
15d80 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
15d90 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
15da0 68 65 74 68 65 72 20 74 72 69 67 67 65 72 73 20  hether triggers 
15db0 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20  are disabled or 
15dc0 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f  enabled.** follo
15dd0 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20  wing this call. 
15de0 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
15df0 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e  meter may be a N
15e00 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a  ULL pointer, in.
15e10 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68  ** which case th
15e20 65 20 74 72 69 67 67 65 72 20 73 65 74 74 69 6e  e trigger settin
15e30 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65  g is not reporte
15e40 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a  d back. </dd>.**
15e50 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
15e60 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
15e70 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20  NFIG_LOOKASIDE  
15e80 20 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f       1001  /* vo
15e90 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23  id* int int */.#
15ea0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
15eb0 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b  CONFIG_ENABLE_FK
15ec0 45 59 20 20 20 20 20 31 30 30 32 20 20 2f 2a 20  EY     1002  /* 
15ed0 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66  int int* */.#def
15ee0 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
15ef0 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47  FIG_ENABLE_TRIGG
15f00 45 52 20 20 31 30 30 33 20 20 2f 2a 20 69 6e 74  ER  1003  /* int
15f10 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a   int* */.../*.**
15f20 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c   CAPI3REF: Enabl
15f30 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74  e Or Disable Ext
15f40 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64  ended Result Cod
15f50 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  es.**.** ^The sq
15f60 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
15f70 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f  esult_codes() ro
15f80 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72  utine enables or
15f90 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a   disables the.**
15fa0 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
15fb0 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65  t codes] feature
15fc0 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65   of SQLite. ^The
15fd0 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
15fe0 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69  .** codes are di
15ff0 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
16000 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c  t for historical
16010 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
16020 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
16030 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
16040 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69  odes(sqlite3*, i
16050 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a  nt onoff);../*.*
16060 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74  * CAPI3REF: Last
16070 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a   Insert Rowid.**
16080 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20  .** ^Each entry 
16090 69 6e 20 6d 6f 73 74 20 53 51 4c 69 74 65 20 74  in most SQLite t
160a0 61 62 6c 65 73 20 28 65 78 63 65 70 74 20 66 6f  ables (except fo
160b0 72 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 44  r [WITHOUT ROWID
160c0 5d 20 74 61 62 6c 65 73 29 0a 2a 2a 20 68 61 73  ] tables).** has
160d0 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74   a unique 64-bit
160e0 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67   signed.** integ
160f0 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68  er key called th
16100 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 69  e [ROWID | "rowi
16110 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64 20  d"]. ^The rowid 
16120 69 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61  is always availa
16130 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64  ble.** as an und
16140 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e  eclared column n
16150 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c  amed ROWID, OID,
16160 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c   or _ROWID_ as l
16170 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20  ong as those.** 
16180 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c  names are not al
16190 73 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c 69  so used by expli
161a0 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63  citly declared c
161b0 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74  olumns. ^If.** t
161c0 68 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 63  he table has a c
161d0 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49  olumn of type [I
161e0 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b  NTEGER PRIMARY K
161f0 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20 63 6f  EY] then that co
16200 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68  lumn.** is anoth
16210 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65  er alias for the
16220 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54   rowid..**.** ^T
16230 68 65 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  he sqlite3_last_
16240 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20  insert_rowid(D) 
16250 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
16260 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66  s the [rowid] of
16270 20 74 68 65 20 0a 2a 2a 20 6d 6f 73 74 20 72 65   the .** most re
16280 63 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c 20  cent successful 
16290 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 61 20  [INSERT] into a 
162a0 72 6f 77 69 64 20 74 61 62 6c 65 20 6f 72 20 5b  rowid table or [
162b0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a  virtual table].*
162c0 2a 20 6f 6e 20 64 61 74 61 62 61 73 65 20 63 6f  * on database co
162d0 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 20 5e  nnection D..** ^
162e0 49 6e 73 65 72 74 73 20 69 6e 74 6f 20 5b 57 49  Inserts into [WI
162f0 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62  THOUT ROWID] tab
16300 6c 65 73 20 61 72 65 20 6e 6f 74 20 72 65 63 6f  les are not reco
16310 72 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20  rded..** ^If no 
16320 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45  successful [INSE
16330 52 54 5d 73 20 69 6e 74 6f 20 72 6f 77 69 64 20  RT]s into rowid 
16340 74 61 62 6c 65 73 0a 2a 2a 20 68 61 76 65 20 65  tables.** have e
16350 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20  ver occurred on 
16360 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
16370 6e 65 63 74 69 6f 6e 20 44 2c 20 0a 2a 2a 20 74  nection D, .** t
16380 68 65 6e 20 73 71 6c 69 74 65 33 5f 6c 61 73 74  hen sqlite3_last
16390 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29  _insert_rowid(D)
163a0 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a   returns zero..*
163b0 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e  *.** ^(If an [IN
163c0 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74  SERT] occurs wit
163d0 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 6f 72  hin a trigger or
163e0 20 77 69 74 68 69 6e 20 61 20 5b 76 69 72 74 75   within a [virtu
163f0 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65 74  al table].** met
16400 68 6f 64 2c 20 74 68 65 6e 20 74 68 69 73 20 72  hod, then this r
16410 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 65 74 75  outine will retu
16420 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f  rn the [rowid] o
16430 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a  f the inserted.*
16440 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73  * row as long as
16450 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20   the trigger or 
16460 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65  virtual table me
16470 74 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e 67 2e  thod is running.
16480 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65  .** But once the
16490 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74   trigger or virt
164a0 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64  ual table method
164b0 20 65 6e 64 73 2c 20 74 68 65 20 76 61 6c 75 65   ends, the value
164c0 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79   returned .** by
164d0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
164e0 76 65 72 74 73 20 74 6f 20 77 68 61 74 20 69 74  verts to what it
164f0 20 77 61 73 20 62 65 66 6f 72 65 20 74 68 65 20   was before the 
16500 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75  trigger or virtu
16510 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65 74 68  al.** table meth
16520 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a  od began.)^.**.*
16530 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74  * ^An [INSERT] t
16540 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f  hat fails due to
16550 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69   a constraint vi
16560 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61  olation is not a
16570 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b  .** successful [
16580 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73  INSERT] and does
16590 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
165a0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
165b0 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  y this.** routin
165c0 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54  e.  ^Thus INSERT
165d0 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54   OR FAIL, INSERT
165e0 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45   OR IGNORE, INSE
165f0 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a  RT OR ROLLBACK,.
16600 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52  ** and INSERT OR
16610 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63   ABORT make no c
16620 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65  hanges to the re
16630 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
16640 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68  is.** routine wh
16650 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69  en their inserti
16660 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65  on fails.  ^(Whe
16670 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c  n INSERT OR REPL
16680 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72  ACE.** encounter
16690 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  s a constraint v
166a0 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65  iolation, it doe
166b0 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65  s not fail.  The
166c0 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69  .** INSERT conti
166d0 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69  nues to completi
166e0 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e  on after deletin
166f0 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 73  g rows that caus
16700 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72  ed.** the constr
16710 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20  aint problem so 
16720 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43  INSERT OR REPLAC
16730 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68  E will always ch
16740 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75  ange.** the retu
16750 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  rn value of this
16760 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a   interface.)^.**
16770 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72  .** ^For the pur
16780 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f  poses of this ro
16790 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52  utine, an [INSER
167a0 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  T] is considered
167b0 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73   to.** be succes
167c0 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20  sful even if it 
167d0 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20  is subsequently 
167e0 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a  rolled back..**.
167f0 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
16800 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 20 74   is accessible t
16810 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  o SQL statements
16820 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73   via the.** [las
16830 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
16840 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
16850 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72  **.** If a separ
16860 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66 6f  ate thread perfo
16870 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52  rms a new [INSER
16880 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a  T] on the same.*
16890 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
168a0 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20  ction while the 
168b0 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
168c0 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a  sert_rowid()].**
168d0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
168e0 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68  ning and thus ch
168f0 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69  anges the last i
16900 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a  nsert [rowid],.*
16910 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  * then the value
16920 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
16930 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
16940 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a  t_rowid()] is.**
16950 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
16960 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75  nd might not equ
16970 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c  al either the ol
16980 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20  d or the new.** 
16990 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77  last insert [row
169a0 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  id]..*/.sqlite3_
169b0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61  int64 sqlite3_la
169c0 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
169d0 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
169e0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e  * CAPI3REF: Coun
169f0 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20  t The Number Of 
16a00 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a  Rows Modified.**
16a10 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
16a20 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
16a30 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61 73  umber of databas
16a40 65 20 72 6f 77 73 20 74 68 61 74 20 77 65 72 65  e rows that were
16a50 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69   changed.** or i
16a60 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74  nserted or delet
16a70 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72  ed by the most r
16a80 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65  ecently complete
16a90 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a  d SQL statement.
16aa0 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62  ** on the [datab
16ab0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
16ac0 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
16ad0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
16ae0 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61 6e  ..** ^(Only chan
16af0 67 65 73 20 74 68 61 74 20 61 72 65 20 64 69 72  ges that are dir
16b00 65 63 74 6c 79 20 73 70 65 63 69 66 69 65 64 20  ectly specified 
16b10 62 79 20 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c  by the [INSERT],
16b20 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72   [UPDATE],.** or
16b30 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d   [DELETE] statem
16b40 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e  ent are counted.
16b50 20 20 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e    Auxiliary chan
16b60 67 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a  ges caused by.**
16b70 20 74 72 69 67 67 65 72 73 20 6f 72 20 5b 66 6f   triggers or [fo
16b80 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e  reign key action
16b90 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  s] are not count
16ba0 65 64 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a 2a  ed.)^ Use the.**
16bb0 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
16bc0 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74  changes()] funct
16bd0 69 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68 65 20  ion to find the 
16be0 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20  total number of 
16bf0 63 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75  changes.** inclu
16c00 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75  ding changes cau
16c10 73 65 64 20 62 79 20 74 72 69 67 67 65 72 73 20  sed by triggers 
16c20 61 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65 79 20  and foreign key 
16c30 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  actions..**.** ^
16c40 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65  Changes to a vie
16c50 77 20 74 68 61 74 20 61 72 65 20 73 69 6d 75 6c  w that are simul
16c60 61 74 65 64 20 62 79 20 61 6e 20 5b 49 4e 53 54  ated by an [INST
16c70 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 0a  EAD OF trigger].
16c80 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  ** are not count
16c90 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74  ed.  Only real t
16ca0 61 62 6c 65 20 63 68 61 6e 67 65 73 20 61 72 65  able changes are
16cb0 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20   counted..**.** 
16cc0 5e 28 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22  ^(A "row change"
16cd0 20 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20   is a change to 
16ce0 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20  a single row of 
16cf0 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a  a single table.*
16d00 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e 20 49  * caused by an I
16d10 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f  NSERT, DELETE, o
16d20 72 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65  r UPDATE stateme
16d30 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a  nt.  Rows that.*
16d40 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20 61 73  * are changed as
16d50 20 73 69 64 65 20 65 66 66 65 63 74 73 20 6f 66   side effects of
16d60 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74   [REPLACE] const
16d70 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e  raint resolution
16d80 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41  ,.** rollback, A
16d90 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c  BORT processing,
16da0 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f   [DROP TABLE], o
16db0 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a  r by any other.*
16dc0 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20  * mechanisms do 
16dd0 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72  not count as dir
16de0 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e  ect row changes.
16df0 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67  )^.**.** A "trig
16e00 67 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20  ger context" is 
16e10 61 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75  a scope of execu
16e20 74 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73  tion that begins
16e30 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74   and.** ends wit
16e40 68 20 74 68 65 20 73 63 72 69 70 74 20 6f 66 20  h the script of 
16e50 61 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45  a [CREATE TRIGGE
16e60 52 20 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a  R | trigger]. .*
16e70 2a 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65  * Most SQL state
16e80 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61  ments are.** eva
16e90 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f  luated outside o
16ea0 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20  f any trigger.  
16eb0 54 68 69 73 20 69 73 20 74 68 65 20 22 74 6f 70  This is the "top
16ec0 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67   level".** trigg
16ed0 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20  er context.  If 
16ee0 61 20 74 72 69 67 67 65 72 20 66 69 72 65 73 20  a trigger fires 
16ef0 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76  from the top lev
16f00 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69  el, a.** new tri
16f10 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20  gger context is 
16f20 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65 20  entered for the 
16f30 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74  duration of that
16f40 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e   one.** trigger.
16f50 20 20 53 75 62 74 72 69 67 67 65 72 73 20 63 72    Subtriggers cr
16f60 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73  eate subcontexts
16f70 20 66 6f 72 20 74 68 65 69 72 20 64 75 72 61 74   for their durat
16f80 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  ion..**.** ^Call
16f90 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  ing [sqlite3_exe
16fa0 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  c()] or [sqlite3
16fb0 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72 73 69  _step()] recursi
16fc0 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  vely does.** not
16fd0 20 63 72 65 61 74 65 20 61 20 6e 65 77 20 74 72   create a new tr
16fe0 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a  igger context..*
16ff0 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
17000 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
17010 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74  number of direct
17020 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20   row changes in 
17030 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65  the.** most rece
17040 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  nt INSERT, UPDAT
17050 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61  E, or DELETE sta
17060 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68  tement within th
17070 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65  e same.** trigge
17080 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a  r context..**.**
17090 20 5e 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c   ^Thus, when cal
170a0 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70  led from the top
170b0 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e   level, this fun
170c0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
170d0 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63  e.** number of c
170e0 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f  hanges in the mo
170f0 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54  st recent INSERT
17100 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
17110 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f  ETE.** that also
17120 20 6f 63 63 75 72 72 65 64 20 61 74 20 74 68 65   occurred at the
17130 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28 57   top level.  ^(W
17140 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f  ithin the body o
17150 66 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20  f a trigger,.** 
17160 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  the sqlite3_chan
17170 67 65 73 28 29 20 69 6e 74 65 72 66 61 63 65 20  ges() interface 
17180 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f  can be called to
17190 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72   find the number
171a0 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69   of.** changes i
171b0 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  n the most recen
171c0 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e  tly completed IN
171d0 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
171e0 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65   DELETE.** state
171f0 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20  ment within the 
17200 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65  body of the same
17210 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77   trigger..** How
17220 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72  ever, the number
17230 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e   returned does n
17240 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67  ot include chang
17250 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20  es.** caused by 
17260 73 75 62 74 72 69 67 67 65 72 73 20 73 69 6e 63  subtriggers sinc
17270 65 20 74 68 6f 73 65 20 68 61 76 65 20 74 68 65  e those have the
17280 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 29  ir own context.)
17290 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ^.**.** See also
172a0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f   the [sqlite3_to
172b0 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  tal_changes()] i
172c0 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a  nterface, the.**
172d0 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20   [count_changes 
172e0 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65  pragma], and the
172f0 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20   [changes() SQL 
17300 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
17310 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
17320 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
17330 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
17340 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
17350 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71  ion.** while [sq
17360 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d  lite3_changes()]
17370 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
17380 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
17390 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64  ned.** is unpred
173a0 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20  ictable and not 
173b0 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69  meaningful..*/.i
173c0 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  nt sqlite3_chang
173d0 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  es(sqlite3*);../
173e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
173f0 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52  otal Number Of R
17400 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a  ows Modified.**.
17410 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
17420 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
17430 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e  mber of row chan
17440 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 49  ges caused by [I
17450 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41  NSERT],.** [UPDA
17460 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20  TE] or [DELETE] 
17470 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65  statements since
17480 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
17490 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f  onnection] was o
174a0 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65 20  pened..** ^(The 
174b0 63 6f 75 6e 74 20 72 65 74 75 72 6e 65 64 20 62  count returned b
174c0 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f  y sqlite3_total_
174d0 63 68 61 6e 67 65 73 28 29 20 69 6e 63 6c 75 64  changes() includ
174e0 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a 2a  es all changes.*
174f0 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41  * from all [CREA
17500 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69  TE TRIGGER | tri
17510 67 67 65 72 5d 20 63 6f 6e 74 65 78 74 73 20 61  gger] contexts a
17520 6e 64 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20  nd changes made 
17530 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b  by.** [foreign k
17540 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f 77  ey actions]. How
17550 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75  ever,.** the cou
17560 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  nt does not incl
17570 75 64 65 20 63 68 61 6e 67 65 73 20 75 73 65 64  ude changes used
17580 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52   to implement [R
17590 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69  EPLACE] constrai
175a0 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62  nts,.** do rollb
175b0 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72  acks or ABORT pr
175c0 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52  ocessing, or [DR
175d0 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f 63 65 73  OP TABLE] proces
175e0 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f  sing.  The.** co
175f0 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  unt does not inc
17600 6c 75 64 65 20 72 6f 77 73 20 6f 66 20 76 69 65  lude rows of vie
17610 77 73 20 74 68 61 74 20 66 69 72 65 20 61 6e 20  ws that fire an 
17620 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67  [INSTEAD OF trig
17630 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20  ger],.** though 
17640 69 66 20 74 68 65 20 49 4e 53 54 45 41 44 20 4f  if the INSTEAD O
17650 46 20 74 72 69 67 67 65 72 20 6d 61 6b 65 73 20  F trigger makes 
17660 63 68 61 6e 67 65 73 20 6f 66 20 69 74 73 20 6f  changes of its o
17670 77 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e 67 65  wn, those change
17680 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65  s .** are counte
17690 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  d.)^.** ^The sql
176a0 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
176b0 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 6f  es() function co
176c0 75 6e 74 73 20 74 68 65 20 63 68 61 6e 67 65 73  unts the changes
176d0 20 61 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74   as soon as.** t
176e0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  he statement tha
176f0 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 20  t makes them is 
17700 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20  completed (when 
17710 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
17720 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73 65  ndle.** is passe
17730 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  d to [sqlite3_re
17740 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
17750 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e  e3_finalize()]).
17760 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
17770 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  the [sqlite3_cha
17780 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  nges()] interfac
17790 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74  e, the.** [count
177a0 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d  _changes pragma]
177b0 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c  , and the [total
177c0 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  _changes() SQL f
177d0 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
177e0 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
177f0 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
17800 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
17810 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
17820 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c  on.** while [sql
17830 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
17840 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67  es()] is running
17850 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a   then the value.
17860 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75  ** returned is u
17870 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
17880 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e   not meaningful.
17890 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
178a0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71  total_changes(sq
178b0 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
178c0 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72  CAPI3REF: Interr
178d0 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69  upt A Long-Runni
178e0 6e 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e  ng Query.**.** ^
178f0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61  This function ca
17900 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67  uses any pending
17910 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74   database operat
17920 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64  ion to abort and
17930 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74  .** return at it
17940 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72  s earliest oppor
17950 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75  tunity. This rou
17960 74 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c  tine is typicall
17970 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72  y.** called in r
17980 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65  esponse to a use
17990 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73  r action such as
179a0 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65   pressing "Cance
179b0 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20  l".** or Ctrl-C 
179c0 77 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77  where the user w
179d0 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72  ants a long quer
179e0 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68  y operation to h
179f0 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65  alt.** immediate
17a00 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73  ly..**.** ^It is
17a10 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68   safe to call th
17a20 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20  is routine from 
17a30 61 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65  a thread differe
17a40 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74  nt from the.** t
17a50 68 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75  hread that is cu
17a60 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20  rrently running 
17a70 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65  the database ope
17a80 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a  ration.  But it.
17a90 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  ** is not safe t
17aa0 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74  o call this rout
17ab0 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61  ine with a [data
17ac0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
17ad0 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73   that.** is clos
17ae0 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73  ed or might clos
17af0 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33  e before sqlite3
17b00 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74  _interrupt() ret
17b10 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  urns..**.** ^If 
17b20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  an SQL operation
17b30 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20   is very nearly 
17b40 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 20  finished at the 
17b50 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c  time when.** sql
17b60 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
17b70 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e   is called, then
17b80 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61   it might not ha
17b90 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74  ve an opportunit
17ba0 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72  y.** to be inter
17bb0 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74  rupted and might
17bc0 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d   continue to com
17bd0 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  pletion..**.** ^
17be0 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  An SQL operation
17bf0 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75   that is interru
17c00 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e  pted will return
17c10 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
17c20 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  PT]..** ^If the 
17c30 69 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20  interrupted SQL 
17c40 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20  operation is an 
17c50 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
17c60 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61  or DELETE.** tha
17c70 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65  t is inside an e
17c80 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
17c90 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e  ion, then the en
17ca0 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  tire transaction
17cb0 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c  .** will be roll
17cc0 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69  ed back automati
17cd0 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  cally..**.** ^Th
17ce0 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
17cf0 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69  upt(D) call is i
17d00 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61  n effect until a
17d10 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e  ll currently run
17d20 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ning.** SQL stat
17d30 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62  ements on [datab
17d40 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
17d50 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e  D complete.  ^An
17d60 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d  y new SQL statem
17d70 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
17d80 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
17d90 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
17da0 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20  rupt() call and 
17db0 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72  before the .** r
17dc0 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  unning statement
17dd0 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61  s reaches zero a
17de0 72 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61  re interrupted a
17df0 73 20 69 66 20 74 68 65 79 20 68 61 64 20 62 65  s if they had be
17e00 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72  en.** running pr
17e10 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ior to the sqlit
17e20 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63  e3_interrupt() c
17e30 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73  all.  ^New SQL s
17e40 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
17e50 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
17e60 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20  ter the running 
17e70 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20  statement count 
17e80 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65  reaches zero are
17e90 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64  .** not effected
17ea0 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f   by the sqlite3_
17eb0 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20  interrupt()..** 
17ec0 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ^A call to sqlit
17ed0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20  e3_interrupt(D) 
17ee0 74 68 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e  that occurs when
17ef0 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75   there are no ru
17f00 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61  nning.** SQL sta
17f10 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d  tements is a no-
17f20 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66  op and has no ef
17f30 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74  fect on SQL stat
17f40 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
17f50 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
17f60 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
17f70 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65  errupt() call re
17f80 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  turns..**.** If 
17f90 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
17fa0 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77  nection closes w
17fb0 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e  hile [sqlite3_in
17fc0 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73  terrupt()].** is
17fd0 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61   running then ba
17fe0 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69  d things will li
17ff0 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a  kely happen..*/.
18000 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74  void sqlite3_int
18010 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29  errupt(sqlite3*)
18020 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
18030 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
18040 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
18050 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a   Is Complete.**.
18060 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
18070 73 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72  s are useful dur
18080 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65  ing command-line
18090 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d   input to determ
180a0 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75  ine if the.** cu
180b0 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20  rrently entered 
180c0 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f  text seems to fo
180d0 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51  rm a complete SQ
180e0 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a  L statement or.*
180f0 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20  * if additional 
18100 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20  input is needed 
18110 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74  before sending t
18120 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20  he text into.** 
18130 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69  SQLite for parsi
18140 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74  ng.  ^These rout
18150 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66  ines return 1 if
18160 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
18170 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20  g.** appears to 
18180 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51  be a complete SQ
18190 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41  L statement.  ^A
181a0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75   statement is ju
181b0 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f  dged to be.** co
181c0 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64  mplete if it end
181d0 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c  s with a semicol
181e0 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20  on token and is 
181f0 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20  not a prefix of 
18200 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64  a.** well-formed
18210 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20   CREATE TRIGGER 
18220 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d  statement.  ^Sem
18230 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65  icolons that are
18240 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e   embedded within
18250 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72  .** string liter
18260 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64  als or quoted id
18270 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f  entifier names o
18280 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e  r comments are n
18290 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e  ot.** independen
182a0 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61  t tokens (they a
182b0 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74  re part of the t
182c0 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68  oken in which th
182d0 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64  ey are.** embedd
182e0 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20  ed) and thus do 
182f0 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73  not count as a s
18300 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61  tatement termina
18310 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63  tor.  ^Whitespac
18320 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74  e.** and comment
18330 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68  s that follow th
18340 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f  e final semicolo
18350 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a  n are ignored..*
18360 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
18370 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66  ines return 0 if
18380 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
18390 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e  s incomplete.  ^
183a0 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  If a.** memory a
183b0 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c  llocation fails,
183c0 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d   then SQLITE_NOM
183d0 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  EM is returned..
183e0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
183f0 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72  tines do not par
18400 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  se the SQL state
18410 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69  ments thus.** wi
18420 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79  ll not detect sy
18430 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f  ntactically inco
18440 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a  rrect SQL..**.**
18450 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73   ^(If SQLite has
18460 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61   not been initia
18470 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  lized using [sql
18480 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
18490 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20  )] prior .** to 
184a0 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33  invoking sqlite3
184b0 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68  _complete16() th
184c0 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  en sqlite3_initi
184d0 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
184e0 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  ed.** automatica
184f0 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63  lly by sqlite3_c
18500 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66  omplete16().  If
18510 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61   that initializa
18520 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74  tion fails,.** t
18530 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76  hen the return v
18540 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
18550 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77  3_complete16() w
18560 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a  ill be non-zero.
18570 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ** regardless of
18580 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
18590 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73  the input SQL is
185a0 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a   complete.)^.**.
185b0 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20  ** The input to 
185c0 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74  [sqlite3_complet
185d0 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a  e()] must be a z
185e0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
185f0 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a  * UTF-8 string..
18600 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20  **.** The input 
18610 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70  to [sqlite3_comp
18620 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62  lete16()] must b
18630 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  e a zero-termina
18640 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74  ted.** UTF-16 st
18650 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62  ring in native b
18660 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e  yte order..*/.in
18670 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  t sqlite3_comple
18680 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  te(const char *s
18690 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ql);.int sqlite3
186a0 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73  _complete16(cons
186b0 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f  t void *sql);../
186c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
186d0 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61  egister A Callba
186e0 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c  ck To Handle SQL
186f0 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a  ITE_BUSY Errors.
18700 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
18710 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62  ine sets a callb
18720 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  ack function tha
18730 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b  t might be invok
18740 65 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61  ed whenever.** a
18750 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64  n attempt is mad
18760 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61  e to open a data
18770 62 61 73 65 20 74 61 62 6c 65 20 74 68 61 74 20  base table that 
18780 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a  another thread.*
18790 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73  * or process has
187a0 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e   locked..**.** ^
187b0 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
187c0 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68  back is NULL, th
187d0 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  en [SQLITE_BUSY]
187e0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
187f0 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73  R_BLOCKED].** is
18800 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
18810 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75  ately upon encou
18820 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b  ntering the lock
18830 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 20  .  ^If the busy 
18840 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e  callback.** is n
18850 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68  ot NULL, then th
18860 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74  e callback might
18870 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   be invoked with
18880 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a   two arguments..
18890 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
188a0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
188b0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
188c0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76   a copy of the v
188d0 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69  oid* pointer whi
188e0 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69  ch.** is the thi
188f0 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  rd argument to s
18900 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
18910 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63  ler().  ^The sec
18920 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
18930 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ** the busy hand
18940 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ler callback is 
18950 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69  the number of ti
18960 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73  mes that the bus
18970 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a  y handler has.**
18980 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f   been invoked fo
18990 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65  r this locking e
189a0 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a  vent.  ^If the.*
189b0 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  * busy callback 
189c0 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20  returns 0, then 
189d0 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74  no additional at
189e0 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20  tempts are made 
189f0 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65  to.** access the
18a00 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53   database and [S
18a10 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b  QLITE_BUSY] or [
18a20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
18a30 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65  CKED] is returne
18a40 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61  d..** ^If the ca
18a50 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
18a60 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e  on-zero, then an
18a70 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a  other attempt.**
18a80 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e   is made to open
18a90 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f   the database fo
18aa0 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68  r reading and th
18ab0 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e  e cycle repeats.
18ac0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65  .**.** The prese
18ad0 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61  nce of a busy ha
18ae0 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67  ndler does not g
18af0 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74  uarantee that it
18b00 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64   will be invoked
18b10 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69  .** when there i
18b20 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f  s lock contentio
18b30 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65  n. ^If SQLite de
18b40 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e  termines that in
18b50 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a  voking the busy.
18b60 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64  ** handler could
18b70 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61   result in a dea
18b80 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67  dlock, it will g
18b90 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75  o ahead and retu
18ba0 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  rn [SQLITE_BUSY]
18bb0 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  .** or [SQLITE_I
18bc0 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e  OERR_BLOCKED] in
18bd0 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e  stead of invokin
18be0 67 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  g the busy handl
18bf0 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20  er..** Consider 
18c00 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65  a scenario where
18c10 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20   one process is 
18c20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c  holding a read l
18c30 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69  ock that.** it i
18c40 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d  s trying to prom
18c50 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65  ote to a reserve
18c60 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20  d lock and.** a 
18c70 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69  second process i
18c80 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65  s holding a rese
18c90 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69  rved lock that i
18ca0 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74  t is trying.** t
18cb0 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20  o promote to an 
18cc0 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20  exclusive lock. 
18cd0 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   The first proce
18ce0 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65  ss cannot procee
18cf0 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20  d.** because it 
18d00 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
18d10 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65  e second and the
18d20 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
18d30 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65  cannot.** procee
18d40 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20  d because it is 
18d50 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66  blocked by the f
18d60 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70  irst.  If both p
18d70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f  rocesses.** invo
18d80 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ke the busy hand
18d90 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69  lers, neither wi
18da0 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67  ll make any prog
18db0 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65  ress.  Therefore
18dc0 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75  ,.** SQLite retu
18dd0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  rns [SQLITE_BUSY
18de0 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  ] for the first 
18df0 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20  process, hoping 
18e00 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c  that this.** wil
18e10 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72  l induce the fir
18e20 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65  st process to re
18e30 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c  lease its read l
18e40 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a  ock and allow.**
18e50 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
18e60 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a  ess to proceed..
18e70 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  **.** ^The defau
18e80 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  lt busy callback
18e90 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   is NULL..**.** 
18ea0 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53  ^The [SQLITE_BUS
18eb0 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76  Y] error is conv
18ec0 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45  erted to [SQLITE
18ed0 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a  _IOERR_BLOCKED].
18ee0 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  ** when SQLite i
18ef0 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20  s in the middle 
18f00 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73  of a large trans
18f10 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c  action where all
18f20 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20   the.** changes 
18f30 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74  will not fit int
18f40 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20  o the in-memory 
18f50 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77  cache.  SQLite w
18f60 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68  ill.** already h
18f70 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44 20 6c  old a RESERVED l
18f80 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62  ock on the datab
18f90 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74  ase file, but it
18fa0 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f   needs.** to pro
18fb0 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74  mote this lock t
18fc0 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74  o EXCLUSIVE so t
18fd0 68 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c  hat it can spill
18fe0 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20   cache.** pages 
18ff0 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  into the databas
19000 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68  e file without h
19010 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e  arm to concurren
19020 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 5e  t.** readers.  ^
19030 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20  If it is unable 
19040 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c  to promote the l
19050 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e  ock, then the in
19060 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65  -memory.** cache
19070 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e   will be left in
19080 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74   an inconsistent
19090 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68   state and so th
190a0 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20  e error.** code 
190b0 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d  is promoted from
190c0 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20   the relatively 
190d0 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42  benign [SQLITE_B
190e0 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d  USY] to.** the m
190f0 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49  ore severe [SQLI
19100 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
19110 5d 2e 20 20 5e 54 68 69 73 20 65 72 72 6f 72 20  ].  ^This error 
19120 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a  code promotion.*
19130 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f  * forces an auto
19140 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f  matic rollback o
19150 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20  f the changes.  
19160 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72  See the.** <a hr
19170 65 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b  ef="/cvstrac/wik
19180 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f  i?p=CorruptionFo
19190 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72  llowingBusyError
191a0 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e  ">.** Corruption
191b0 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72  FollowingBusyErr
191c0 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65  or</a> wiki page
191d0 20 66 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f   for a discussio
191e0 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73  n of why.** this
191f0 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a   is important..*
19200 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e  *.** ^(There can
19210 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
19220 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  e busy handler d
19230 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a  efined for each.
19240 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
19250 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69  nection].  Setti
19260 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61  ng a new busy ha
19270 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79  ndler clears any
19280 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
19290 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e  et handler.)^  ^
192a0 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e  Note that callin
192b0 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
192c0 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69  timeout()].** wi
192d0 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63  ll also set or c
192e0 6c 65 61 72 20 74 68 65 20 62 75 73 79 20 68 61  lear the busy ha
192f0 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ndler..**.** The
19300 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73   busy callback s
19310 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61  hould not take a
19320 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68  ny actions which
19330 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64   modify the.** d
19340 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
19350 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
19360 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
19370 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69  .  Any such acti
19380 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e  ons.** result in
19390 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
193a0 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75  ior..** .** A bu
193b0 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20  sy handler must 
193c0 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61  not close the da
193d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
193e0 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65  n.** or [prepare
193f0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
19400 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75  t invoked the bu
19410 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69  sy handler..*/.i
19420 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  nt sqlite3_busy_
19430 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a  handler(sqlite3*
19440 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69  , int(*)(void*,i
19450 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  nt), void*);../*
19460 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65  .** CAPI3REF: Se
19470 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74  t A Busy Timeout
19480 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
19490 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c  tine sets a [sql
194a0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
194b0 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72  r | busy handler
194c0 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a  ] that sleeps.**
194d0 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64   for a specified
194e0 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20   amount of time 
194f0 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20  when a table is 
19500 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61  locked.  ^The ha
19510 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c  ndler.** will sl
19520 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d  eep multiple tim
19530 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73  es until at leas
19540 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f  t "ms" milliseco
19550 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a  nds of sleeping.
19560 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61  ** have accumula
19570 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20  ted.  ^After at 
19580 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69  least "ms" milli
19590 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
195a0 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64  ing,.** the hand
195b0 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68  ler returns 0 wh
195c0 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69  ich causes [sqli
195d0 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72  te3_step()] to r
195e0 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  eturn.** [SQLITE
195f0 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54  _BUSY] or [SQLIT
19600 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
19610 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  ..**.** ^Calling
19620 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
19630 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c  th an argument l
19640 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61  ess than or equa
19650 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72  l to zero.** tur
19660 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20  ns off all busy 
19670 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  handlers..**.** 
19680 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79  ^(There can only
19690 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73   be a single bus
196a0 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20  y handler for a 
196b0 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64  particular.** [d
196c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
196d0 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69 76 65  on] any any give
196e0 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e  n moment.  If an
196f0 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c  other busy handl
19700 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65  er.** was define
19710 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74  d  (using [sqlit
19720 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
19730 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c  )]) prior to cal
19740 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75  ling.** this rou
19750 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72  tine, that other
19760 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
19770 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a 69   cleared.)^.*/.i
19780 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  nt sqlite3_busy_
19790 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a  timeout(sqlite3*
197a0 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a  , int ms);../*.*
197b0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76  * CAPI3REF: Conv
197c0 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73  enience Routines
197d0 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65   For Running Que
197e0 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ries.**.** This 
197f0 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65  is a legacy inte
19800 72 66 61 63 65 20 74 68 61 74 20 69 73 20 70 72  rface that is pr
19810 65 73 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b  eserved for back
19820 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
19830 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74  ity..** Use of t
19840 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73  his interface is
19850 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64   not recommended
19860 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69  ..**.** Definiti
19870 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20  on: A <b>result 
19880 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d  table</b> is mem
19890 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75  ory data structu
198a0 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68  re created by th
198b0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65  e.** [sqlite3_ge
198c0 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72  t_table()] inter
198d0 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20  face.  A result 
198e0 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68  table records th
198f0 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75  e.** complete qu
19900 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d  ery results from
19910 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65   one or more que
19920 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ries..**.** The 
19930 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c  table conceptual
19940 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20  ly has a number 
19950 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75  of rows and colu
19960 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65  mns.  But.** the
19970 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e  se numbers are n
19980 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72  ot part of the r
19990 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65  esult table itse
199a0 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75  lf.  These.** nu
199b0 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e  mbers are obtain
199c0 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20  ed separately.  
199d0 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d  Let N be the num
199e0 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61  ber of rows.** a
199f0 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62  nd M be the numb
19a00 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a  er of columns..*
19a10 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  *.** A result ta
19a20 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20  ble is an array 
19a30 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a  of pointers to z
19a40 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
19a50 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a  TF-8 strings..**
19a60 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29   There are (N+1)
19a70 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74  *M elements in t
19a80 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 66  he array.  The f
19a90 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20  irst M pointers 
19aa0 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f  point.** to zero
19ab0 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
19ac0 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69  ngs that  contai
19ad0 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74  n the names of t
19ae0 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54  he columns..** T
19af0 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74  he remaining ent
19b00 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74  ries all point t
19b10 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e  o query results.
19b20 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65    NULL values re
19b30 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20  sult.** in NULL 
19b40 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f  pointers.  All o
19b50 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20  ther values are 
19b60 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a  in their UTF-8 z
19b70 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
19b80 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65  * string represe
19b90 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72  ntation as retur
19ba0 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
19bb0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a  column_text()]..
19bc0 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  **.** A result t
19bd0 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69  able might consi
19be0 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72  st of one or mor
19bf0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
19c00 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e  ions..** It is n
19c10 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20  ot safe to pass 
19c20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64  a result table d
19c30 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69  irectly to [sqli
19c40 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20  te3_free()]..** 
19c50 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73  A result table s
19c60 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63  hould be dealloc
19c70 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ated using [sqli
19c80 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
19c90 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e  ]..**.** ^(As an
19ca0 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20   example of the 
19cb0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72  result table for
19cc0 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71  mat, suppose a q
19cd0 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69  uery result.** i
19ce0 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  s as follows:.**
19cf0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
19d00 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20  <pre>.**        
19d10 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67  Name        | Ag
19d20 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d  e.**        ----
19d30 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
19d40 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c  ---.**        Al
19d50 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a  ice       | 43.*
19d60 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20  *        Bob    
19d70 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20       | 28.**    
19d80 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20      Cindy       
19d90 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  | 21.** </pre></
19da0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
19db0 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20  * There are two 
19dc0 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e  column (M==2) an
19dd0 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d  d three rows (N=
19de0 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a  =3).  Thus the.*
19df0 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68  * result table h
19e00 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53  as 8 entries.  S
19e10 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c  uppose the resul
19e20 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65  t table is store
19e30 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79  d.** in an array
19e40 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e   names azResult.
19e50 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20    Then azResult 
19e60 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65  holds this conte
19e70 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  nt:.**.** <block
19e80 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
19e90 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
19ea0 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a  91;0] = "Name";.
19eb0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
19ec0 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65  lt&#91;1] = "Age
19ed0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
19ee0 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22  esult&#91;2] = "
19ef0 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20  Alice";.**      
19f00 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33    azResult&#91;3
19f10 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20  ] = "43";.**    
19f20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
19f30 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20  ;4] = "Bob";.** 
19f40 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
19f50 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a  #91;5] = "28";.*
19f60 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
19f70 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64  t&#91;6] = "Cind
19f80 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  y";.**        az
19f90 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20  Result&#91;7] = 
19fa0 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  "21";.** </pre><
19fb0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a  /blockquote>)^.*
19fc0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
19fd0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75  3_get_table() fu
19fe0 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73  nction evaluates
19ff0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
1a000 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61  semicolon-separa
1a010 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
1a020 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74  ts in the zero-t
1a030 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a  erminated UTF-8.
1a040 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73  ** string of its
1a050 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
1a060 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72 65 73  nd returns a res
1a070 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65  ult table to the
1a080 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65  .** pointer give
1a090 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72  n in its 3rd par
1a0a0 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66  ameter..**.** Af
1a0b0 74 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  ter the applicat
1a0c0 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64  ion has finished
1a0d0 20 77 69 74 68 20 74 68 65 20 72 65 73 75 6c 74   with the result
1a0e0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65   from sqlite3_ge
1a0f0 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74  t_table(),.** it
1a100 20 6d 75 73 74 20 70 61 73 73 20 74 68 65 20 72   must pass the r
1a110 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e  esult table poin
1a120 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66  ter to sqlite3_f
1a130 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f  ree_table() in o
1a140 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61  rder to.** relea
1a150 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68  se the memory th
1a160 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e  at was malloced.
1a170 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65    Because of the
1a180 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   way the.** [sql
1a190 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68  ite3_malloc()] h
1a1a0 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71  appens within sq
1a1b0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1a1c0 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a  ), the calling.*
1a1d0 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  * function must 
1a1e0 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20  not try to call 
1a1f0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1a200 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79   directly.  Only
1a210 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
1a220 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62  e_table()] is ab
1a230 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68  le to release th
1a240 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c  e memory properl
1a250 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a  y and safely..**
1a260 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1a270 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65  get_table() inte
1a280 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65  rface is impleme
1a290 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65  nted as a wrappe
1a2a0 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c  r around.** [sql
1a2b0 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54  ite3_exec()].  T
1a2c0 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
1a2d0 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64  able() routine d
1a2e0 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63  oes not have acc
1a2f0 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e  ess.** to any in
1a300 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75  ternal data stru
1a310 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65  ctures of SQLite
1a320 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20  .  It uses only 
1a330 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e  the public.** in
1a340 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20  terface defined 
1a350 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73  here.  As a cons
1a360 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20  equence, errors 
1a370 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68  that occur in th
1a380 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79  e.** wrapper lay
1a390 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68  er outside of th
1a3a0 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69  e internal [sqli
1a3b0 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c  te3_exec()] call
1a3c0 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c   are not.** refl
1a3d0 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75  ected in subsequ
1a3e0 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ent calls to [sq
1a3f0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
1a400 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
1a410 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e  errmsg()]..*/.in
1a420 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  t sqlite3_get_ta
1a430 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ble(.  sqlite3 *
1a440 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20  db,          /* 
1a450 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  An open database
1a460 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
1a470 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53   *zSql,     /* S
1a480 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74  QL to be evaluat
1a490 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a  ed */.  char ***
1a4a0 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a  pazResult,    /*
1a4b0 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20   Results of the 
1a4c0 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a  query */.  int *
1a4d0 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20  pnRow,          
1a4e0 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65   /* Number of re
1a4f0 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65  sult rows writte
1a500 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20  n here */.  int 
1a510 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20  *pnColumn,      
1a520 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72    /* Number of r
1a530 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72  esult columns wr
1a540 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20  itten here */.  
1a550 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20  char **pzErrmsg 
1a560 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d        /* Error m
1a570 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  sg written here 
1a580 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  */.);.void sqlit
1a590 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68  e3_free_table(ch
1a5a0 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f  ar **result);../
1a5b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
1a5c0 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20  ormatted String 
1a5d0 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f  Printing Functio
1a5e0 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  ns.**.** These r
1a5f0 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b  outines are work
1a600 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22  -alikes of the "
1a610 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79  printf()" family
1a620 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a   of functions.**
1a630 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
1a640 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  rd C library..**
1a650 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1a660 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73  _mprintf() and s
1a670 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28  qlite3_vmprintf(
1a680 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65  ) routines write
1a690 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74   their.** result
1a6a0 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  s into memory ob
1a6b0 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
1a6c0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a  ite3_malloc()]..
1a6d0 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72  ** The strings r
1a6e0 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65  eturned by these
1a6f0 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68   two routines sh
1a700 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61  ould be.** relea
1a710 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  sed by [sqlite3_
1a720 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20  free()].  ^Both 
1a730 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
1a740 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  a.** NULL pointe
1a750 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  r if [sqlite3_ma
1a760 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c  lloc()] is unabl
1a770 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e  e to allocate en
1a780 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74  ough.** memory t
1a790 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c  o hold the resul
1a7a0 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  ting string..**.
1a7b0 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33  ** ^(The sqlite3
1a7c0 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74  _snprintf() rout
1a7d0 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74  ine is similar t
1a7e0 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66  o "snprintf()" f
1a7f0 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64  rom.** the stand
1a800 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20  ard C library.  
1a810 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72  The result is wr
1a820 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a  itten into the.*
1a830 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65  * buffer supplie
1a840 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
1a850 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20  parameter whose 
1a860 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79  size is given by
1a870 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61  .** the first pa
1a880 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68  rameter. Note th
1a890 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20  at the order of 
1a8a0 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f  the.** first two
1a8b0 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72   parameters is r
1a8c0 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70  eversed from snp
1a8d0 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73  rintf().)^  This
1a8e0 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72   is an.** histor
1a8f0 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68  ical accident th
1a900 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78  at cannot be fix
1a910 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ed without break
1a920 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  ing.** backwards
1a930 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20   compatibility. 
1a940 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61   ^(Note also tha
1a950 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  t sqlite3_snprin
1a960 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20  tf().** returns 
1a970 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73  a pointer to its
1a980 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20   buffer instead 
1a990 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  of the number of
1a9a0 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61  .** characters a
1a9b0 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20  ctually written 
1a9c0 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e  into the buffer.
1a9d0 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61  )^  We admit tha
1a9e0 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  t.** the number 
1a9f0 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72  of characters wr
1aa00 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61  itten would be a
1aa10 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74   more useful ret
1aa20 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74  urn.** value but
1aa30 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67   we cannot chang
1aa40 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  e the implementa
1aa50 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  tion of sqlite3_
1aa60 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f  snprintf().** no
1aa70 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  w without breaki
1aa80 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ng compatibility
1aa90 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67  ..**.** ^As long
1aaa0 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73   as the buffer s
1aab0 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74  ize is greater t
1aac0 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65  han zero, sqlite
1aad0 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
1aae0 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20  guarantees that 
1aaf0 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c  the buffer is al
1ab00 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  ways zero-termin
1ab10 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73  ated.  ^The firs
1ab20 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22  t.** parameter "
1ab30 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20  n" is the total 
1ab40 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66  size of the buff
1ab50 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70  er, including sp
1ab60 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a  ace for.** the z
1ab70 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero terminator. 
1ab80 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20   So the longest 
1ab90 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20  string that can 
1aba0 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a  be completely.**
1abb0 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65   written will be
1abc0 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e   n-1 characters.
1abd0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1abe0 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20  te3_vsnprintf() 
1abf0 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61 72  routine is a var
1ac00 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20  args version of 
1ac10 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1ac20 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ()..**.** These 
1ac30 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70  routines all imp
1ac40 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69  lement some addi
1ac50 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e  tional formattin
1ac60 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61  g.** options tha
1ac70 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72  t are useful for
1ac80 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51   constructing SQ
1ac90 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
1aca0 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61   All of the usua
1acb0 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61  l printf() forma
1acc0 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70  tting options ap
1acd0 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f  ply.  In additio
1ace0 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61  n, there.** is a
1acf0 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61  re "%q", "%Q", a
1ad00 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e  nd "%z" options.
1ad10 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20  .**.** ^(The %q 
1ad20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
1ad30 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20  e %s in that it 
1ad40 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75  substitutes a nu
1ad50 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  l-terminated.** 
1ad60 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20  string from the 
1ad70 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20  argument list.  
1ad80 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62  But %q also doub
1ad90 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63  les every '\'' c
1ada0 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20  haracter..** %q 
1adb0 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20  is designed for 
1adc0 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72  use inside a str
1add0 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20  ing literal.)^  
1ade0 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68  By doubling each
1adf0 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74   '\''.** charact
1ae00 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74 68  er it escapes th
1ae10 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e 64  at character and
1ae20 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65   allows it to be
1ae30 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a   inserted into.*
1ae40 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a  * the string..**
1ae50 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  .** For example,
1ae60 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 69   assume the stri
1ae70 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78  ng variable zTex
1ae80 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20  t contains text 
1ae90 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
1aea0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1aeb0 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54  re>.**  char *zT
1aec0 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 61  ext = "It's a ha
1aed0 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f  ppy day!";.** </
1aee0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1aef0 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20  >.**.** One can 
1af00 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69 6e  use this text in
1af10 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
1af20 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  t as follows:.**
1af30 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1af40 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
1af50 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d  zSQL = sqlite3_m
1af60 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49  printf("INSERT I
1af70 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53  NTO table VALUES
1af80 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b  ('%q')", zText);
1af90 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65  .**  sqlite3_exe
1afa0 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30  c(db, zSQL, 0, 0
1afb0 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  , 0);.**  sqlite
1afc0 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a  3_free(zSQL);.**
1afd0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1afe0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75  ote>.**.** Becau
1aff0 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74  se the %q format
1b000 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c   string is used,
1b010 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 63   the '\'' charac
1b020 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20  ter in zText.** 
1b030 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 74  is escaped and t
1b040 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64  he SQL generated
1b050 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a   is as follows:.
1b060 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1b070 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45  e><pre>.**  INSE
1b080 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56  RT INTO table1 V
1b090 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 68  ALUES('It''s a h
1b0a0 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c  appy day!').** <
1b0b0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1b0c0 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73  e>.**.** This is
1b0d0 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77   correct.  Had w
1b0e0 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 61  e used %s instea
1b0f0 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e  d of %q, the gen
1b100 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f  erated SQL.** wo
1b110 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20  uld have looked 
1b120 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a  like this:.**.**
1b130 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1b140 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e  e>.**  INSERT IN
1b150 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53  TO table1 VALUES
1b160 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20 64  ('It's a happy d
1b170 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  ay!');.** </pre>
1b180 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1b190 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20  .** This second 
1b1a0 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51  example is an SQ
1b1b0 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20  L syntax error. 
1b1c0 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75   As a general ru
1b1d0 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a  le you should.**
1b1e0 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 69   always use %q i
1b1f0 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 65  nstead of %s whe
1b200 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74  n inserting text
1b210 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c   into a string l
1b220 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28  iteral..**.** ^(
1b230 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f  The %Q option wo
1b240 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65  rks like %q exce
1b250 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20  pt it also adds 
1b260 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72  single quotes ar
1b270 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73  ound.** the outs
1b280 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c  ide of the total
1b290 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69   string.  Additi
1b2a0 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70  onally, if the p
1b2b0 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a  arameter in the.
1b2c0 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74  ** argument list
1b2d0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
1b2e0 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75 74  er, %Q substitut
1b2f0 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c  es the text "NUL
1b300 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73  L" (without.** s
1b310 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e  ingle quotes).)^
1b320 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c    So, for exampl
1b330 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79  e, one could say
1b340 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1b350 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
1b360 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
1b370 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
1b380 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
1b390 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74  LUES(%Q)", zText
1b3a0 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65  );.**  sqlite3_e
1b3b0 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c  xec(db, zSQL, 0,
1b3c0 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69   0, 0);.**  sqli
1b3d0 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a  te3_free(zSQL);.
1b3e0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1b3f0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
1b400 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c   code above will
1b410 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63   render a correc
1b420 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
1b430 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76  in the zSQL.** v
1b440 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20  ariable even if 
1b450 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62  the zText variab
1b460 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  le is a NULL poi
1b470 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  nter..**.** ^(Th
1b480 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e  e "%z" formattin
1b490 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  g option works l
1b4a0 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69 74  ike "%s" but wit
1b4b0 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f  h the.** additio
1b4c0 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65  n that after the
1b4d0 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e   string has been
1b4e0 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64   read and copied
1b4f0 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73   into.** the res
1b500 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72  ult, [sqlite3_fr
1b510 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20  ee()] is called 
1b520 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  on the input str
1b530 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a  ing.)^.*/.char *
1b540 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
1b550 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29  const char*,...)
1b560 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  ;.char *sqlite3_
1b570 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63  vmprintf(const c
1b580 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a  har*, va_list);.
1b590 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e  char *sqlite3_sn
1b5a0 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a  printf(int,char*
1b5b0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e  ,const char*, ..
1b5c0 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  .);.char *sqlite
1b5d0 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c  3_vsnprintf(int,
1b5e0 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
1b5f0 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a  *, va_list);../*
1b600 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
1b610 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
1b620 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20  Subsystem.**.** 
1b630 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
1b640 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65  uses these three
1b650 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c   routines for al
1b660 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20  l of its own.** 
1b670 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20  internal memory 
1b680 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
1b690 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20  . "Core" in the 
1b6a0 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63  previous sentenc
1b6b0 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e  e.** does not in
1b6c0 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d  clude operating-
1b6d0 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20  system specific 
1b6e0 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
1b6f0 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64  on.  The.** Wind
1b700 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74  ows VFS uses nat
1b710 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64  ive malloc() and
1b720 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65   free() for some
1b730 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a   operations..**.
1b740 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1b750 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65  malloc() routine
1b760 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
1b770 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a  er to a block.**
1b780 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65   of memory at le
1b790 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c  ast N bytes in l
1b7a0 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69  ength, where N i
1b7b0 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  s the parameter.
1b7c0 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
1b7d0 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62  malloc() is unab
1b7e0 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66  le to obtain suf
1b7f0 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20  ficient free.** 
1b800 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72  memory, it retur
1b810 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
1b820 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72 61  r.  ^If the para
1b830 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71  meter N to.** sq
1b840 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69  lite3_malloc() i
1b850 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69  s zero or negati
1b860 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ve then sqlite3_
1b870 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73  malloc() returns
1b880 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  .** a NULL point
1b890 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  er..**.** ^Calli
1b8a0 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ng sqlite3_free(
1b8b0 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72  ) with a pointer
1b8c0 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75   previously retu
1b8d0 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
1b8e0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73  e3_malloc() or s
1b8f0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1b900 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d   releases that m
1b910 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74  emory so.** that
1b920 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75   it might be reu
1b930 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  sed.  ^The sqlit
1b940 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e  e3_free() routin
1b950 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20  e is.** a no-op 
1b960 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  if is called wit
1b970 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
1b980 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c  .  Passing a NUL
1b990 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  L pointer.** to 
1b9a0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
1b9b0 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74  s harmless.  Aft
1b9c0 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20  er being freed, 
1b9d0 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64  memory.** should
1b9e0 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64   neither be read
1b9f0 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45   nor written.  E
1ba00 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76  ven reading prev
1ba10 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20  iously freed.** 
1ba20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73  memory might res
1ba30 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74  ult in a segment
1ba40 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f  ation fault or o
1ba50 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f  ther severe erro
1ba60 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72  r..** Memory cor
1ba70 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65  ruption, a segme
1ba80 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f  ntation fault, o
1ba90 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65  r other severe e
1baa0 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65  rror.** might re
1bab0 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f  sult if sqlite3_
1bac0 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64  free() is called
1bad0 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c   with a non-NULL
1bae0 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a   pointer that.**
1baf0 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65   was not obtaine
1bb00 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
1bb10 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
1bb20 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
1bb30 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
1bb40 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65  3_realloc() inte
1bb50 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
1bb60 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72  o resize a.** pr
1bb70 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ior memory alloc
1bb80 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c  ation to be at l
1bb90 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68  east N bytes, wh
1bba0 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20  ere N is the.** 
1bbb0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1bbc0 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c  .  The memory al
1bbd0 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72  location to be r
1bbe0 65 73 69 7a 65 64 20 69 73 20 74 68 65 20 66 69  esized is the fi
1bbf0 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  rst.** parameter
1bc00 2e 29 5e 20 5e 20 49 66 20 74 68 65 20 66 69 72  .)^ ^ If the fir
1bc10 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
1bc20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1bc30 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70  ).** is a NULL p
1bc40 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20  ointer then its 
1bc50 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e  behavior is iden
1bc60 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67  tical to calling
1bc70 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
1bc80 6f 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69 73  oc(N) where N is
1bc90 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
1bca0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
1bcb0 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e  _realloc()..** ^
1bcc0 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  If the second pa
1bcd0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
1bce0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 20  e3_realloc() is 
1bcf0 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74  zero or.** negat
1bd00 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68  ive then the beh
1bd10 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79  avior is exactly
1bd20 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c   the same as cal
1bd30 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ling.** sqlite3_
1bd40 66 72 65 65 28 50 29 20 77 68 65 72 65 20 50 20  free(P) where P 
1bd50 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  is the first par
1bd60 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1bd70 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20  3_realloc()..** 
1bd80 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  ^sqlite3_realloc
1bd90 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  () returns a poi
1bda0 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79  nter to a memory
1bdb0 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f   allocation.** o
1bdc0 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  f at least N byt
1bdd0 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55  es in size or NU
1bde0 4c 4c 20 69 66 20 73 75 66 66 69 63 69 65 6e 74  LL if sufficient
1bdf0 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 61   memory is unava
1be00 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d  ilable..** ^If M
1be10 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20   is the size of 
1be20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
1be30 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e  tion, then min(N
1be40 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20  ,M) bytes.** of 
1be50 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
1be60 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20  tion are copied 
1be70 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69  into the beginni
1be80 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74  ng of buffer ret
1be90 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69  urned.** by sqli
1bea0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e  te3_realloc() an
1beb0 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  d the prior allo
1bec0 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e  cation is freed.
1bed0 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
1bee0 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  realloc() return
1bef0 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65  s NULL, then the
1bf00 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
1bf10 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 65  n.** is not free
1bf20 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65  d..**.** ^The me
1bf30 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79  mory returned by
1bf40 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1bf50 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  ) and sqlite3_re
1bf60 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c  alloc().** is al
1bf70 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20  ways aligned to 
1bf80 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79  at least an 8 by
1bf90 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20  te boundary, or 
1bfa0 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62  to a.** 4 byte b
1bfb0 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b  oundary if the [
1bfc0 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c  SQLITE_4_BYTE_AL
1bfd0 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f  IGNED_MALLOC] co
1bfe0 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70  mpile-time.** op
1bff0 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a  tion is used..**
1c000 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65  .** In SQLite ve
1c010 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20  rsion 3.5.0 and 
1c020 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f  3.5.1, it was po
1c030 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65  ssible to define
1c040 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f  .** the SQLITE_O
1c050 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43  MIT_MEMORY_ALLOC
1c060 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c  ATION which woul
1c070 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c  d cause the buil
1c080 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  t-in.** implemen
1c090 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20  tation of these 
1c0a0 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f  routines to be o
1c0b0 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 61  mitted.  That ca
1c0c0 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e  pability.** is n
1c0d0 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65  o longer provide
1c0e0 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69  d.  Only built-i
1c0f0 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
1c100 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e  ors can be used.
1c110 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20  .**.** Prior to 
1c120 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
1c130 2e 37 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 6f  .7.10, the Windo
1c140 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20  ws OS interface 
1c150 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20  layer called.** 
1c160 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f  the system mallo
1c170 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64  c() and free() d
1c180 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e  irectly when con
1c190 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e  verting.** filen
1c1a0 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65  ames between the
1c1b0 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
1c1c0 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a  used by SQLite.*
1c1d0 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66  * and whatever f
1c1e0 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67  ilename encoding
1c1f0 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20   is used by the 
1c200 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f  particular Windo
1c210 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69  ws.** installati
1c220 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f  on.  Memory allo
1c230 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 65  cation errors we
1c240 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74  re detected, but
1c250 0a 2a 2a 20 74 68 65 79 20 77 65 72 65 20 72 65  .** they were re
1c260 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b  ported back as [
1c270 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d  SQLITE_CANTOPEN]
1c280 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49   or.** [SQLITE_I
1c290 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 61  OERR] rather tha
1c2a0 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  n [SQLITE_NOMEM]
1c2b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e  ..**.** The poin
1c2c0 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ter arguments to
1c2d0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1c2e0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
1c2f0 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73  ealloc()].** mus
1c300 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c  t be either NULL
1c310 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72   or else pointer
1c320 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  s obtained from 
1c330 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63  a prior.** invoc
1c340 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
1c350 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b  3_malloc()] or [
1c360 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1c370 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20  )] that have.** 
1c380 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c  not yet been rel
1c390 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  eased..**.** The
1c3a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
1c3b0 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72  t not read or wr
1c3c0 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a  ite any part of.
1c3d0 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65  ** a block of me
1c3e0 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 61  mory after it ha
1c3f0 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20  s been released 
1c400 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
1c410 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71  3_free()] or [sq
1c420 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
1c430 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
1c440 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a  e3_malloc(int);.
1c450 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65  void *sqlite3_re
1c460 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74  alloc(void*, int
1c470 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
1c480 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  free(void*);../*
1c490 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
1c4a0 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53  mory Allocator S
1c4b0 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20  tatistics.**.** 
1c4c0 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20  SQLite provides 
1c4d0 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66  these two interf
1c4e0 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69  aces for reporti
1c4f0 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73  ng on the status
1c500 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
1c510 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b  te3_malloc()], [
1c520 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c  sqlite3_free()],
1c530 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
1c540 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74  alloc()].** rout
1c550 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d  ines, which form
1c560 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65   the built-in me
1c570 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1c580 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a  subsystem..**.**
1c590 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d   ^The [sqlite3_m
1c5a0 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f  emory_used()] ro
1c5b0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
1c5c0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
1c5d0 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63  s.** of memory c
1c5e0 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e  urrently outstan
1c5f0 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62  ding (malloced b
1c600 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a  ut not freed)..*
1c610 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
1c620 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
1c630 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ()] routine retu
1c640 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a  rns the maximum.
1c650 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c  ** value of [sql
1c660 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
1c670 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69  ()] since the hi
1c680 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a  gh-water mark.**
1c690 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e   was last reset.
1c6a0 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65    ^The values re
1c6b0 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
1c6c0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
1c6d0 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1c6e0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1c6f0 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e  er()] include an
1c700 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64  y overhead.** ad
1c710 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e  ded by SQLite in
1c720 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74   its implementat
1c730 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
1c740 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75  malloc()],.** bu
1c750 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61  t not overhead a
1c760 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20  dded by the any 
1c770 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65  underlying syste
1c780 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75  m library.** rou
1c790 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69  tines that [sqli
1c7a0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61  te3_malloc()] ma
1c7b0 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  y call..**.** ^T
1c7c0 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77  he memory high-w
1c7d0 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73  ater mark is res
1c7e0 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e  et to the curren
1c7f0 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73  t value of.** [s
1c800 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
1c810 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c  ed()] if and onl
1c820 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  y if the paramet
1c830 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  er to.** [sqlite
1c840 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1c850 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20  er()] is true.  
1c860 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72  ^The value retur
1c870 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74  ned.** by [sqlit
1c880 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
1c890 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 68  ter(1)] is the h
1c8a0 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a  igh-water mark.*
1c8b0 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72  * prior to the r
1c8c0 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  eset..*/.sqlite3
1c8d0 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d  _int64 sqlite3_m
1c8e0 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29  emory_used(void)
1c8f0 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
1c900 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
1c910 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 73  ighwater(int res
1c920 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20  etFlag);../*.** 
1c930 43 41 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f  CAPI3REF: Pseudo
1c940 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47  -Random Number G
1c950 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53  enerator.**.** S
1c960 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61  QLite contains a
1c970 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73   high-quality ps
1c980 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62  eudo-random numb
1c990 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52  er generator (PR
1c9a0 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73  NG) used to.** s
1c9b0 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f  elect random [RO
1c9c0 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68  WID | ROWIDs] wh
1c9d0 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77  en inserting new
1c9e0 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20   records into a 
1c9f0 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c  table that.** al
1ca00 72 65 61 64 79 20 75 73 65 73 20 74 68 65 20 6c  ready uses the l
1ca10 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20  argest possible 
1ca20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52  [ROWID].  The PR
1ca30 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20  NG is also used 
1ca40 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64  for.** the build
1ca50 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64  -in random() and
1ca60 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51   randomblob() SQ
1ca70 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68  L functions.  Th
1ca80 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c  is interface all
1ca90 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  ows.** applicati
1caa0 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 68  ons to access th
1cab0 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20  e same PRNG for 
1cac0 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a  other purposes..
1cad0 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f  **.** ^A call to
1cae0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74   this routine st
1caf0 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20  ores N bytes of 
1cb00 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20  randomness into 
1cb10 62 75 66 66 65 72 20 50 2e 0a 2a 2a 20 5e 49 66  buffer P..** ^If
1cb20 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20   N is less than 
1cb30 6f 6e 65 2c 20 74 68 65 6e 20 50 20 63 61 6e 20  one, then P can 
1cb40 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  be a NULL pointe
1cb50 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 69  r..**.** ^If thi
1cb60 73 20 72 6f 75 74 69 6e 65 20 68 61 73 20 6e 6f  s routine has no
1cb70 74 20 62 65 65 6e 20 70 72 65 76 69 6f 75 73 6c  t been previousl
1cb80 79 20 63 61 6c 6c 65 64 20 6f 72 20 69 66 20 74  y called or if t
1cb90 68 65 20 70 72 65 76 69 6f 75 73 0a 2a 2a 20 63  he previous.** c
1cba0 61 6c 6c 20 68 61 64 20 4e 20 6c 65 73 73 20 74  all had N less t
1cbb0 68 61 6e 20 6f 6e 65 2c 20 74 68 65 6e 20 74 68  han one, then th
1cbc0 65 20 50 52 4e 47 20 69 73 20 73 65 65 64 65 64  e PRNG is seeded
1cbd0 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73   using randomnes
1cbe0 73 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66 72  s.** obtained fr
1cbf0 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65  om the xRandomne
1cc00 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  ss method of the
1cc10 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
1cc20 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a  3_vfs] object..*
1cc30 2a 20 5e 49 66 20 74 68 65 20 70 72 65 76 69 6f  * ^If the previo
1cc40 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20  us call to this 
1cc50 72 6f 75 74 69 6e 65 20 68 61 64 20 61 6e 20 4e  routine had an N
1cc60 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 74 68   of 1 or more th
1cc70 65 6e 0a 2a 2a 20 74 68 65 20 70 73 65 75 64 6f  en.** the pseudo
1cc80 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67  -randomness is g
1cc90 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65  enerated.** inte
1cca0 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f  rnally and witho
1ccb0 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74  ut recourse to t
1ccc0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  he [sqlite3_vfs]
1ccd0 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20   xRandomness.** 
1cce0 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20  method..*/.void 
1ccf0 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65  sqlite3_randomne
1cd00 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a  ss(int N, void *
1cd10 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  P);../*.** CAPI3
1cd20 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d  REF: Compile-Tim
1cd30 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20  e Authorization 
1cd40 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20  Callbacks.**.** 
1cd50 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65  ^This routine re
1cd60 67 69 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f  gisters an autho
1cd70 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77  rizer callback w
1cd80 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72  ith a particular
1cd90 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
1cda0 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c  nnection], suppl
1cdb0 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74  ied in the first
1cdc0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54   argument..** ^T
1cdd0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1cde0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
1cdf0 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65  d as SQL stateme
1ce00 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f  nts are being co
1ce10 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71  mpiled.** by [sq
1ce20 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
1ce30 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
1ce40 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1ce50 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  e_v2()],.** [sql
1ce60 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
1ce70 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
1ce80 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20  repare16_v2()]. 
1ce90 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20   ^At various.** 
1cea0 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68  points during th
1ceb0 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72  e compilation pr
1cec0 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20  ocess, as logic 
1ced0 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64  is being created
1cee0 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76  .** to perform v
1cef0 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20  arious actions, 
1cf00 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1cf10 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
1cf20 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20  ed to.** see if 
1cf30 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72  those actions ar
1cf40 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65  e allowed.  ^The
1cf50 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1cf60 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72  back should.** r
1cf70 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
1cf80 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61  ] to allow the a
1cf90 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49  ction, [SQLITE_I
1cfa0 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c  GNORE] to disall
1cfb0 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66  ow the.** specif
1cfc0 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c  ic action but al
1cfd0 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74  low the SQL stat
1cfe0 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75  ement to continu
1cff0 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69  e to be.** compi
1d000 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  led, or [SQLITE_
1d010 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74  DENY] to cause t
1d020 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74  he entire SQL st
1d030 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a  atement to be.**
1d040 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61   rejected with a
1d050 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68  n error.  ^If th
1d060 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1d070 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a  lback returns.**
1d080 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72   any value other
1d090 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47   than [SQLITE_IG
1d0a0 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  NORE], [SQLITE_O
1d0b0 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  K], or [SQLITE_D
1d0c0 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ENY].** then the
1d0d0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1d0e0 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76  e_v2()] or equiv
1d0f0 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20  alent call that 
1d100 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65  triggered.** the
1d110 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c   authorizer will
1d120 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72   fail with an er
1d130 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a  ror message..**.
1d140 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c  ** When the call
1d150 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
1d160 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d  LITE_OK], that m
1d170 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69  eans the operati
1d180 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20  on.** requested 
1d190 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68  is ok.  ^When th
1d1a0 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
1d1b0 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  ns [SQLITE_DENY]
1d1c0 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  , the.** [sqlite
1d1d0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1d1e0 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61  or equivalent ca
1d1f0 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65  ll that triggere
1d200 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69  d the.** authori
1d210 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69  zer will fail wi
1d220 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  th an error mess
1d230 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74  age explaining t
1d240 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73  hat.** access is
1d250 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20   denied. .**.** 
1d260 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  ^The first param
1d270 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
1d280 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1d290 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
1d2a0 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65   third.** parame
1d2b0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
1d2c0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1d2d0 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e  r() interface. ^
1d2e0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
1d2f0 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63  eter.** to the c
1d300 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
1d310 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f  teger [SQLITE_CO
1d320 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65  PY | action code
1d330 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  ] that specifies
1d340 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c  .** the particul
1d350 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20  ar action to be 
1d360 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65  authorized. ^The
1d370 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73   third through s
1d380 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a  ixth parameters.
1d390 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ** to the callba
1d3a0 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d  ck are zero-term
1d3b0 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74  inated strings t
1d3c0 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69  hat contain addi
1d3d0 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c  tional.** detail
1d3e0 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69  s about the acti
1d3f0 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69  on to be authori
1d400 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  zed..**.** ^If t
1d410 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69  he action code i
1d420 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a  s [SQLITE_READ].
1d430 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62  ** and the callb
1d440 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
1d450 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e  ITE_IGNORE] then
1d460 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
1d470 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61  d statement] sta
1d480 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72  tement is constr
1d490 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 74  ucted to substit
1d4a0 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61  ute.** a NULL va
1d4b0 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20  lue in place of 
1d4c0 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  the table column
1d4d0 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65   that would have
1d4e0 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66  .** been read if
1d4f0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64   [SQLITE_OK] had
1d500 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20   been returned. 
1d510 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e   The [SQLITE_IGN
1d520 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63  ORE].** return c
1d530 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65  an be used to de
1d540 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  ny an untrusted 
1d550 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69  user access to i
1d560 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c  ndividual.** col
1d570 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e  umns of a table.
1d580 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69  .** ^If the acti
1d590 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49  on code is [SQLI
1d5a0 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74  TE_DELETE] and t
1d5b0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
1d5c0 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  rns.** [SQLITE_I
1d5d0 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20  GNORE] then the 
1d5e0 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69  [DELETE] operati
1d5f0 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 20  on proceeds but 
1d600 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65  the.** [truncate
1d610 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69   optimization] i
1d620 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61  s disabled and a
1d630 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65  ll rows are dele
1d640 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79  ted individually
1d650 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f  ..**.** An autho
1d660 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68  rizer is used wh
1d670 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  en [sqlite3_prep
1d680 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d  are | preparing]
1d690 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
1d6a0 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75  ts from an untru
1d6b0 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20  sted source, to 
1d6c0 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  ensure that the 
1d6d0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
1d6e0 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20  * do not try to 
1d6f0 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79  access data they
1d700 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64   are not allowed
1d710 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74   to see, or that
1d720 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20   they do not.** 
1d730 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d  try to execute m
1d740 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65  alicious stateme
1d750 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20  nts that damage 
1d760 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46  the database.  F
1d770 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61  or.** example, a
1d780 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61  n application ma
1d790 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74  y allow a user t
1d7a0 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72  o enter arbitrar
1d7b0 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73  y.** SQL queries
1d7c0 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20   for evaluation 
1d7d0 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20  by a database.  
1d7e0 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74  But the applicat
1d7f0 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20  ion does.** not 
1d800 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f  want the user to
1d810 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65   be able to make
1d820 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67   arbitrary chang
1d830 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74  es to the.** dat
1d840 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f  abase.  An autho
1d850 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e  rizer could then
1d860 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65   be put in place
1d870 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73   while the.** us
1d880 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69  er-entered SQL i
1d890 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33  s being [sqlite3
1d8a0 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61  _prepare | prepa
1d8b0 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73  red] that.** dis
1d8c0 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e  allows everythin
1d8d0 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54  g except [SELECT
1d8e0 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  ] statements..**
1d8f0 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
1d900 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72   that need to pr
1d910 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75  ocess SQL from u
1d920 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73  ntrusted sources
1d930 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63  .** might also c
1d940 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67  onsider lowering
1d950 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73   resource limits
1d960 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1d970 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20  limit()].** and 
1d980 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73  limiting databas
1d990 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65  e size using the
1d9a0 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74   [max_page_count
1d9b0 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e  ] [PRAGMA].** in
1d9c0 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69   addition to usi
1d9d0 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72  ng an authorizer
1d9e0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61  ..**.** ^(Only a
1d9f0 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a   single authoriz
1da00 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61  er can be in pla
1da10 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65  ce on a database
1da20 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61   connection.** a
1da30 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20  t a time.  Each 
1da40 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
1da50 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f  set_authorizer o
1da60 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20  verrides the.** 
1da70 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e  previous call.)^
1da80 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61    ^Disable the a
1da90 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73  uthorizer by ins
1daa0 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63  talling a NULL c
1dab0 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20  allback..** The 
1dac0 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69  authorizer is di
1dad0 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
1dae0 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74  t..**.** The aut
1daf0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1db00 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
1db10 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
1db20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
1db30 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1db40 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
1db50 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1db60 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20  llback..** Note 
1db70 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72  that [sqlite3_pr
1db80 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
1db90 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1dba0 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65   both modify the
1dbb0 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  ir.** database c
1dbc0 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74  onnections for t
1dbd0 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d  he meaning of "m
1dbe0 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70  odify" in this p
1dbf0 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20  aragraph..**.** 
1dc00 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70  ^When [sqlite3_p
1dc10 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20  repare_v2()] is 
1dc20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20  used to prepare 
1dc30 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65  a statement, the
1dc40 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69  .** statement mi
1dc50 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 72  ght be re-prepar
1dc60 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74  ed during [sqlit
1dc70 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74  e3_step()] due t
1dc80 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63  o a .** schema c
1dc90 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74  hange.  Hence, t
1dca0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
1dcb0 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61  hould ensure tha
1dcc0 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74  t the.** correct
1dcd0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1dce0 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20  back remains in 
1dcf0 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65  place during the
1dd00 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1dd10 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74  ]..**.** ^Note t
1dd20 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a  hat the authoriz
1dd30 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
1dd40 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69  nvoked only duri
1dd50 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ng.** [sqlite3_p
1dd60 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73  repare()] or its
1dd70 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68   variants.  Auth
1dd80 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74  orization is not
1dd90 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75  .** performed du
1dda0 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65  ring statement e
1ddb0 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71  valuation in [sq
1ddc0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75  lite3_step()], u
1ddd0 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74  nless.** as stat
1dde0 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  ed in the previo
1ddf0 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73 71  us paragraph, sq
1de00 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76  lite3_step() inv
1de10 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  okes.** sqlite3_
1de20 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20  prepare_v2() to 
1de30 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61 74  reprepare a stat
1de40 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73 63  ement after a sc
1de50 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a  hema change..*/.
1de60 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  int sqlite3_set_
1de70 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71  authorizer(.  sq
1de80 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a  lite3*,.  int (*
1de90 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74  xAuth)(void*,int
1dea0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
1deb0 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
1dec0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
1ded0 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72  ),.  void *pUser
1dee0 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  Data.);../*.** C
1def0 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
1df00 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73  zer Return Codes
1df10 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
1df20 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1df30 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  er | authorizer 
1df40 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1df50 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72  n] must.** retur
1df60 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  n either [SQLITE
1df70 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74  _OK] or one of t
1df80 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e  hese two constan
1df90 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74  ts in order.** t
1dfa0 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20  o signal SQLite 
1dfb0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
1dfc0 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72  he action is per
1dfd0 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65  mitted.  See the
1dfe0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  .** [sqlite3_set
1dff0 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
1e000 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e  thorizer documen
1e010 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69  tation] for addi
1e020 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d  tional.** inform
1e030 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  ation..**.** Not
1e040 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49 47  e that SQLITE_IG
1e050 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73 65  NORE is also use
1e060 64 20 61 73 20 61 20 5b 53 51 4c 49 54 45 5f 52  d as a [SQLITE_R
1e070 4f 4c 4c 42 41 43 4b 20 7c 20 72 65 74 75 72 6e  OLLBACK | return
1e080 20 63 6f 64 65 5d 0a 2a 2a 20 66 72 6f 6d 20 74   code].** from t
1e090 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62  he [sqlite3_vtab
1e0a0 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20  _on_conflict()] 
1e0b0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64  interface..*/.#d
1e0c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e  efine SQLITE_DEN
1e0d0 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74  Y   1   /* Abort
1e0e0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
1e0f0 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  nt with an error
1e100 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1e110 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a  TE_IGNORE 2   /*
1e120 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63   Don't allow acc
1e130 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67  ess, but don't g
1e140 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72  enerate an error
1e150 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
1e160 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20  REF: Authorizer 
1e170 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a  Action Codes.**.
1e180 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
1e190 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
1e1a0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ] interface regi
1e1b0 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
1e1c0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61   function.** tha
1e1d0 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20  t is invoked to 
1e1e0 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69  authorize certai
1e1f0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
1e200 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a  actions.  The.**
1e210 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1e220 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  r to the callbac
1e230 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  k is an integer 
1e240 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 66  code that specif
1e250 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69  ies.** what acti
1e260 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 68  on is being auth
1e270 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61  orized.  These a
1e280 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 61  re the integer a
1e290 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74  ction codes that
1e2a0 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a  .** the authoriz
1e2b0 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20  er callback may 
1e2c0 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a  be passed..**.**
1e2d0 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f   These action co
1e2e0 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66  de values signif
1e2f0 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f  y what kind of o
1e300 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62  peration is to b
1e310 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e  e.** authorized.
1e320 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74    The 3rd and 4t
1e330 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  h parameters to 
1e340 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f  the authorizatio
1e350 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75  n.** callback fu
1e360 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70  nction will be p
1e370 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c  arameters or NUL
1e380 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77  L depending on w
1e390 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a  hich of these.**
1e3a0 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 61   codes is used a
1e3b0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
1e3c0 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35  ameter.  ^(The 5
1e3d0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
1e3e0 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65  the.** authorize
1e3f0 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68  r callback is th
1e400 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  e name of the da
1e410 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20  tabase ("main", 
1e420 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29  "temp",.** etc.)
1e430 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29   if applicable.)
1e440 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61 72 61  ^  ^The 6th para
1e450 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
1e460 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1e470 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20  .** is the name 
1e480 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73  of the inner-mos
1e490 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65  t trigger or vie
1e4a0 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e  w that is respon
1e4b0 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65  sible for.** the
1e4c0 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
1e4d0 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20  or NULL if this 
1e4e0 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69  access attempt i
1e4f0 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a  s directly from.
1e500 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c  ** top-level SQL
1e510 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a   code..*/./*****
1e520 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1e530 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1e540 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a  ****** 3rd *****
1e550 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a  ******* 4th ****
1e560 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65  *******/.#define
1e570 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49   SQLITE_CREATE_I
1e580 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20  NDEX          1 
1e590 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
1e5a0 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
1e5b0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1e5c0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41  SQLITE_CREATE_TA
1e5d0 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20  BLE          2  
1e5e0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1e5f0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1e600 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1e610 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
1e620 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20  P_INDEX     3   
1e630 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
1e640 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1e650 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1e660 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
1e670 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f  _TABLE     4   /
1e680 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1e690 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1e6a0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1e6b0 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
1e6c0 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a  TRIGGER   5   /*
1e6d0 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
1e6e0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1e6f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1e700 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56  TE_CREATE_TEMP_V
1e710 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20  IEW      6   /* 
1e720 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
1e730 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1e740 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1e750 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52  E_CREATE_TRIGGER
1e760 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54          7   /* T
1e770 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
1e780 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1e790 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1e7a0 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20  _CREATE_VIEW    
1e7b0 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69         8   /* Vi
1e7c0 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
1e7d0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1e7e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1e7f0 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20  DELETE          
1e800 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62        9   /* Tab
1e810 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1e820 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1e830 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1e840 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20  ROP_INDEX       
1e850 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65      10   /* Inde
1e860 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
1e870 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1e880 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1e890 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  OP_TABLE        
1e8a0 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65     11   /* Table
1e8b0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1e8c0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1e8d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1e8e0 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20  P_TEMP_INDEX    
1e8f0 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20    12   /* Index 
1e900 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
1e910 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1e920 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1e930 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20  _TEMP_TABLE     
1e940 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   13   /* Table N
1e950 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1e960 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1e970 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1e980 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20  TEMP_TRIGGER    
1e990 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20  14   /* Trigger 
1e9a0 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
1e9b0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1e9c0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
1e9d0 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31  EMP_VIEW       1
1e9e0 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  5   /* View Name
1e9f0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1ea00 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1ea10 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52  e SQLITE_DROP_TR
1ea20 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36  IGGER         16
1ea30 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
1ea40 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
1ea50 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1ea60 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45   SQLITE_DROP_VIE
1ea70 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20  W            17 
1ea80 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
1ea90 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1eaa0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1eab0 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20  SQLITE_INSERT   
1eac0 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20              18  
1ead0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1eae0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1eaf0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1eb00 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20  QLITE_PRAGMA    
1eb10 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20             19   
1eb20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20  /* Pragma Name  
1eb30 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55     1st arg or NU
1eb40 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  LL */.#define SQ
1eb50 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20  LITE_READ       
1eb60 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f            20   /
1eb70 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1eb80 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20    Column Name   
1eb90 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1eba0 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20  ITE_SELECT      
1ebb0 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a           21   /*
1ebc0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1ebd0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1ebe0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1ebf0 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20  TE_TRANSACTION  
1ec00 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20          22   /* 
1ec10 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20  Operation       
1ec20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1ec30 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1ec40 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20  E_UPDATE        
1ec50 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54         23   /* T
1ec60 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43  able Name      C
1ec70 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a  olumn Name     *
1ec80 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1ec90 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20  _ATTACH         
1eca0 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69        24   /* Fi
1ecb0 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55  lename        NU
1ecc0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1ecd0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1ece0 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20  DETACH          
1ecf0 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74       25   /* Dat
1ed00 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c  abase Name   NUL
1ed10 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1ed20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
1ed30 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20  LTER_TABLE      
1ed40 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61      26   /* Data
1ed50 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c  base Name   Tabl
1ed60 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1ed70 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
1ed80 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20  INDEX           
1ed90 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78     27   /* Index
1eda0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1edb0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1edc0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41  efine SQLITE_ANA
1edd0 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20  LYZE            
1ede0 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20    28   /* Table 
1edf0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1ee00 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1ee10 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1ee20 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20  TE_VTABLE       
1ee30 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   29   /* Table N
1ee40 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20  ame      Module 
1ee50 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
1ee60 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1ee70 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  VTABLE          
1ee80 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  30   /* Table Na
1ee90 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e  me      Module N
1eea0 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
1eeb0 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49  ne SQLITE_FUNCTI
1eec0 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33  ON             3
1eed0 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  1   /* NULL     
1eee0 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20         Function 
1eef0 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e  Name   */.#defin
1ef00 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49  e SQLITE_SAVEPOI
1ef10 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 33 32  NT            32
1ef20 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20     /* Operation 
1ef30 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20        Savepoint 
1ef40 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65  Name  */.#define
1ef50 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20   SQLITE_COPY    
1ef60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20                0 
1ef70 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75    /* No longer u
1ef80 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  sed */../*.** CA
1ef90 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20  PI3REF: Tracing 
1efa0 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75  And Profiling Fu
1efb0 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  nctions.**.** Th
1efc0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67  ese routines reg
1efd0 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66  ister callback f
1efe0 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61  unctions that ca
1eff0 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a  n be used for.**
1f000 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f   tracing and pro
1f010 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75  filing the execu
1f020 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74  tion of SQL stat
1f030 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ements..**.** ^T
1f040 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
1f050 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
1f060 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  by sqlite3_trace
1f070 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74  () is invoked at
1f080 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65  .** various time
1f090 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74  s when an SQL st
1f0a0 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67  atement is being
1f0b0 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33   run by [sqlite3
1f0c0 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68  _step()]..** ^Th
1f0d0 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  e sqlite3_trace(
1f0e0 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  ) callback is in
1f0f0 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 46  voked with a UTF
1f100 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  -8 rendering of 
1f110 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  the.** SQL state
1f120 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 65  ment text as the
1f130 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74   statement first
1f140 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e   begins executin
1f150 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e  g..** ^(Addition
1f160 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  al sqlite3_trace
1f170 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67  () callbacks mig
1f180 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65  ht occur.** as e
1f190 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75  ach triggered su
1f1a0 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65  bprogram is ente
1f1b0 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61  red.  The callba
1f1c0 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73  cks for triggers
1f1d0 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54  .** contain a UT
1f1e0 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20  F-8 SQL comment 
1f1f0 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20  that identifies 
1f200 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a  the trigger.)^.*
1f210 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
1f220 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49  _TRACE_SIZE_LIMI
1f230 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  T] compile-time 
1f240 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
1f250 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74  ed to limit.** t
1f260 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f  he length of [bo
1f270 75 6e 64 20 70 61 72 61 6d 65 74 65 72 5d 20 65  und parameter] e
1f280 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20  xpansion in the 
1f290 6f 75 74 70 75 74 20 6f 66 20 73 71 6c 69 74 65  output of sqlite
1f2a0 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a  3_trace()..**.**
1f2b0 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66   ^The callback f
1f2c0 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
1f2d0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72  ed by sqlite3_pr
1f2e0 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b  ofile() is invok
1f2f0 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51  ed.** as each SQ
1f300 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69  L statement fini
1f310 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66  shes.  ^The prof
1f320 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e  ile callback con
1f330 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69  tains.** the ori
1f340 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20  ginal statement 
1f350 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69  text and an esti
1f360 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f  mate of wall-clo
1f370 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f  ck time.** of ho
1f380 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74  w long that stat
1f390 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75  ement took to ru
1f3a0 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65  n.  ^The profile
1f3b0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d   callback.** tim
1f3c0 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66  e is in units of
1f3d0 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f   nanoseconds, ho
1f3e0 77 65 76 65 72 20 74 68 65 20 63 75 72 72 65 6e  wever the curren
1f3f0 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  t implementation
1f400 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61  .** is only capa
1f410 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ble of milliseco
1f420 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f  nd resolution so
1f430 20 74 68 65 20 73 69 78 20 6c 65 61 73 74 20 73   the six least s
1f440 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69  ignificant.** di
1f450 67 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65  gits in the time
1f460 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73   are meaningless
1f470 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
1f480 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  ns of SQLite.** 
1f490 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20 67 72  might provide gr
1f4a0 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e  eater resolution
1f4b0 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72   on the profiler
1f4c0 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a   callback.  The.
1f4d0 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  ** sqlite3_profi
1f4e0 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  le() function is
1f4f0 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65   considered expe
1f500 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a  rimental and is.
1f510 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  ** subject to ch
1f520 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 76  ange in future v
1f530 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
1f540 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  e..*/.void *sqli
1f550 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65  te3_trace(sqlite
1f560 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65  3*, void(*xTrace
1f570 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
1f580 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51  ar*), void*);.SQ
1f590 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41  LITE_EXPERIMENTA
1f5a0 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  L void *sqlite3_
1f5b0 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a  profile(sqlite3*
1f5c0 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66  ,.   void(*xProf
1f5d0 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74  ile)(void*,const
1f5e0 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75   char*,sqlite3_u
1f5f0 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a  int64), void*);.
1f600 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1f610 20 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20   Query Progress 
1f620 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20  Callbacks.**.** 
1f630 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f  ^The sqlite3_pro
1f640 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c  gress_handler(D,
1f650 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65  N,X,P) interface
1f660 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c   causes the call
1f670 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  back.** function
1f680 20 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64   X to be invoked
1f690 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75   periodically du
1f6a0 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e  ring long runnin
1f6b0 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73  g calls to.** [s
1f6c0 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20  qlite3_exec()], 
1f6d0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1f6e0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65   and [sqlite3_ge
1f6f0 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a  t_table()] for.*
1f700 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
1f710 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61  ction D.  An exa
1f720 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69  mple use for thi
1f730 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  s.** interface i
1f740 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20  s to keep a GUI 
1f750 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61  updated during a
1f760 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a   large query..**
1f770 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74  .** ^The paramet
1f780 65 72 20 50 20 69 73 20 70 61 73 73 65 64 20 74  er P is passed t
1f790 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e  hrough as the on
1f7a0 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ly parameter to 
1f7b0 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  the .** callback
1f7c0 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54   function X.  ^T
1f7d0 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69  he parameter N i
1f7e0 73 20 74 68 65 20 61 70 70 72 6f 78 69 6d 61 74  s the approximat
1f7f0 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20  e number of .** 
1f800 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65  [virtual machine
1f810 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74   instructions] t
1f820 68 61 74 20 61 72 65 20 65 76 61 6c 75 61 74 65  hat are evaluate
1f830 64 20 62 65 74 77 65 65 6e 20 73 75 63 63 65 73  d between succes
1f840 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  sive.** invocati
1f850 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62  ons of the callb
1f860 61 63 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69 73  ack X.  ^If N is
1f870 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 74   less than one t
1f880 68 65 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73  hen the progress
1f890 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69 73 20 64  .** handler is d
1f8a0 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  isabled..**.** ^
1f8b0 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72  Only a single pr
1f8c0 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d  ogress handler m
1f8d0 61 79 20 62 65 20 64 65 66 69 6e 65 64 20 61 74  ay be defined at
1f8e0 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a   one time per.**
1f8f0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1f900 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20  ction]; setting 
1f910 61 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68  a new progress h
1f920 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74  andler cancels t
1f930 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20  he.** old one.  
1f940 5e 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74  ^Setting paramet
1f950 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73  er X to NULL dis
1f960 61 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65  ables the progre
1f970 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e  ss handler..** ^
1f980 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  The progress han
1f990 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73  dler is also dis
1f9a0 61 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67  abled by setting
1f9b0 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65   N to a value le
1f9c0 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a  ss.** than 1..**
1f9d0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67  .** ^If the prog
1f9e0 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65  ress callback re
1f9f0 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
1fa00 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  the operation is
1fa10 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e  .** interrupted.
1fa20 20 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63    This feature c
1fa30 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d  an be used to im
1fa40 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61  plement a.** "Ca
1fa50 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20  ncel" button on 
1fa60 61 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 64  a GUI progress d
1fa70 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a  ialog box..**.**
1fa80 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   The progress ha
1fa90 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  ndler callback m
1faa0 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
1fab0 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
1fac0 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
1fad0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1fae0 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
1faf0 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
1fb00 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  r..** Note that 
1fb10 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1fb20 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
1fb30 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
1fb40 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
1fb50 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1fb60 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
1fb70 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
1fb80 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
1fb90 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20  aph..**.*/.void 
1fba0 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
1fbb0 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
1fbc0 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76  *, int, int(*)(v
1fbd0 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  oid*), void*);..
1fbe0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1fbf0 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61  Opening A New Da
1fc00 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
1fc10 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  n.**.** ^These r
1fc20 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20  outines open an 
1fc30 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20  SQLite database 
1fc40 66 69 6c 65 20 61 73 20 73 70 65 63 69 66 69 65  file as specifie
1fc50 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c  d by the .** fil
1fc60 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20  ename argument. 
1fc70 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72  ^The filename ar
1fc80 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70  gument is interp
1fc90 72 65 74 65 64 20 61 73 20 55 54 46 2d 38 20 66  reted as UTF-8 f
1fca0 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  or.** sqlite3_op
1fcb0 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  en() and sqlite3
1fcc0 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61  _open_v2() and a
1fcd0 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20  s UTF-16 in the 
1fce0 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f  native byte.** o
1fcf0 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33  rder for sqlite3
1fd00 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b  _open16(). ^(A [
1fd10 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1fd20 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75  ion] handle is u
1fd30 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e  sually.** return
1fd40 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65  ed in *ppDb, eve
1fd50 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63  n if an error oc
1fd60 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20  curs.  The only 
1fd70 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61  exception is tha
1fd80 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69  t.** if SQLite i
1fd90 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
1fda0 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68  cate memory to h
1fdb0 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  old the [sqlite3
1fdc0 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e  ] object,.** a N
1fdd0 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74  ULL will be writ
1fde0 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69  ten into *ppDb i
1fdf0 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e  nstead of a poin
1fe00 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
1fe10 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29  te3].** object.)
1fe20 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74 61 62  ^ ^(If the datab
1fe30 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61  ase is opened (a
1fe40 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73  nd/or created) s
1fe50 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65  uccessfully, the
1fe60 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  n.** [SQLITE_OK]
1fe70 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f   is returned.  O
1fe80 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72  therwise an [err
1fe90 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
1fea0 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20  rned.)^ ^The.** 
1feb0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
1fec0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65  )] or [sqlite3_e
1fed0 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69  rrmsg16()] routi
1fee0 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  nes can be used 
1fef0 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20  to obtain.** an 
1ff00 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65  English language
1ff10 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20   description of 
1ff20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77  the error follow
1ff30 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66  ing a failure of
1ff40 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73   any.** of the s
1ff50 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f  qlite3_open() ro
1ff60 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  utines..**.** ^T
1ff70 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64  he default encod
1ff80 69 6e 67 20 66 6f 72 20 74 68 65 20 64 61 74 61  ing for the data
1ff90 62 61 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46  base will be UTF
1ffa0 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33  -8 if.** sqlite3
1ffb0 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
1ffc0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
1ffd0 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54  called and.** UT
1ffe0 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69  F-16 in the nati
1fff0 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 66  ve byte order if
20000 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
20010 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  ) is used..**.**
20020 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   Whether or not 
20030 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
20040 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65  when it is opene
20050 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20  d, resources.** 
20060 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
20070 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
20080 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
20090 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61   should be relea
200a0 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e  sed by.** passin
200b0 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  g it to [sqlite3
200c0 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69  _close()] when i
200d0 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72  t is no longer r
200e0 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  equired..**.** T
200f0 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  he sqlite3_open_
20100 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77  v2() interface w
20110 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65  orks like sqlite
20120 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65  3_open().** exce
20130 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65 70  pt that it accep
20140 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61  ts two additiona
20150 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72  l parameters for
20160 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74   additional cont
20170 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20  rol.** over the 
20180 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
20190 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20  nection.  ^(The 
201a0 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
201b0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  to.** sqlite3_op
201c0 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65  en_v2() can take
201d0 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66   one of.** the f
201e0 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76  ollowing three v
201f0 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c  alues, optionall
20200 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20  y combined with 
20210 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  the .** [SQLITE_
20220 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b  OPEN_NOMUTEX], [
20230 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
20240 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f  MUTEX], [SQLITE_
20250 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
20260 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  ],.** [SQLITE_OP
20270 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d  EN_PRIVATECACHE]
20280 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45  , and/or [SQLITE
20290 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73  _OPEN_URI] flags
202a0 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  :)^.**.** <dl>.*
202b0 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  * ^(<dt>[SQLITE_
202c0 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f  OPEN_READONLY]</
202d0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
202e0 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
202f0 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d  d in read-only m
20300 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 74  ode.  If the dat
20310 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a  abase does not.*
20320 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c  * already exist,
20330 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74   an error is ret
20340 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  urned.</dd>)^.**
20350 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54  .** ^(<dt>[SQLIT
20360 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
20370 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
20380 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
20390 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67  ened for reading
203a0 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20   and writing if 
203b0 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61  possible, or rea
203c0 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20  ding.** only if 
203d0 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 74  the file is writ
203e0 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 74  e protected by t
203f0 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
20400 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a  tem.  In either.
20410 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74 61  ** case the data
20420 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64  base must alread
20430 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69  y exist, otherwi
20440 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72  se an error is r
20450 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a  eturned.</dd>)^.
20460 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  **.** ^(<dt>[SQL
20470 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
20480 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50  TE] | [SQLITE_OP
20490 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a  EN_CREATE]</dt>.
204a0 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
204b0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
204c0 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72  r reading and wr
204d0 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72  iting, and is cr
204e0 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 64  eated if.** it d
204f0 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20  oes not already 
20500 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 74  exist. This is t
20510 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 74  he behavior that
20520 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20   is always used 
20530 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
20540 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  pen() and sqlite
20550 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e  3_open16().</dd>
20560 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a  )^.** </dl>.**.*
20570 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72  * If the 3rd par
20580 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
20590 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e  3_open_v2() is n
205a0 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a  ot one of the.**
205b0 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68   combinations sh
205c0 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e  own above option
205d0 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69  ally combined wi
205e0 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c  th other.** [SQL
205f0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
20600 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  Y | SQLITE_OPEN_
20610 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20  * bits].** then 
20620 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
20630 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
20640 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
20650 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66  _OPEN_NOMUTEX] f
20660 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e  lag is set, then
20670 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
20680 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e  nnection.** open
20690 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74  s in the multi-t
206a0 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67  hread [threading
206b0 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61   mode] as long a
206c0 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72  s the single-thr
206d0 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20  ead.** mode has 
206e0 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 20  not been set at 
206f0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20  compile-time or 
20700 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66  start-time.  ^If
20710 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
20720 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20  OPEN_FULLMUTEX] 
20730 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 65 6e  flag is set then
20740 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
20750 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a  nnection opens.*
20760 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69  * in the seriali
20770 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
20780 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67  ode] unless sing
20790 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a  le-thread was.**
207a0 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65   previously sele
207b0 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d  cted at compile-
207c0 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69  time or start-ti
207d0 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  me..** ^The [SQL
207e0 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
207f0 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65  ACHE] flag cause
20800 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
20810 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a  onnection to be.
20820 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75  ** eligible to u
20830 73 65 20 5b 73 68 61 72 65 64 20 63 61 63 68 65  se [shared cache
20840 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65   mode], regardle
20850 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
20860 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63   not shared.** c
20870 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20  ache is enabled 
20880 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65  using [sqlite3_e
20890 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63  nable_shared_cac
208a0 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20  he()].  ^The.** 
208b0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49  [SQLITE_OPEN_PRI
208c0 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20  VATECACHE] flag 
208d0 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62  causes the datab
208e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
208f0 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69  o not.** partici
20900 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20  pate in [shared 
20910 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e  cache mode] even
20920 20 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65   if it is enable
20930 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f  d..**.** ^The fo
20940 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
20950 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
20960 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20  2() is the name 
20970 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
20980 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74  e3_vfs] object t
20990 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  hat defines the 
209a0 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
209b0 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a   interface that.
209c0 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62  ** the new datab
209d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73  ase connection s
209e0 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20  hould use.  ^If 
209f0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
20a00 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c  eter is.** a NUL
20a10 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74  L pointer then t
20a20 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
20a30 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
20a40 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  is used..**.** ^
20a50 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  If the filename 
20a60 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74  is ":memory:", t
20a70 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
20a80 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f  emporary in-memo
20a90 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69  ry database.** i
20aa0 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68  s created for th
20ab0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e  e connection.  ^
20ac0 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64  This in-memory d
20ad0 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e  atabase will van
20ae0 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20  ish when.** the 
20af0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
20b00 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20  ion is closed.  
20b10 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
20b20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a  of SQLite might.
20b30 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61  ** make use of a
20b40 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61  dditional specia
20b50 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74  l filenames that
20b60 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20   begin with the 
20b70 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ":" character..*
20b80 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  * It is recommen
20b90 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20  ded that when a 
20ba0 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  database filenam
20bb0 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20  e actually does 
20bc0 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20  begin with.** a 
20bd0 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f  ":" character yo
20be0 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20  u should prefix 
20bf0 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74  the filename wit
20c00 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63  h a pathname suc
20c10 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20  h as.** "./" to 
20c20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e  avoid ambiguity.
20c30 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .**.** ^If the f
20c40 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d  ilename is an em
20c50 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  pty string, then
20c60 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70   a private, temp
20c70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b  orary.** on-disk
20c80 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
20c90 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69  e created.  ^Thi
20ca0 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62 61  s private databa
20cb0 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75  se will be.** au
20cc0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65  tomatically dele
20cd0 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74  ted as soon as t
20ce0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
20cf0 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
20d00 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69  ..**.** [[URI fi
20d10 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69 74  lenames in sqlit
20d20 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e  e3_open()]] <h3>
20d30 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68  URI Filenames</h
20d40 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52  3>.**.** ^If [UR
20d50 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65  I filename] inte
20d60 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e  rpretation is en
20d70 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20 66  abled, and the f
20d80 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
20d90 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68 20  .** begins with 
20da0 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68  "file:", then th
20db0 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e  e filename is in
20dc0 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 55  terpreted as a U
20dd0 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65  RI. ^URI.** file
20de0 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74  name interpretat
20df0 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20 69  ion is enabled i
20e00 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
20e10 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 0a  EN_URI] flag is.
20e20 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20 66 6f  ** set in the fo
20e30 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  urth argument to
20e40 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
20e50 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61 73  (), or if it has
20e60 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 64  .** been enabled
20e70 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20   globally using 
20e80 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  the [SQLITE_CONF
20e90 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77  IG_URI] option w
20ea0 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ith the.** [sqli
20eb0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65  te3_config()] me
20ec0 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20 5b  thod or by the [
20ed0 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20  SQLITE_USE_URI] 
20ee0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
20ef0 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51  ion..** As of SQ
20f00 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37  Lite version 3.7
20f10 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  .7, URI filename
20f20 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
20f30 69 73 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a  is turned off.**
20f40 20 62 79 20 64 65 66 61 75 6c 74 2c 20 62 75 74   by default, but
20f50 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
20f60 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
20f70 20 65 6e 61 62 6c 65 20 55 52 49 20 66 69 6c 65   enable URI file
20f80 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65  name.** interpre
20f90 74 61 74 69 6f 6e 20 62 79 20 64 65 66 61 75 6c  tation by defaul
20fa0 74 2e 20 20 53 65 65 20 22 5b 55 52 49 20 66 69  t.  See "[URI fi
20fb0 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61 64  lenames]" for ad
20fc0 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f  ditional.** info
20fd0 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55  rmation..**.** U
20fe0 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65  RI filenames are
20ff0 20 70 61 72 73 65 64 20 61 63 63 6f 72 64 69 6e   parsed accordin
21000 67 20 74 6f 20 52 46 43 20 33 39 38 36 2e 20 5e  g to RFC 3986. ^
21010 49 66 20 74 68 65 20 55 52 49 20 63 6f 6e 74 61  If the URI conta
21020 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72  ins an.** author
21030 69 74 79 2c 20 74 68 65 6e 20 69 74 20 6d 75 73  ity, then it mus
21040 74 20 62 65 20 65 69 74 68 65 72 20 61 6e 20 65  t be either an e
21050 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 74  mpty string or t
21060 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c  he string .** "l
21070 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74  ocalhost". ^If t
21080 68 65 20 61 75 74 68 6f 72 69 74 79 20 69 73 20  he authority is 
21090 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 74 72  not an empty str
210a0 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73  ing or "localhos
210b0 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72  t", an .** error
210c0 20 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20   is returned to 
210d0 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65  the caller. ^The
210e0 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e   fragment compon
210f0 65 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 69 66  ent of a URI, if
21100 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69 73   .** present, is
21110 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20   ignored..**.** 
21120 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65  ^SQLite uses the
21130 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20   path component 
21140 6f 66 20 74 68 65 20 55 52 49 20 61 73 20 74 68  of the URI as th
21150 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 69  e name of the di
21160 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68  sk file.** which
21170 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61   contains the da
21180 74 61 62 61 73 65 2e 20 5e 49 66 20 74 68 65 20  tabase. ^If the 
21190 70 61 74 68 20 62 65 67 69 6e 73 20 77 69 74 68  path begins with
211a0 20 61 20 27 2f 27 20 63 68 61 72 61 63 74 65 72   a '/' character
211b0 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73  , .** then it is
211c0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
211d0 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68  an absolute path
211e0 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 64  . ^If the path d
211f0 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a  oes not begin .*
21200 2a 20 77 69 74 68 20 61 20 27 2f 27 20 28 6d 65  * with a '/' (me
21210 61 6e 69 6e 67 20 74 68 61 74 20 74 68 65 20 61  aning that the a
21220 75 74 68 6f 72 69 74 79 20 73 65 63 74 69 6f 6e  uthority section
21230 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
21240 20 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 68 65   the URI).** the
21250 6e 20 74 68 65 20 70 61 74 68 20 69 73 20 69 6e  n the path is in
21260 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 72  terpreted as a r
21270 65 6c 61 74 69 76 65 20 70 61 74 68 2e 20 0a 2a  elative path. .*
21280 2a 20 5e 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74  * ^On windows, t
21290 68 65 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65  he first compone
212a0 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74  nt of an absolut
212b0 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 20 61 20  e path .** is a 
212c0 64 72 69 76 65 20 73 70 65 63 69 66 69 63 61 74  drive specificat
212d0 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e  ion (e.g. "C:").
212e0 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52  .**.** [[core UR
212f0 49 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  I query paramete
21300 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72  rs]].** The quer
21310 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  y component of a
21320 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e   URI may contain
21330 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 74   parameters that
21340 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
21350 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 20 53 51  .** either by SQ
21360 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 6f 72 20  Lite itself, or 
21370 62 79 20 61 20 5b 56 46 53 20 7c 20 63 75 73 74  by a [VFS | cust
21380 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  om VFS implement
21390 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74  ation]..** SQLit
213a0 65 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65  e interprets the
213b0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65   following three
213c0 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
213d0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
213e0 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f     <li> <b>vfs</
213f0 62 3e 3a 20 5e 54 68 65 20 22 76 66 73 22 20 70  b>: ^The "vfs" p
21400 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
21410 75 73 65 64 20 74 6f 20 73 70 65 63 69 66 79 20  used to specify 
21420 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20  the name of.**  
21430 20 20 20 61 20 56 46 53 20 6f 62 6a 65 63 74 20     a VFS object 
21440 74 68 61 74 20 70 72 6f 76 69 64 65 73 20 74 68  that provides th
21450 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
21460 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  em interface tha
21470 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20  t should.**     
21480 62 65 20 75 73 65 64 20 74 6f 20 61 63 63 65 73  be used to acces
21490 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  s the database f
214a0 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66  ile on disk. ^If
214b0 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20   this option is 
214c0 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e  set to.**     an
214d0 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 74 68   empty string th
214e0 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 6f 62  e default VFS ob
214f0 6a 65 63 74 20 69 73 20 75 73 65 64 2e 20 5e 53  ject is used. ^S
21500 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b  pecifying an unk
21510 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20  nown.**     VFS 
21520 69 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66  is an error. ^If
21530 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
21540 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74  () is used and t
21550 68 65 20 76 66 73 20 6f 70 74 69 6f 6e 20 69 73  he vfs option is
21560 0a 2a 2a 20 20 20 20 20 70 72 65 73 65 6e 74 2c  .**     present,
21570 20 74 68 65 6e 20 74 68 65 20 56 46 53 20 73 70   then the VFS sp
21580 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f  ecified by the o
21590 70 74 69 6f 6e 20 74 61 6b 65 73 20 70 72 65 63  ption takes prec
215a0 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20  edence over.**  
215b0 20 20 20 74 68 65 20 76 61 6c 75 65 20 70 61 73     the value pas
215c0 73 65 64 20 61 73 20 74 68 65 20 66 6f 75 72 74  sed as the fourt
215d0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
215e0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
215f0 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c  ..**.**   <li> <
21600 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68  b>mode</b>: ^(Th
21610 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72  e mode parameter
21620 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65   may be set to e
21630 69 74 68 65 72 20 22 72 6f 22 2c 20 22 72 77 22  ither "ro", "rw"
21640 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63 22 2c 20  ,.**     "rwc", 
21650 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74  or "memory". Att
21660 65 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 20 69  empting to set i
21670 74 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 76  t to any other v
21680 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20 20 20 61  alue is.**     a
21690 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20  n error)^. .**  
216a0 20 20 20 5e 49 66 20 22 72 6f 22 20 69 73 20 73     ^If "ro" is s
216b0 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20 74  pecified, then t
216c0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
216d0 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 6f  pened for read-o
216e0 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63 63 65  nly .**     acce
216f0 73 73 2c 20 6a 75 73 74 20 61 73 20 69 66 20 74  ss, just as if t
21700 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
21710 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68  READONLY] flag h
21720 61 64 20 62 65 65 6e 20 73 65 74 20 69 6e 20 74  ad been set in t
21730 68 65 20 0a 2a 2a 20 20 20 20 20 74 68 69 72 64  he .**     third
21740 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
21750 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20  ite3_open_v2(). 
21760 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74  ^If the mode opt
21770 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 20 0a 2a  ion is set to .*
21780 2a 20 20 20 20 20 22 72 77 22 2c 20 74 68 65 6e  *     "rw", then
21790 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
217a0 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
217b0 2d 77 72 69 74 65 20 28 62 75 74 20 6e 6f 74 20  -write (but not 
217c0 63 72 65 61 74 65 29 20 0a 2a 2a 20 20 20 20 20  create) .**     
217d0 61 63 63 65 73 73 2c 20 61 73 20 69 66 20 53 51  access, as if SQ
217e0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
217f0 49 54 45 20 28 62 75 74 20 6e 6f 74 20 53 51 4c  ITE (but not SQL
21800 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29  ITE_OPEN_CREATE)
21810 20 68 61 64 20 0a 2a 2a 20 20 20 20 20 62 65 65   had .**     bee
21820 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65 20 22 72  n set. ^Value "r
21830 77 63 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e  wc" is equivalen
21840 74 20 74 6f 20 73 65 74 74 69 6e 67 20 62 6f 74  t to setting bot
21850 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45  h .**     SQLITE
21860 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20  _OPEN_READWRITE 
21870 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  and SQLITE_OPEN_
21880 43 52 45 41 54 45 2e 20 20 5e 49 66 20 74 68 65  CREATE.  ^If the
21890 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a   mode option is.
218a0 2a 2a 20 20 20 20 20 73 65 74 20 74 6f 20 22 6d  **     set to "m
218b0 65 6d 6f 72 79 22 20 74 68 65 6e 20 61 20 70 75  emory" then a pu
218c0 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61  re [in-memory da
218d0 74 61 62 61 73 65 5d 20 74 68 61 74 20 6e 65 76  tabase] that nev
218e0 65 72 20 72 65 61 64 73 0a 2a 2a 20 20 20 20 20  er reads.**     
218f0 6f 72 20 77 72 69 74 65 73 20 66 72 6f 6d 20 64  or writes from d
21900 69 73 6b 20 69 73 20 75 73 65 64 2e 20 5e 49 74  isk is used. ^It
21910 20 69 73 20 61 6e 20 65 72 72 6f 72 20 74 6f 20   is an error to 
21920 73 70 65 63 69 66 79 20 61 20 76 61 6c 75 65 20  specify a value 
21930 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d  for.**     the m
21940 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 74 68  ode parameter th
21950 61 74 20 69 73 20 6c 65 73 73 20 72 65 73 74 72  at is less restr
21960 69 63 74 69 76 65 20 74 68 61 6e 20 74 68 61 74  ictive than that
21970 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a   specified by.**
21980 20 20 20 20 20 74 68 65 20 66 6c 61 67 73 20 70       the flags p
21990 61 73 73 65 64 20 69 6e 20 74 68 65 20 74 68 69  assed in the thi
219a0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
219b0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
219c0 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20  )..**.**   <li> 
219d0 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54  <b>cache</b>: ^T
219e0 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74  he cache paramet
219f0 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f  er may be set to
21a00 20 65 69 74 68 65 72 20 22 73 68 61 72 65 64 22   either "shared"
21a10 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72 69 76   or.**     "priv
21a20 61 74 65 22 2e 20 5e 53 65 74 74 69 6e 67 20 69  ate". ^Setting i
21a30 74 20 74 6f 20 22 73 68 61 72 65 64 22 20 69 73  t to "shared" is
21a40 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73   equivalent to s
21a50 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20  etting the.**   
21a60 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48    SQLITE_OPEN_SH
21a70 41 52 45 44 43 41 43 48 45 20 62 69 74 20 69 6e  AREDCACHE bit in
21a80 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   the flags argum
21a90 65 6e 74 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a  ent passed to.**
21aa0 20 20 20 20 20 73 71 6c 69 74 65 33 5f 6f 70 65       sqlite3_ope
21ab0 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74 69 6e 67  n_v2(). ^Setting
21ac0 20 74 68 65 20 63 61 63 68 65 20 70 61 72 61 6d   the cache param
21ad0 65 74 65 72 20 74 6f 20 22 70 72 69 76 61 74 65  eter to "private
21ae0 22 20 69 73 20 0a 2a 2a 20 20 20 20 20 65 71 75  " is .**     equ
21af0 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69  ivalent to setti
21b00 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50  ng the SQLITE_OP
21b10 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20  EN_PRIVATECACHE 
21b20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20  bit..**     ^If 
21b30 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
21b40 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68  ) is used and th
21b50 65 20 22 63 61 63 68 65 22 20 70 61 72 61 6d 65  e "cache" parame
21b60 74 65 72 20 69 73 20 70 72 65 73 65 6e 74 20 69  ter is present i
21b70 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52 49 20 66  n.**     a URI f
21b80 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c  ilename, its val
21b90 75 65 20 6f 76 65 72 72 69 64 65 73 20 61 6e 79  ue overrides any
21ba0 20 62 65 68 61 76 69 6f 72 20 72 65 71 75 65 73   behavior reques
21bb0 74 65 64 20 62 79 20 73 65 74 74 69 6e 67 0a 2a  ted by setting.*
21bc0 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45  *     SQLITE_OPE
21bd0 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 6f  N_PRIVATECACHE o
21be0 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48  r SQLITE_OPEN_SH
21bf0 41 52 45 44 43 41 43 48 45 20 66 6c 61 67 2e 0a  AREDCACHE flag..
21c00 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e  ** </ul>.**.** ^
21c10 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e  Specifying an un
21c20 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20  known parameter 
21c30 69 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d  in the query com
21c40 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20  ponent of a URI 
21c50 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72  is not an.** err
21c60 6f 72 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  or.  Future vers
21c70 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
21c80 69 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20  ight understand 
21c90 61 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79  additional query
21ca0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20  .** parameters. 
21cb0 20 53 65 65 20 22 5b 71 75 65 72 79 20 70 61 72   See "[query par
21cc0 61 6d 65 74 65 72 73 20 77 69 74 68 20 73 70 65  ameters with spe
21cd0 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20  cial meaning to 
21ce0 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20  SQLite]" for.** 
21cf0 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
21d00 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  mation..**.** [[
21d10 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61  URI filename exa
21d20 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20  mples]] <h3>URI 
21d30 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65  filename example
21d40 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61  s</h3>.**.** <ta
21d50 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61  ble border="1" a
21d60 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c  lign=center cell
21d70 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74  padding=5>.** <t
21d80 72 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e  r><th> URI filen
21d90 61 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74  ames <th> Result
21da0 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  s.** <tr><td> fi
21db0 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20  le:data.db <td> 
21dc0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
21dd0 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61  n the file "data
21de0 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72  .db" in the curr
21df0 65 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  ent directory..*
21e00 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
21e10 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
21e20 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20  db<br>.**       
21e30 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f     file:///home/
21e40 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72  fred/data.db <br
21e50 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  > .**          f
21e60 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f  ile://localhost/
21e70 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
21e80 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20  b <br> <td> .** 
21e90 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68           Open th
21ea0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
21eb0 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  "/home/fred/data
21ec0 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  .db"..** <tr><td
21ed0 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61  > file://darksta
21ee0 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  r/home/fred/data
21ef0 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  .db <td> .**    
21f00 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20        An error. 
21f10 22 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f  "darkstar" is no
21f20 74 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61  t a recognized a
21f30 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72  uthority..** <tr
21f40 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74  ><td style="whit
21f50 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e  e-space:nowrap">
21f60 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69   .**          fi
21f70 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e  le:///C:/Documen
21f80 74 73 25 32 30 61 6e 64 25 32 30 53 65 74 74 69  ts%20and%20Setti
21f90 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70  ngs/fred/Desktop
21fa0 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20  /data.db.**     
21fb0 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c  <td> Windows onl
21fc0 79 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65  y: Open the file
21fd0 20 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72   "data.db" on fr
21fe0 65 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20  ed's desktop on 
21ff0 64 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20  drive.**        
22000 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20    C:. Note that 
22010 74 68 65 20 25 32 30 20 65 73 63 61 70 69 6e 67  the %20 escaping
22020 20 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65   in this example
22030 20 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79   is not strictly
22040 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65   .**          ne
22050 63 65 73 73 61 72 79 20 2d 20 73 70 61 63 65 20  cessary - space 
22060 63 68 61 72 61 63 74 65 72 73 20 63 61 6e 20 62  characters can b
22070 65 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79  e used literally
22080 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20  .**          in 
22090 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a  URI filenames..*
220a0 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
220b0 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26  data.db?mode=ro&
220c0 63 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74  cache=private <t
220d0 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
220e0 4f 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e  Open file "data.
220f0 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65  db" in the curre
22100 6e 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72  nt directory for
22110 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73   read-only acces
22120 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52  s..**          R
22130 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
22140 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72  ther or not shar
22150 65 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73  ed-cache mode is
22160 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20   enabled by.**  
22170 20 20 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c          default,
22180 20 75 73 65 20 61 20 70 72 69 76 61 74 65 20 63   use a private c
22190 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  ache..** <tr><td
221a0 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65  > file:/home/fre
221b0 64 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e  d/data.db?vfs=un
221c0 69 78 2d 6e 6f 6c 6f 63 6b 20 3c 74 64 3e 0a 2a  ix-nolock <td>.*
221d0 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
221e0 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64  file "/home/fred
221f0 2f 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74  /data.db". Use t
22200 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 22  he special VFS "
22210 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 22 2e 0a 2a 2a  unix-nolock"..**
22220 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64   <tr><td> file:d
22230 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64  ata.db?mode=read
22240 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  only <td> .**   
22250 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e         An error.
22260 20 22 72 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e   "readonly" is n
22270 6f 74 20 61 20 76 61 6c 69 64 20 6f 70 74 69 6f  ot a valid optio
22280 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f 64 65 22  n for the "mode"
22290 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c   parameter..** <
222a0 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55  /table>.**.** ^U
222b0 52 49 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65  RI hexadecimal e
222c0 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20  scape sequences 
222d0 28 25 48 48 29 20 61 72 65 20 73 75 70 70 6f 72  (%HH) are suppor
222e0 74 65 64 20 77 69 74 68 69 6e 20 74 68 65 20 70  ted within the p
222f0 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79  ath and.** query
22300 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61   components of a
22310 20 55 52 49 2e 20 41 20 68 65 78 61 64 65 63 69   URI. A hexadeci
22320 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65  mal escape seque
22330 6e 63 65 20 63 6f 6e 73 69 73 74 73 20 6f 66 20  nce consists of 
22340 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73 69 67  a.** percent sig
22350 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77  n - "%" - follow
22360 65 64 20 62 79 20 65 78 61 63 74 6c 79 20 74 77  ed by exactly tw
22370 6f 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64 69  o hexadecimal di
22380 67 69 74 73 20 0a 2a 2a 20 73 70 65 63 69 66 79  gits .** specify
22390 69 6e 67 20 61 6e 20 6f 63 74 65 74 20 76 61 6c  ing an octet val
223a0 75 65 2e 20 5e 42 65 66 6f 72 65 20 74 68 65 20  ue. ^Before the 
223b0 70 61 74 68 20 6f 72 20 71 75 65 72 79 20 63 6f  path or query co
223c0 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a  mponents of a.**
223d0 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 61 72   URI filename ar
223e0 65 20 69 6e 74 65 72 70 72 65 74 65 64 2c 20 74  e interpreted, t
223f0 68 65 79 20 61 72 65 20 65 6e 63 6f 64 65 64 20  hey are encoded 
22400 75 73 69 6e 67 20 55 54 46 2d 38 20 61 6e 64 20  using UTF-8 and 
22410 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63 69  all .** hexadeci
22420 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65  mal escape seque
22430 6e 63 65 73 20 72 65 70 6c 61 63 65 64 20 62 79  nces replaced by
22440 20 61 20 73 69 6e 67 6c 65 20 62 79 74 65 20 63   a single byte c
22450 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a  ontaining the.**
22460 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f   corresponding o
22470 63 74 65 74 2e 20 49 66 20 74 68 69 73 20 70 72  ctet. If this pr
22480 6f 63 65 73 73 20 67 65 6e 65 72 61 74 65 73 20  ocess generates 
22490 61 6e 20 69 6e 76 61 6c 69 64 20 55 54 46 2d 38  an invalid UTF-8
224a0 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68   encoding,.** th
224b0 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
224c0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  defined..**.** <
224d0 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77  b>Note to Window
224e0 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68  s users:</b>  Th
224f0 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20  e encoding used 
22500 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  for the filename
22510 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20   argument.** of 
22520 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
22530 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nd sqlite3_open_
22540 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46  v2() must be UTF
22550 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72  -8, not whatever
22560 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20  .** codepage is 
22570 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
22580 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f  d.  Filenames co
22590 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61  ntaining interna
225a0 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63  tional.** charac
225b0 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e  ters must be con
225c0 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20  verted to UTF-8 
225d0 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67  prior to passing
225e0 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71   them into.** sq
225f0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
22600 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
22610 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65  )..**.** <b>Note
22620 20 74 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e 74   to Windows Runt
22630 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20  ime users:</b>  
22640 54 68 65 20 74 65 6d 70 6f 72 61 72 79 20 64 69  The temporary di
22650 72 65 63 74 6f 72 79 20 6d 75 73 74 20 62 65 20  rectory must be 
22660 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  set.** prior to 
22670 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  calling sqlite3_
22680 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  open() or sqlite
22690 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 4f 74  3_open_v2().  Ot
226a0 68 65 72 77 69 73 65 2c 20 76 61 72 69 6f 75 73  herwise, various
226b0 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 74 68 61  .** features tha
226c0 74 20 72 65 71 75 69 72 65 20 74 68 65 20 75 73  t require the us
226d0 65 20 6f 66 20 74 65 6d 70 6f 72 61 72 79 20 66  e of temporary f
226e0 69 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e 0a 2a  iles may fail..*
226f0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
22700 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72  sqlite3_temp_dir
22710 65 63 74 6f 72 79 5d 0a 2a 2f 0a 69 6e 74 20 73  ectory].*/.int s
22720 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63  qlite3_open(.  c
22730 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e  onst char *filen
22740 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61  ame,   /* Databa
22750 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46  se filename (UTF
22760 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  -8) */.  sqlite3
22770 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20   **ppDb         
22780 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
22790 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a  db handle */.);.
227a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
227b0 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64  16(.  const void
227c0 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
227d0 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
227e0 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20  me (UTF-16) */. 
227f0 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20   sqlite3 **ppDb 
22800 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
22810 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
22820 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  e */.);.int sqli
22830 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63  te3_open_v2(.  c
22840 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e  onst char *filen
22850 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61  ame,   /* Databa
22860 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46  se filename (UTF
22870 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  -8) */.  sqlite3
22880 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20   **ppDb,        
22890 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
228a0 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69  db handle */.  i
228b0 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20  nt flags,       
228c0 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20         /* Flags 
228d0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
228e0 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20  *zVfs        /* 
228f0 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75  Name of VFS modu
22900 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a  le to use */.);.
22910 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
22920 20 4f 62 74 61 69 6e 20 56 61 6c 75 65 73 20 46   Obtain Values F
22930 6f 72 20 55 52 49 20 50 61 72 61 6d 65 74 65 72  or URI Parameter
22940 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72  s.**.** These ar
22950 65 20 75 74 69 6c 69 74 79 20 72 6f 75 74 69 6e  e utility routin
22960 65 73 2c 20 75 73 65 66 75 6c 20 74 6f 20 56 46  es, useful to VF
22970 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
22980 73 2c 20 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a  s, that check.**
22990 20 74 6f 20 73 65 65 20 69 66 20 61 20 64 61 74   to see if a dat
229a0 61 62 61 73 65 20 66 69 6c 65 20 77 61 73 20 61  abase file was a
229b0 20 55 52 49 20 74 68 61 74 20 63 6f 6e 74 61 69   URI that contai
229c0 6e 65 64 20 61 20 73 70 65 63 69 66 69 63 20 71  ned a specific q
229d0 75 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74  uery .** paramet
229e0 65 72 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f 62  er, and if so ob
229f0 74 61 69 6e 73 20 74 68 65 20 76 61 6c 75 65 20  tains the value 
22a00 6f 66 20 74 68 61 74 20 71 75 65 72 79 20 70 61  of that query pa
22a10 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49  rameter..**.** I
22a20 66 20 46 20 69 73 20 74 68 65 20 64 61 74 61 62  f F is the datab
22a30 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69  ase filename poi
22a40 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e 74 6f  nter passed into
22a50 20 74 68 65 20 78 4f 70 65 6e 28 29 20 6d 65 74   the xOpen() met
22a60 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53  hod of .** a VFS
22a70 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
22a80 77 68 65 6e 20 74 68 65 20 66 6c 61 67 73 20 70  when the flags p
22a90 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65  arameter to xOpe
22aa0 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a  n() has one or .
22ab0 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b  ** more of the [
22ac0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
22ad0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e   or [SQLITE_OPEN
22ae0 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73 20 73  _MAIN_DB] bits s
22af0 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74  et and.** P is t
22b00 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 71  he name of the q
22b10 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2c 20  uery parameter, 
22b20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  then.** sqlite3_
22b30 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c  uri_parameter(F,
22b40 50 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 76  P) returns the v
22b50 61 6c 75 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a  alue of the P.**
22b60 20 70 61 72 61 6d 65 74 65 72 20 69 66 20 69 74   parameter if it
22b70 20 65 78 69 73 74 73 20 6f 72 20 61 20 4e 55 4c   exists or a NUL
22b80 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 50 20 64  L pointer if P d
22b90 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20 61  oes not appear a
22ba0 73 20 61 20 0a 2a 2a 20 71 75 65 72 79 20 70 61  s a .** query pa
22bb0 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20 20 49  rameter on F.  I
22bc0 66 20 50 20 69 73 20 61 20 71 75 65 72 79 20 70  f P is a query p
22bd0 61 72 61 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a  arameter of F.**
22be0 20 68 61 73 20 6e 6f 20 65 78 70 6c 69 63 69 74   has no explicit
22bf0 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c   value, then sql
22c00 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
22c10 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 0a  er(F,P) returns.
22c20 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** a pointer to 
22c30 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e  an empty string.
22c40 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
22c50 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
22c60 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 61 73  ,P,B) routine as
22c70 73 75 6d 65 73 20 74 68 61 74 20 50 20 69 73 20  sumes that P is 
22c80 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72  a boolean.** par
22c90 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72  ameter and retur
22ca0 6e 73 20 74 72 75 65 20 28 31 29 20 6f 72 20 66  ns true (1) or f
22cb0 61 6c 73 65 20 28 30 29 20 61 63 63 6f 72 64 69  alse (0) accordi
22cc0 6e 67 20 74 6f 20 74 68 65 20 76 61 6c 75 65 0a  ng to the value.
22cd0 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65 20 73 71  ** of P.  The sq
22ce0 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
22cf0 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65  n(F,P,B) routine
22d00 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31   returns true (1
22d10 29 20 69 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75  ) if the.** valu
22d20 65 20 6f 66 20 71 75 65 72 79 20 70 61 72 61 6d  e of query param
22d30 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66  eter P is one of
22d40 20 22 79 65 73 22 2c 20 22 74 72 75 65 22 2c 20   "yes", "true", 
22d50 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a  or "on" in any.*
22d60 2a 20 63 61 73 65 20 6f 72 20 69 66 20 74 68 65  * case or if the
22d70 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69   value begins wi
22d80 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75  th a non-zero nu
22d90 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73  mber.  The .** s
22da0 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
22db0 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e  an(F,P,B) routin
22dc0 65 73 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65  es returns false
22dd0 20 28 30 29 20 69 66 20 74 68 65 20 76 61 6c 75   (0) if the valu
22de0 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20 70 61  e of.** query pa
22df0 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65  rameter P is one
22e00 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65   of "no", "false
22e10 22 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e 20 61  ", or "off" in a
22e20 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66  ny case or.** if
22e30 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e   the value begin
22e40 73 20 77 69 74 68 20 61 20 6e 75 6d 65 72 69 63  s with a numeric
22e50 20 7a 65 72 6f 2e 20 20 49 66 20 50 20 69 73 20   zero.  If P is 
22e60 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a 20 70  not a query.** p
22e70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72  arameter on F or
22e80 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66   if the value of
22e90 20 50 20 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d   P is does not m
22ea0 61 74 63 68 20 61 6e 79 20 6f 66 20 74 68 65 0a  atch any of the.
22eb0 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e 20 73  ** above, then s
22ec0 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
22ed0 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e  an(F,P,B) return
22ee0 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20  s (B!=0)..**.** 
22ef0 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  The sqlite3_uri_
22f00 69 6e 74 36 34 28 46 2c 50 2c 44 29 20 72 6f 75  int64(F,P,D) rou
22f10 74 69 6e 65 20 63 6f 6e 76 65 72 74 73 20 74 68  tine converts th
22f20 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 6e 74  e value of P int
22f30 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69  o a.** 64-bit si
22f40 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64  gned integer and
22f50 20 72 65 74 75 72 6e 73 20 74 68 61 74 20 69 6e   returns that in
22f60 74 65 67 65 72 2c 20 6f 72 20 44 20 69 66 20 50  teger, or D if P
22f70 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69   does not.** exi
22f80 73 74 2e 20 20 49 66 20 74 68 65 20 76 61 6c 75  st.  If the valu
22f90 65 20 6f 66 20 50 20 69 73 20 73 6f 6d 65 74 68  e of P is someth
22fa0 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 61  ing other than a
22fb0 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a  n integer, then.
22fc0 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72  ** zero is retur
22fd0 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46  ned..** .** If F
22fe0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
22ff0 65 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  er, then sqlite3
23000 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46  _uri_parameter(F
23010 2c 50 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c  ,P) returns NULL
23020 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   and.** sqlite3_
23030 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
23040 42 29 20 72 65 74 75 72 6e 73 20 42 2e 20 20 49  B) returns B.  I
23050 66 20 46 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c  f F is not a NUL
23060 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a  L pointer and.**
23070 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61   is not a databa
23080 73 65 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65  se file pathname
23090 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 53 51   pointer that SQ
230a0 4c 69 74 65 20 70 61 73 73 65 64 20 69 6e 74 6f  Lite passed into
230b0 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46   the xOpen.** VF
230c0 53 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74  S method, then t
230d0 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74  he behavior of t
230e0 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75  his routine is u
230f0 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f  ndefined and pro
23100 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72  bably.** undesir
23110 61 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  able..*/.const c
23120 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 75 72 69  har *sqlite3_uri
23130 5f 70 61 72 61 6d 65 74 65 72 28 63 6f 6e 73 74  _parameter(const
23140 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65   char *zFilename
23150 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50  , const char *zP
23160 61 72 61 6d 29 3b 0a 69 6e 74 20 73 71 6c 69 74  aram);.int sqlit
23170 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63  e3_uri_boolean(c
23180 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
23190 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50  , const char *zP
231a0 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 66 61 75  aram, int bDefau
231b0 6c 74 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  lt);.sqlite3_int
231c0 36 34 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69  64 sqlite3_uri_i
231d0 6e 74 36 34 28 63 6f 6e 73 74 20 63 68 61 72 2a  nt64(const char*
231e0 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73  , const char*, s
231f0 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a  qlite3_int64);..
23200 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
23210 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64   Error Codes And
23220 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20   Messages.**.** 
23230 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72  ^The sqlite3_err
23240 63 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63 65  code() interface
23250 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
23260 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64  eric [result cod
23270 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64  e] or.** [extend
23280 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  ed result code] 
23290 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63  for the most rec
232a0 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74  ent failed sqlit
232b0 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a  e3_* API call.**
232c0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
232d0 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
232e0 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70  nection]. If a p
232f0 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61  rior API call fa
23300 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 65 20  iled.** but the 
23310 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20  most recent API 
23320 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20  call succeeded, 
23330 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
23340 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33   from.** sqlite3
23350 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e  _errcode() is un
23360 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 73  defined.  ^The s
23370 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
23380 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74  errcode().** int
23390 65 72 66 61 63 65 20 69 73 20 74 68 65 20 73 61  erface is the sa
233a0 6d 65 20 65 78 63 65 70 74 20 74 68 61 74 20 69  me except that i
233b0 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  t always returns
233c0 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64   the .** [extend
233d0 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  ed result code] 
233e0 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64  even when extend
233f0 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
23400 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e  are.** disabled.
23410 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
23420 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64  te3_errmsg() and
23430 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31   sqlite3_errmsg1
23440 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69  6() return Engli
23450 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74  sh-language.** t
23460 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62  ext that describ
23470 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73  es the error, as
23480 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72   either UTF-8 or
23490 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 69   UTF-16 respecti
234a0 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72  vely..** ^(Memor
234b0 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72  y to hold the er
234c0 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69  ror message stri
234d0 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e  ng is managed in
234e0 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65  ternally..** The
234f0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65   application doe
23500 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f  s not need to wo
23510 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e  rry about freein
23520 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a  g the result..**
23530 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72   However, the er
23540 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74  ror string might
23550 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20   be overwritten 
23560 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62  or deallocated b
23570 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20  y.** subsequent 
23580 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53  calls to other S
23590 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 20  QLite interface 
235a0 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a  functions.)^.**.
235b0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
235c0 65 72 72 73 74 72 28 29 20 69 6e 74 65 72 66 61  errstr() interfa
235d0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 45  ce returns the E
235e0 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 20  nglish-language 
235f0 74 65 78 74 0a 2a 2a 20 74 68 61 74 20 64 65 73  text.** that des
23600 63 72 69 62 65 73 20 74 68 65 20 5b 72 65 73 75  cribes the [resu
23610 6c 74 20 63 6f 64 65 5d 2c 20 61 73 20 55 54 46  lt code], as UTF
23620 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20  -8..** ^(Memory 
23630 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f  to hold the erro
23640 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
23650 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65   is managed inte
23660 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75  rnally.** and mu
23670 73 74 20 6e 6f 74 20 62 65 20 66 72 65 65 64 20  st not be freed 
23680 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
23690 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  on)^..**.** When
236a0 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20   the serialized 
236b0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
236c0 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d   is in use, it m
236d0 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63  ight be the.** c
236e0 61 73 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e  ase that a secon
236f0 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f  d error occurs o
23700 6e 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  n a separate thr
23710 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a  ead in between.*
23720 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68  * the time of th
23730 65 20 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e  e first error an
23740 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68  d the call to th
23750 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a  ese interfaces..
23760 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61 70  ** When that hap
23770 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64  pens, the second
23780 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72   error will be r
23790 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68  eported since th
237a0 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ese.** interface
237b0 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20  s always report 
237c0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
237d0 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69  result.  To avoi
237e0 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20  d.** this, each 
237f0 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69  thread can obtai
23800 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73 65 20  n exclusive use 
23810 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  of the [database
23820 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a   connection] D.*
23830 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73  * by invoking [s
23840 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74  qlite3_mutex_ent
23850 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f  er]([sqlite3_db_
23860 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72  mutex](D)) befor
23870 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74  e beginning.** t
23880 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f  o use D and invo
23890 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  king [sqlite3_mu
238a0 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69  tex_leave]([sqli
238b0 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29  te3_db_mutex](D)
238c0 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63  ) after.** all c
238d0 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65  alls to the inte
238e0 72 66 61 63 65 73 20 6c 69 73 74 65 64 20 68 65  rfaces listed he
238f0 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64  re are completed
23900 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e  ..**.** If an in
23910 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69  terface fails wi
23920 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  th SQLITE_MISUSE
23930 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65  , that means the
23940 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61   interface.** wa
23950 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72  s invoked incorr
23960 65 63 74 6c 79 20 62 79 20 74 68 65 20 61 70 70  ectly by the app
23970 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68  lication.  In th
23980 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20  at case, the.** 
23990 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d  error code and m
239a0 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61  essage may or ma
239b0 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f  y not be set..*/
239c0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72  .int sqlite3_err
239d0 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62  code(sqlite3 *db
239e0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  );.int sqlite3_e
239f0 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
23a00 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f  sqlite3 *db);.co
23a10 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
23a20 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33  3_errmsg(sqlite3
23a30 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
23a40 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
23a50 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73  (sqlite3*);.cons
23a60 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
23a70 65 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a  errstr(int);../*
23a80 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51  .** CAPI3REF: SQ
23a90 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  L Statement Obje
23aa0 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ct.** KEYWORDS: 
23ab0 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  {prepared statem
23ac0 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73  ent} {prepared s
23ad0 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a  tatements}.**.**
23ae0 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
23af0 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72  this object repr
23b00 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20  esents a single 
23b10 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  SQL statement..*
23b20 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73  * This object is
23b30 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e   variously known
23b40 20 61 73 20 61 20 22 70 72 65 70 61 72 65 64 20   as a "prepared 
23b50 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a  statement" or a.
23b60 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c  ** "compiled SQL
23b70 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73   statement" or s
23b80 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61 74  imply as a "stat
23b90 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68  ement"..**.** Th
23ba0 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74  e life of a stat
23bb0 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65  ement object goe
23bc0 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65  s something like
23bd0 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   this:.**.** <ol
23be0 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65  >.** <li> Create
23bf0 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e   the object usin
23c00 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
23c10 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65  re_v2()] or a re
23c20 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75  lated.**      fu
23c30 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20  nction..** <li> 
23c40 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b  Bind values to [
23c50 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 5d  host parameters]
23c60 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
23c70 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20  e3_bind_*().**  
23c80 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a      interfaces..
23c90 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20  ** <li> Run the 
23ca0 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  SQL by calling [
23cb0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
23cc0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
23cd0 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74  s..** <li> Reset
23ce0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75   the statement u
23cf0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  sing [sqlite3_re
23d00 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62  set()] then go b
23d10 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73  ack.**      to s
23d20 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20  tep 2.  Do this 
23d30 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d  zero or more tim
23d40 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74  es..** <li> Dest
23d50 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75  roy the object u
23d60 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
23d70 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f  nalize()]..** </
23d80 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20  ol>.**.** Refer 
23d90 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  to documentation
23da0 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d   on individual m
23db0 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72  ethods above for
23dc0 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
23dd0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74  nformation..*/.t
23de0 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
23df0 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74  lite3_stmt sqlit
23e00 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20  e3_stmt;../*.** 
23e10 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69  CAPI3REF: Run-ti
23e20 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20  me Limits.**.** 
23e30 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  ^(This interface
23e40 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65   allows the size
23e50 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73   of various cons
23e60 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d  tructs to be lim
23e70 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e  ited.** on a con
23e80 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65  nection by conne
23e90 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68  ction basis.  Th
23ea0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
23eb0 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74  r is the.** [dat
23ec0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
23ed0 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73  ] whose limit is
23ee0 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75   to be set or qu
23ef0 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73  eried.  The.** s
23f00 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
23f10 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c  is one of the [l
23f20 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d  imit categories]
23f30 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a   that define a.*
23f40 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74  * class of const
23f50 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65  ructs to be size
23f60 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74   limited.  The t
23f70 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69  hird parameter i
23f80 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d  s the.** new lim
23f90 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73  it for that cons
23fa0 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  truct.)^.**.** ^
23fb0 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74  If the new limit
23fc0 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e   is a negative n
23fd0 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74  umber, the limit
23fe0 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a   is unchanged..*
23ff0 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d  * ^(For each lim
24000 69 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49  it category SQLI
24010 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45  TE_LIMIT_<i>NAME
24020 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61 20  </i> there is a 
24030 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61  .** [limits | ha
24040 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a  rd upper bound].
24050 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c  ** set at compil
24060 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70 72  e-time by a C pr
24070 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
24080 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69   called.** [limi
24090 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f  ts | SQLITE_MAX_
240a0 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a  <i>NAME</i>]..**
240b0 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20   (The "_LIMIT_" 
240c0 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63  in the name is c
240d0 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f  hanged to "_MAX_
240e0 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70  ".))^.** ^Attemp
240f0 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61  ts to increase a
24100 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73   limit above its
24110 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
24120 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c  d are.** silentl
24130 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74  y truncated to t
24140 68 65 20 68 61 72 64 20 75 70 70 65 72 20 62 6f  he hard upper bo
24150 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61  und..**.** ^Rega
24160 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
24170 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d  r or not the lim
24180 69 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20  it was changed, 
24190 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  the .** [sqlite3
241a0 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66  _limit()] interf
241b0 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
241c0 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74  prior value of t
241d0 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65  he limit..** ^He
241e0 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65  nce, to find the
241f0 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f   current value o
24200 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75  f a limit withou
24210 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a  t changing it,.*
24220 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20  * simply invoke 
24230 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 77  this interface w
24240 69 74 68 20 74 68 65 20 74 68 69 72 64 20 70 61  ith the third pa
24250 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d  rameter set to -
24260 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d  1..**.** Run-tim
24270 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74  e limits are int
24280 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
24290 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   applications th
242a0 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74  at manage.** bot
242b0 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65  h their own inte
242c0 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e  rnal database an
242d0 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73  d also databases
242e0 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f   that are contro
242f0 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75  lled.** by untru
24300 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f  sted external so
24310 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70  urces.  An examp
24320 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  le application m
24330 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62  ight be a.** web
24340 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61   browser that ha
24350 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61  s its own databa
24360 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20  ses for storing 
24370 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73  history and.** s
24380 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65  eparate database
24390 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20  s controlled by 
243a0 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69  JavaScript appli
243b0 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64  cations download
243c0 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e  ed.** off the In
243d0 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74  ternet.  The int
243e0 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20  ernal databases 
243f0 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65  can be given the
24400 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75  .** large, defau
24410 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61  lt limits.  Data
24420 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79  bases managed by
24430 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65   external source
24440 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65  s can.** be give
24450 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c  n much smaller l
24460 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74  imits designed t
24470 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69  o prevent a deni
24480 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a  al of service.**
24490 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f   attack.  Develo
244a0 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20  pers might also 
244b0 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20  want to use the 
244c0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
244d0 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e  horizer()].** in
244e0 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68  terface to furth
244f0 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75  er control untru
24500 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73  sted SQL.  The s
24510 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ize of the datab
24520 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62  ase.** created b
24530 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73  y an untrusted s
24540 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e  cript can be con
24550 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65  tained using the
24560 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f  .** [max_page_co
24570 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a  unt] [PRAGMA]..*
24580 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d  *.** New run-tim
24590 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69  e limit categori
245a0 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  es may be added 
245b0 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
245c0 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  es..*/.int sqlit
245d0 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33  e3_limit(sqlite3
245e0 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e  *, int id, int n
245f0 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ewVal);../*.** C
24600 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
24610 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69  e Limit Categori
24620 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
24630 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d  {limit category}
24640 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72   {*limit categor
24650 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ies}.**.** These
24660 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e   constants defin
24670 65 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72  e various perfor
24680 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20  mance limits.** 
24690 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65  that can be lowe
246a0 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20  red at run-time 
246b0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c  using [sqlite3_l
246c0 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  imit()]..** The 
246d0 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20  synopsis of the 
246e0 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20  meanings of the 
246f0 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69  various limits i
24700 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a  s shown below..*
24710 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  * Additional inf
24720 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69  ormation is avai
24730 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73  lable at [limits
24740 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c   | Limits in SQL
24750 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  ite]..**.** <dl>
24760 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
24770 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64  IT_LENGTH]] ^(<d
24780 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  t>SQLITE_LIMIT_L
24790 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
247a0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69  d>The maximum si
247b0 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67  ze of any string
247c0 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c   or BLOB or tabl
247d0 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e  e row, in bytes.
247e0 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  <dd>)^.**.** [[S
247f0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
24800 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  LENGTH]] ^(<dt>S
24810 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
24820 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
24830 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c  dd>The maximum l
24840 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20  ength of an SQL 
24850 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79  statement, in by
24860 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  tes.</dd>)^.**.*
24870 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
24880 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e  _COLUMN]] ^(<dt>
24890 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
248a0 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  UMN</dt>.** <dd>
248b0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
248c0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
248d0 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74   a table definit
248e0 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a  ion or in the.**
248f0 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61   result set of a
24900 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65   [SELECT] or the
24910 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
24920 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e  of columns in an
24930 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20   index.** or in 
24940 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47  an ORDER BY or G
24950 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c  ROUP BY clause.<
24960 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
24970 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
24980 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  _DEPTH]] ^(<dt>S
24990 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
249a0 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  _DEPTH</dt>.** <
249b0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64  dd>The maximum d
249c0 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73  epth of the pars
249d0 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78  e tree on any ex
249e0 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e  pression.</dd>)^
249f0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
24a00 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53  LIMIT_COMPOUND_S
24a10 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51  ELECT]] ^(<dt>SQ
24a20 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
24a30 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a  UND_SELECT</dt>.
24a40 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
24a50 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72  um number of ter
24a60 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64  ms in a compound
24a70 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
24a80 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  t.</dd>)^.**.** 
24a90 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  [[SQLITE_LIMIT_V
24aa0 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53  DBE_OP]] ^(<dt>S
24ab0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
24ac0 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  _OP</dt>.** <dd>
24ad0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
24ae0 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f  er of instructio
24af0 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20  ns in a virtual 
24b00 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a  machine program.
24b10 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  ** used to imple
24b20 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74  ment an SQL stat
24b30 65 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d  ement.  This lim
24b40 69 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e  it is not curren
24b50 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c  tly.** enforced,
24b60 20 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67   though that mig
24b70 68 74 20 62 65 20 61 64 64 65 64 20 69 6e 20 73  ht be added in s
24b80 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61  ome future relea
24b90 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e  se of.** SQLite.
24ba0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
24bb0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
24bc0 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64  CTION_ARG]] ^(<d
24bd0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  t>SQLITE_LIMIT_F
24be0 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e  UNCTION_ARG</dt>
24bf0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
24c00 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  mum number of ar
24c10 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e  guments on a fun
24c20 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ction.</dd>)^.**
24c30 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
24c40 49 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28  IT_ATTACHED]] ^(
24c50 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
24c60 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a  _ATTACHED</dt>.*
24c70 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
24c80 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54  m number of [ATT
24c90 41 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64  ACH | attached d
24ca0 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64  atabases].)^</dd
24cb0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
24cc0 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
24cd0 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20  ERN_LENGTH]].** 
24ce0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
24cf0 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
24d00 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
24d10 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c  dd>The maximum l
24d20 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74  ength of the pat
24d30 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f  tern argument to
24d40 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a   the [LIKE] or.*
24d50 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f  * [GLOB] operato
24d60 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  rs.</dd>)^.**.**
24d70 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
24d80 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d  VARIABLE_NUMBER]
24d90 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  ].** ^(<dt>SQLIT
24da0 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
24db0 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20  _NUMBER</dt>.** 
24dc0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
24dd0 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20  index number of 
24de0 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  any [parameter] 
24df0 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  in an SQL statem
24e00 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ent.)^.**.** [[S
24e10 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
24e20 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64  GER_DEPTH]] ^(<d
24e30 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54  t>SQLITE_LIMIT_T
24e40 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74  RIGGER_DEPTH</dt
24e50 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
24e60 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65  imum depth of re
24e70 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67  cursion for trig
24e80 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20  gers.</dd>)^.** 
24e90 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
24ea0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45   SQLITE_LIMIT_LE
24eb0 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
24ec0 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e          0.#defin
24ed0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  e SQLITE_LIMIT_S
24ee0 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  QL_LENGTH       
24ef0 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
24f00 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
24f10 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20  COLUMN          
24f20 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66            2.#def
24f30 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
24f40 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20  _EXPR_DEPTH     
24f50 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65             3.#de
24f60 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
24f70 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
24f80 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64  T           4.#d
24f90 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
24fa0 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20  IT_VDBE_OP      
24fb0 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23               5.#
24fc0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
24fd0 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
24fe0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a                6.
24ff0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
25000 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20  IMIT_ATTACHED   
25010 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37                 7
25020 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
25030 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
25040 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  RN_LENGTH       
25050 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
25060 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
25070 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20  NUMBER          
25080 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   9.#define SQLIT
25090 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f  E_LIMIT_TRIGGER_
250a0 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20  DEPTH           
250b0 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   10../*.** CAPI3
250c0 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41  REF: Compiling A
250d0 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a  n SQL Statement.
250e0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51  ** KEYWORDS: {SQ
250f0 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70  L statement comp
25100 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65  iler}.**.** To e
25110 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75  xecute an SQL qu
25120 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72  ery, it must fir
25130 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69  st be compiled i
25140 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a  nto a byte-code.
25150 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67  ** program using
25160 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f   one of these ro
25170 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  utines..**.** Th
25180 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
25190 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61  , "db", is a [da
251a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
251b0 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  n] obtained from
251c0 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63   a.** prior succ
251d0 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
251e0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
251f0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
25200 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  2()] or.** [sqli
25210 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20  te3_open16()].  
25220 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  The database con
25230 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  nection must not
25240 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65   have been close
25250 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  d..**.** The sec
25260 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a  ond argument, "z
25270 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61  Sql", is the sta
25280 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d  tement to be com
25290 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a  piled, encoded.*
252a0 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d  * as either UTF-
252b0 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68  8 or UTF-16.  Th
252c0 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
252d0 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
252e0 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20  prepare_v2().** 
252f0 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 20 55  interfaces use U
25300 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65  TF-8, and sqlite
25310 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 61 6e  3_prepare16() an
25320 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
25330 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20  e16_v2().** use 
25340 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49  UTF-16..**.** ^I
25350 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75  f the nByte argu
25360 6d 65 6e 74 20 69 73 20 6c 65 73 73 20 74 68 61  ment is less tha
25370 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71  n zero, then zSq
25380 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20  l is read up to 
25390 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72  the.** first zer
253a0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49  o terminator. ^I
253b0 66 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e  f nByte is non-n
253c0 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74  egative, then it
253d0 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a   is the maximum.
253e0 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20 62 79  ** number of  by
253f0 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53  tes read from zS
25400 71 6c 2e 20 20 5e 57 68 65 6e 20 6e 42 79 74 65  ql.  ^When nByte
25410 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
25420 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74  , the.** zSql st
25430 72 69 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74  ring ends at eit
25440 68 65 72 20 74 68 65 20 66 69 72 73 74 20 27 5c  her the first '\
25450 30 30 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27  000' or '\u0000'
25460 20 63 68 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a   character or.**
25470 20 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79   the nByte-th by
25480 74 65 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f  te, whichever co
25490 6d 65 73 20 66 69 72 73 74 2e 20 49 66 20 74 68  mes first. If th
254a0 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a  e caller knows.*
254b0 2a 20 74 68 61 74 20 74 68 65 20 73 75 70 70 6c  * that the suppl
254c0 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75  ied string is nu
254d0 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68  l-terminated, th
254e0 65 6e 20 74 68 65 72 65 20 69 73 20 61 20 73 6d  en there is a sm
254f0 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e  all.** performan
25500 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20  ce advantage to 
25510 62 65 20 67 61 69 6e 65 64 20 62 79 20 70 61 73  be gained by pas
25520 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61  sing an nByte pa
25530 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20  rameter that.** 
25540 69 73 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20  is equal to the 
25550 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
25560 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  in the input str
25570 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67  ing <i>including
25580 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d  </i>.** the nul-
25590 74 65 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73  terminator bytes
255a0 20 61 73 20 74 68 69 73 20 73 61 76 65 73 20 53   as this saves S
255b0 51 4c 69 74 65 20 66 72 6f 6d 20 68 61 76 69 6e  QLite from havin
255c0 67 20 74 6f 0a 2a 2a 20 6d 61 6b 65 20 61 20 63  g to.** make a c
255d0 6f 70 79 20 6f 66 20 74 68 65 20 69 6e 70 75 74  opy of the input
255e0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e   string..**.** ^
255f0 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74  If pzTail is not
25600 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61   NULL then *pzTa
25610 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f  il is made to po
25620 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74  int to the first
25630 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68   byte.** past th
25640 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72  e end of the fir
25650 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  st SQL statement
25660 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65   in zSql.  These
25670 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a   routines only.*
25680 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69  * compile the fi
25690 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  rst statement in
256a0 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69   zSql, so *pzTai
256b0 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69  l is left pointi
256c0 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65  ng to.** what re
256d0 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64  mains uncompiled
256e0 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74  ..**.** ^*ppStmt
256f0 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
25700 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20  g to a compiled 
25710 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
25720 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65  ent] that can be
25730 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69  .** executed usi
25740 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
25750 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20  ()].  ^If there 
25760 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70  is an error, *pp
25770 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74  Stmt is set.** t
25780 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65  o NULL.  ^If the
25790 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74   input text cont
257a0 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20  ains no SQL (if 
257b0 74 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20  the input is an 
257c0 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20  empty.** string 
257d0 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68  or a comment) th
257e0 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65  en *ppStmt is se
257f0 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68  t to NULL..** Th
25800 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64  e calling proced
25810 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ure is responsib
25820 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20  le for deleting 
25830 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  the compiled.** 
25840 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73  SQL statement us
25850 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
25860 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69  alize()] after i
25870 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  t has finished w
25880 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d  ith it..** ppStm
25890 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c  t may not be NUL
258a0 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63  L..**.** ^On suc
258b0 63 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65  cess, the sqlite
258c0 33 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d 69  3_prepare() fami
258d0 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72  ly of routines r
258e0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
258f0 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20  ];.** otherwise 
25900 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
25910 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
25920 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70  ** The sqlite3_p
25930 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20  repare_v2() and 
25940 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
25950 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  6_v2() interface
25960 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65  s are.** recomme
25970 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77  nded for all new
25980 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74   programs. The t
25990 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61  wo older interfa
259a0 63 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64  ces are retained
259b0 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64  .** for backward
259c0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c  s compatibility,
259d0 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69   but their use i
259e0 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a  s discouraged..*
259f0 2a 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69  * ^In the "v2" i
25a00 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70  nterfaces, the p
25a10 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
25a20 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74  t.** that is ret
25a30 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69  urned (the [sqli
25a40 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74  te3_stmt] object
25a50 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70  ) contains a cop
25a60 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67  y of the.** orig
25a70 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54  inal SQL text. T
25a80 68 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b  his causes the [
25a90 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
25aa0 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20  interface to.** 
25ab0 62 65 68 61 76 65 20 64 69 66 66 65 72 65 6e 74  behave different
25ac0 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61 79 73  ly in three ways
25ad0 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20  :.**.** <ol>.** 
25ae0 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  <li>.** ^If the 
25af0 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20  database schema 
25b00 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64  changes, instead
25b10 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53   of returning [S
25b20 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73  QLITE_SCHEMA] as
25b30 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73   it.** always us
25b40 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74  ed to do, [sqlit
25b50 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
25b60 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65  automatically re
25b70 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a  compile the SQL.
25b80 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  ** statement and
25b90 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61   try to run it a
25ba0 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73  gain. As many as
25bb0 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48   [SQLITE_MAX_SCH
25bc0 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65  EMA_RETRY].** re
25bd0 74 72 69 65 73 20 77 69 6c 6c 20 6f 63 63 75 72  tries will occur
25be0 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f   before sqlite3_
25bf0 73 74 65 70 28 29 20 67 69 76 65 73 20 75 70 20  step() gives up 
25c00 61 6e 64 20 72 65 74 75 72 6e 73 20 61 6e 20 65  and returns an e
25c10 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  rror..** </li>.*
25c20 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68  *.** <li>.** ^Wh
25c30 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  en an error occu
25c40 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  rs, [sqlite3_ste
25c50 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  p()] will return
25c60 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61   one of the deta
25c70 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  iled.** [error c
25c80 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64  odes] or [extend
25c90 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e  ed error codes].
25ca0 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65    ^The legacy be
25cb0 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a  havior was that.
25cc0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
25cd0 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72  ()] would only r
25ce0 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20  eturn a generic 
25cf0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72  [SQLITE_ERROR] r
25d00 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e  esult code.** an
25d10 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
25d20 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20  n would have to 
25d30 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61  make a second ca
25d40 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ll to [sqlite3_r
25d50 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72  eset()].** in or
25d60 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20  der to find the 
25d70 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65  underlying cause
25d80 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e   of the problem.
25d90 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70   With the "v2" p
25da0 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66  repare.** interf
25db0 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c  aces, the underl
25dc0 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20  ying reason for 
25dd0 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 65 74  the error is ret
25de0 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  urned immediatel
25df0 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a  y..** </li>.**.*
25e00 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68  * <li>.** ^If th
25e10 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65  e specific value
25e20 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d   bound to [param
25e30 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61  eter | host para
25e40 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a  meter] in the .*
25e50 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d  * WHERE clause m
25e60 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74  ight influence t
25e70 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65  he choice of que
25e80 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74  ry plan for a st
25e90 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e  atement,.** then
25ea0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77   the statement w
25eb0 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63  ill be automatic
25ec0 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c  ally recompiled,
25ed0 20 61 73 20 69 66 20 74 68 65 72 65 20 68 61 64   as if there had
25ee0 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65   been .** a sche
25ef0 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68  ma change, on th
25f00 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65  e first  [sqlite
25f10 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66  3_step()] call f
25f20 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61  ollowing any cha
25f30 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73  nge.** to the [s
25f40 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
25f50 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20   | bindings] of 
25f60 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d  that [parameter]
25f70 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69  . .** ^The speci
25f80 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45  fic value of WHE
25f90 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d  RE-clause [param
25fa0 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c  eter] might infl
25fb0 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68  uence the .** ch
25fc0 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c  oice of query pl
25fd0 61 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  an if the parame
25fe0 74 65 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d  ter is the left-
25ff0 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b  hand side of a [
26000 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f  LIKE].** or [GLO
26010 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69  B] operator or i
26020 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
26030 69 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61  is compared to a
26040 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e  n indexed column
26050 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c  .** and the [SQL
26060 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33  ITE_ENABLE_STAT3
26070 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
26080 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ption is enabled
26090 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  ..** </li>.** </
260a0 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ol>.*/.int sqlit
260b0 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71  e3_prepare(.  sq
260c0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
260d0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
260e0 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
260f0 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
26100 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
26110 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e  tement, UTF-8 en
26120 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
26130 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
26140 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
26150 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
26160 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
26170 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
26180 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
26190 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
261a0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70    const char **p
261b0 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
261c0 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
261d0 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
261e0 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  Sql */.);.int sq
261f0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
26200 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
26210 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
26220 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
26230 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
26240 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
26250 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
26260 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  F-8 encoded */. 
26270 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
26280 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
26290 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
262a0 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
262b0 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
262c0 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
262d0 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
262e0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
262f0 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  ar **pzTail     
26300 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
26310 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
26320 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
26330 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
26340 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33  are16(.  sqlite3
26350 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
26360 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
26370 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
26380 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
26390 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
263a0 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
263b0 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
263c0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
263d0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
263e0 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
263f0 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
26400 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
26410 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
26420 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
26430 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69  nst void **pzTai
26440 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
26450 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
26460 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
26470 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
26480 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a  3_prepare16_v2(.
26490 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
264a0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
264b0 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
264c0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53    const void *zS
264d0 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
264e0 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
264f0 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  16 encoded */.  
26500 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
26510 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
26520 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
26530 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
26540 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
26550 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
26560 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
26570 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
26580 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  d **pzTail     /
26590 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
265a0 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
265b0 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a   of zSql */.);..
265c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
265d0 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65  Retrieving State
265e0 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e  ment SQL.**.** ^
265f0 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63  This interface c
26600 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65  an be used to re
26610 74 72 69 65 76 65 20 61 20 73 61 76 65 64 20 63  trieve a saved c
26620 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69  opy of the origi
26630 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20  nal.** SQL text 
26640 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 61  used to create a
26650 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
26660 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74  ment] if that st
26670 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63  atement was.** c
26680 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69  ompiled using ei
26690 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ther [sqlite3_pr
266a0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
266b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
266c0 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73  6_v2()]..*/.cons
266d0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
266e0 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  sql(sqlite3_stmt
266f0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
26700 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72   CAPI3REF: Deter
26710 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53  mine If An SQL S
26720 74 61 74 65 6d 65 6e 74 20 57 72 69 74 65 73 20  tatement Writes 
26730 54 68 65 20 44 61 74 61 62 61 73 65 0a 2a 2a 0a  The Database.**.
26740 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
26750 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29  stmt_readonly(X)
26760 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
26770 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72  ns true (non-zer
26780 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c  o) if.** and onl
26790 79 20 69 66 20 74 68 65 20 5b 70 72 65 70 61 72  y if the [prepar
267a0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20  ed statement] X 
267b0 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20  makes no direct 
267c0 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68  changes to.** th
267d0 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
267e0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a   database file..
267f0 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
26800 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
26810 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
26820 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75  ns] or.** [virtu
26830 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74  al tables] might
26840 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
26850 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20  base indirectly 
26860 61 73 20 61 20 73 69 64 65 20 65 66 66 65 63 74  as a side effect
26870 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61  .  .** ^(For exa
26880 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c  mple, if an appl
26890 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20  ication defines 
268a0 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c  a function "eval
268b0 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c  ()" that .** cal
268c0 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ls [sqlite3_exec
268d0 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f  ()], then the fo
268e0 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74  llowing SQL stat
268f0 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63  ement would.** c
26900 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61  hange the databa
26910 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20  se file through 
26920 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a  side-effects:.**
26930 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
26940 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45  <pre>.**    SELE
26950 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20  CT eval('DELETE 
26960 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74  FROM t1') FROM t
26970 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  2;.** </pre></bl
26980 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
26990 42 75 74 20 62 65 63 61 75 73 65 20 74 68 65 20  But because the 
269a0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
269b0 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  nt does not chan
269c0 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
269d0 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79  file.** directly
269e0 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  , sqlite3_stmt_r
269f0 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20  eadonly() would 
26a00 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75  still return tru
26a10 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e  e.)^.**.** ^Tran
26a20 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20  saction control 
26a30 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20  statements such 
26a40 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d  as [BEGIN], [COM
26a50 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d  MIT], [ROLLBACK]
26a60 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d  ,.** [SAVEPOINT]
26a70 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20  , and [RELEASE] 
26a80 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74  cause sqlite3_st
26a90 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f  mt_readonly() to
26aa0 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a   return true,.**
26ab0 20 73 69 6e 63 65 20 74 68 65 20 73 74 61 74 65   since the state
26ac0 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73  ments themselves
26ad0 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79   do not actually
26ae0 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61   modify the data
26af0 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68  base but.** rath
26b00 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20  er they control 
26b10 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68  the timing of wh
26b20 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65  en other stateme
26b30 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a  nts modify the .
26b40 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54  ** database.  ^T
26b50 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20  he [ATTACH] and 
26b60 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65  [DETACH] stateme
26b70 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a  nts also cause.*
26b80 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  * sqlite3_stmt_r
26b90 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74  eadonly() to ret
26ba0 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20  urn true since, 
26bb0 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74  while those stat
26bc0 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65  ements.** change
26bd0 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
26be0 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73 65  on of a database
26bf0 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65   connection, the
26c00 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a  y do not make .*
26c10 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  * changes to the
26c20 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
26c30 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f  database files o
26c40 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 69 6e 74 20 73  n disk..*/.int s
26c50 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
26c60 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74 6d  only(sqlite3_stm
26c70 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
26c80 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65  * CAPI3REF: Dete
26c90 72 6d 69 6e 65 20 49 66 20 41 20 50 72 65 70 61  rmine If A Prepa
26ca0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 48 61  red Statement Ha
26cb0 73 20 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a 0a  s Been Reset.**.
26cc0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
26cd0 73 74 6d 74 5f 62 75 73 79 28 53 29 20 69 6e 74  stmt_busy(S) int
26ce0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
26cf0 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69  rue (non-zero) i
26d00 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  f the.** [prepar
26d10 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
26d20 68 61 73 20 62 65 65 6e 20 73 74 65 70 70 65 64  has been stepped
26d30 20 61 74 20 6c 65 61 73 74 20 6f 6e 63 65 20 75   at least once u
26d40 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  sing .** [sqlite
26d50 33 5f 73 74 65 70 28 53 29 5d 20 62 75 74 20 68  3_step(S)] but h
26d60 61 73 20 6e 6f 74 20 72 75 6e 20 74 6f 20 63 6f  as not run to co
26d70 6d 70 6c 65 74 69 6f 6e 20 61 6e 64 2f 6f 72 20  mpletion and/or 
26d80 68 61 73 20 6e 6f 74 20 0a 2a 2a 20 62 65 65 6e  has not .** been
26d90 20 72 65 73 65 74 20 75 73 69 6e 67 20 5b 73 71   reset using [sq
26da0 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e  lite3_reset(S)].
26db0 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73    ^The sqlite3_s
26dc0 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69  tmt_busy(S).** i
26dd0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
26de0 20 66 61 6c 73 65 20 69 66 20 53 20 69 73 20 61   false if S is a
26df0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
26e00 49 66 20 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a  If S is not a .*
26e10 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61  * NULL pointer a
26e20 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e  nd is not a poin
26e30 74 65 72 20 74 6f 20 61 20 76 61 6c 69 64 20 5b  ter to a valid [
26e40 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
26e50 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74  nt].** object, t
26e60 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
26e70 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
26e80 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73  d probably undes
26e90 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  irable..**.** Th
26ea0 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  is interface can
26eb0 20 62 65 20 75 73 65 64 20 69 6e 20 63 6f 6d 62   be used in comb
26ec0 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33  ination [sqlite3
26ed0 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a  _next_stmt()].**
26ee0 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70   to locate all p
26ef0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
26f00 74 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ts associated wi
26f10 74 68 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a  th a database .*
26f20 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  * connection tha
26f30 74 20 61 72 65 20 69 6e 20 6e 65 65 64 20 6f 66  t are in need of
26f40 20 62 65 69 6e 67 20 72 65 73 65 74 2e 20 20 54   being reset.  T
26f50 68 69 73 20 63 61 6e 20 62 65 20 75 73 65 64 2c  his can be used,
26f60 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c  .** for example,
26f70 20 69 6e 20 64 69 61 67 6e 6f 73 74 69 63 20 72   in diagnostic r
26f80 6f 75 74 69 6e 65 73 20 74 6f 20 73 65 61 72 63  outines to searc
26f90 68 20 66 6f 72 20 70 72 65 70 61 72 65 64 20 0a  h for prepared .
26fa0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  ** statements th
26fb0 61 74 20 61 72 65 20 68 6f 6c 64 69 6e 67 20 61  at are holding a
26fc0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65   transaction ope
26fd0 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  n..*/.int sqlite
26fe0 33 5f 73 74 6d 74 5f 62 75 73 79 28 73 71 6c 69  3_stmt_busy(sqli
26ff0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
27000 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e  ** CAPI3REF: Dyn
27010 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56  amically Typed V
27020 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b  alue Object.** K
27030 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63  EYWORDS: {protec
27040 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
27050 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20  e} {unprotected 
27060 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a  sqlite3_value}.*
27070 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
27080 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   the sqlite3_val
27090 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70  ue object to rep
270a0 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65  resent all value
270b0 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65  s.** that can be
270c0 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74   stored in a dat
270d0 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c  abase table. SQL
270e0 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
270f0 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74   typing.** for t
27100 68 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f  he values it sto
27110 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74  res.  ^Values st
27120 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f  ored in sqlite3_
27130 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a  value objects.**
27140 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73   can be integers
27150 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  , floating point
27160 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73   values, strings
27170 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c  , BLOBs, or NULL
27180 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74  ..**.** An sqlit
27190 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
271a0 6d 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70  may be either "p
271b0 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e  rotected" or "un
271c0 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53  protected"..** S
271d0 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72  ome interfaces r
271e0 65 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74  equire a protect
271f0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
27200 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61  .  Other interfa
27210 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65  ces.** will acce
27220 70 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74  pt either a prot
27230 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72  ected or an unpr
27240 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
27250 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20  value..** Every 
27260 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61  interface that a
27270 63 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76  ccepts sqlite3_v
27280 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73  alue arguments s
27290 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74  pecifies.** whet
272a0 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65  her or not it re
272b0 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74  quires a protect
272c0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
272d0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d  ..**.** The term
272e0 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e  s "protected" an
272f0 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20  d "unprotected" 
27300 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72  refer to whether
27310 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74   or not.** a mut
27320 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20  ex is held.  An 
27330 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69  internal mutex i
27340 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f  s held for a pro
27350 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
27360 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62  3_value object b
27370 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68  ut no mutex is h
27380 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f  eld for an unpro
27390 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
273a0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20  3_value object. 
273b0 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   If SQLite is co
273c0 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e  mpiled to be sin
273d0 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20  gle-threaded.** 
273e0 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48  (with [SQLITE_TH
273f0 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20  READSAFE=0] and 
27400 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68  with [sqlite3_th
27410 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75  readsafe()] retu
27420 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69  rning 0).** or i
27430 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20  f SQLite is run 
27440 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65  in one of reduce
27450 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a  d mutex modes .*
27460 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
27470 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f  _SINGLETHREAD] o
27480 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
27490 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a  _MULTITHREAD].**
274a0 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e   then there is n
274b0 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  o distinction be
274c0 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20  tween protected 
274d0 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a  and unprotected.
274e0 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
274f0 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65   objects and the
27500 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e  y can be used in
27510 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20  terchangeably.  
27520 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20  However,.** for 
27530 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72  maximum code por
27540 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72  tability it is r
27550 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
27560 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
27570 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64  still make the d
27580 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65  istinction betwe
27590 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64  en protected and
275a0 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
275b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
275c0 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20  jects even when 
275d0 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71  not strictly req
275e0 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  uired..**.** ^Th
275f0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
27600 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65  objects that are
27610 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d   passed as param
27620 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a  eters into the.*
27630 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
27640 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e   of [application
27650 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
27660 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74  ctions] are prot
27670 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73  ected..** ^The s
27680 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
27690 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
276a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
276b0 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
276c0 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55  nprotected..** U
276d0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
276e0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
276f0 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65   may only be use
27700 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74  d with.** [sqlit
27710 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
27720 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
27730 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a  bind_value()]..*
27740 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  * The [sqlite3_v
27750 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  alue_blob | sqli
27760 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29  te3_value_type()
27770 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69  ] family of.** i
27780 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72  nterfaces requir
27790 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  e protected sqli
277a0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
277b0 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  s..*/.typedef st
277c0 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33  ruct Mem sqlite3
277d0 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _value;../*.** C
277e0 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e  API3REF: SQL Fun
277f0 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62  ction Context Ob
27800 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ject.**.** The c
27810 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20  ontext in which 
27820 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  an SQL function 
27830 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72  executes is stor
27840 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69  ed in an.** sqli
27850 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65  te3_context obje
27860 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20  ct.  ^A pointer 
27870 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f  to an sqlite3_co
27880 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20  ntext object.** 
27890 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20  is always first 
278a0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70  parameter to [ap
278b0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
278c0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
278d0 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
278e0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
278f0 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
27900 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61  entation will pa
27910 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74  ss this.** point
27920 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20  er through into 
27930 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
27940 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73  3_result_int | s
27950 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d  qlite3_result()]
27960 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67  ,.** [sqlite3_ag
27970 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
27980 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65  )], [sqlite3_use
27990 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73  r_data()],.** [s
279a0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
279b0 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71  b_handle()], [sq
279c0 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
279d0 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20  a()],.** and/or 
279e0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78  [sqlite3_set_aux
279f0 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65  data()]..*/.type
27a00 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
27a10 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74  e3_context sqlit
27a20 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a  e3_context;../*.
27a30 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e  ** CAPI3REF: Bin
27a40 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50  ding Values To P
27a50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
27a60 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ts.** KEYWORDS: 
27a70 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d  {host parameter}
27a80 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
27a90 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  s} {host paramet
27aa0 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57  er name}.** KEYW
27ab0 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d  ORDS: {SQL param
27ac0 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d  eter} {SQL param
27ad0 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65  eters} {paramete
27ae0 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a  r binding}.**.**
27af0 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74   ^(In the SQL st
27b00 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70  atement text inp
27b10 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70  ut to [sqlite3_p
27b20 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
27b30 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a   its variants,.*
27b40 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62  * literals may b
27b50 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20  e replaced by a 
27b60 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74  [parameter] that
27b70 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20   matches one of 
27b80 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d  following.** tem
27b90 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  plates:.**.** <u
27ba0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a  l>.** <li>  ?.**
27bb0 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c   <li>  ?NNN.** <
27bc0 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69  li>  :VVV.** <li
27bd0 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20  >  @VVV.** <li> 
27be0 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a   $VVV.** </ul>.*
27bf0 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70  *.** In the temp
27c00 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e  lates above, NNN
27c10 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69   represents an i
27c20 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a  nteger literal,.
27c30 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 65  ** and VVV repre
27c40 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75  sents an alphanu
27c50 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69 65 72  meric identifier
27c60 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73  .)^  ^The values
27c70 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72   of these.** par
27c80 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61  ameters (also ca
27c90 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d  lled "host param
27ca0 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22  eter names" or "
27cb0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29  SQL parameters")
27cc0 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75  .** can be set u
27cd0 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
27ce0 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
27cf0 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e  es defined here.
27d00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
27d10 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
27d20 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
27d30 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61  () routines is a
27d40 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74  lways.** a point
27d50 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
27d60 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20  e3_stmt] object 
27d70 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a  returned from.**
27d80 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
27d90 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76  e_v2()] or its v
27da0 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  ariants..**.** ^
27db0 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
27dc0 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78  ent is the index
27dd0 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61   of the SQL para
27de0 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e  meter to be set.
27df0 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  .** ^The leftmos
27e00 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  t SQL parameter 
27e10 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20  has an index of 
27e20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61  1.  ^When the sa
27e30 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20  me named.** SQL 
27e40 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65  parameter is use
27e50 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65  d more than once
27e60 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62  , second and sub
27e70 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72  sequent.** occur
27e80 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20  rences have the 
27e90 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68  same index as th
27ea0 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e  e first occurren
27eb0 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65  ce..** ^The inde
27ec0 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61  x for named para
27ed0 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f  meters can be lo
27ee0 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68  oked up using th
27ef0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  e.** [sqlite3_bi
27f00 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
27f10 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73  ex()] API if des
27f20 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65  ired.  ^The inde
27f30 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20  x.** for "?NNN" 
27f40 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68  parameters is th
27f50 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a  e value of NNN..
27f60 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75  ** ^The NNN valu
27f70 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65  e must be betwee
27f80 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c  n 1 and the [sql
27f90 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a  ite3_limit()].**
27fa0 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49   parameter [SQLI
27fb0 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
27fc0 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75  E_NUMBER] (defau
27fd0 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a  lt value: 999)..
27fe0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64  **.** ^The third
27ff0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
28000 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74   value to bind t
28010 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  o the parameter.
28020 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72  .** ^If the thir
28030 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
28040 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
28050 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  () or sqlite3_bi
28060 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 6f  nd_text16().** o
28070 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  r sqlite3_bind_b
28080 6c 6f 62 28 29 20 69 73 20 61 20 4e 55 4c 4c 20  lob() is a NULL 
28090 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65  pointer then the
280a0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
280b0 72 0a 2a 2a 20 69 73 20 69 67 6e 6f 72 65 64 20  r.** is ignored 
280c0 61 6e 64 20 74 68 65 20 65 6e 64 20 72 65 73 75  and the end resu
280d0 6c 74 20 69 73 20 74 68 65 20 73 61 6d 65 20 61  lt is the same a
280e0 73 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e  s sqlite3_bind_n
280f0 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  ull()..**.** ^(I
28100 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73  n those routines
28110 20 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75   that have a fou
28120 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74  rth argument, it
28130 73 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a  s value is the.*
28140 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  * number of byte
28150 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74  s in the paramet
28160 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72  er.  To be clear
28170 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74  : the value is t
28180 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
28190 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20  <u>bytes</u> in 
281a0 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74  the value, not t
281b0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
281c0 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49  racters.)^.** ^I
281d0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
281e0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
281f0 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72  3_bind_text() or
28200 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
28210 78 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67  xt16().** is neg
28220 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20  ative, then the 
28230 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74  length of the st
28240 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e  ring is.** the n
28250 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75  umber of bytes u
28260 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a  p to the first z
28270 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a  ero terminator..
28280 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74 68  ** If the fourth
28290 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
282a0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
282b0 29 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  ) is negative, t
282c0 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61 76  hen.** the behav
282d0 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
282e0 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65  ..** If a non-ne
282f0 67 61 74 69 76 65 20 66 6f 75 72 74 68 20 70 61  gative fourth pa
28300 72 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76 69  rameter is provi
28310 64 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ded to sqlite3_b
28320 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72  ind_text().** or
28330 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
28340 78 74 31 36 28 29 20 74 68 65 6e 20 74 68 61 74  xt16() then that
28350 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20   parameter must 
28360 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73  be the byte offs
28370 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 20  et.** where the 
28380 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77  NUL terminator w
28390 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75 6d  ould occur assum
283a0 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20 77  ing the string w
283b0 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69  ere NUL.** termi
283c0 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e  nated.  If any N
283d0 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63  UL characters oc
283e0 63 75 72 20 61 74 20 62 79 74 65 20 6f 66 66 73  cur at byte offs
283f0 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a  ets less than .*
28400 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  * the value of t
28410 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
28420 74 65 72 20 74 68 65 6e 20 74 68 65 20 72 65 73  ter then the res
28430 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76 61  ulting string va
28440 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74  lue will.** cont
28450 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ain embedded NUL
28460 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 6f  s.  The result o
28470 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e  f expressions in
28480 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 0a  volving strings.
28490 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65 64  ** with embedded
284a0 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e   NULs is undefin
284b0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
284c0 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  ifth argument to
284d0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
284e0 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 69  ob(), sqlite3_bi
284f0 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a  nd_text(), and.*
28500 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  * sqlite3_bind_t
28510 65 78 74 31 36 28 29 20 69 73 20 61 20 64 65 73  ext16() is a des
28520 74 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20  tructor used to 
28530 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42  dispose of the B
28540 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67  LOB or.** string
28550 20 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61   after SQLite ha
28560 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
28570 69 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75  it.  ^The destru
28580 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a  ctor is called.*
28590 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20  * to dispose of 
285a0 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  the BLOB or stri
285b0 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 63  ng even if the c
285c0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  all to sqlite3_b
285d0 69 6e 64 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20 73  ind_blob(),.** s
285e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
285f0 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  (), or sqlite3_b
28600 69 6e 64 5f 74 65 78 74 31 36 28 29 20 66 61 69  ind_text16() fai
28610 6c 73 2e 20 20 0a 2a 2a 20 5e 49 66 20 74 68 65  ls.  .** ^If the
28620 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
28630 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61  is.** the specia
28640 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  l value [SQLITE_
28650 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51  STATIC], then SQ
28660 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61  Lite assumes tha
28670 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61  t the.** informa
28680 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69  tion is in stati
28690 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61  c, unmanaged spa
286a0 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20  ce and does not 
286b0 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 64  need to be freed
286c0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66  ..** ^If the fif
286d0 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20  th argument has 
286e0 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54  the value [SQLIT
286f0 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68  E_TRANSIENT], th
28700 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b  en.** SQLite mak
28710 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61  es its own priva
28720 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64  te copy of the d
28730 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c  ata immediately,
28740 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73   before.** the s
28750 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
28760 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e  routine returns.
28770 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
28780 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
28790 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64  b() routine bind
287a0 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67  s a BLOB of leng
287b0 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20  th N that.** is 
287c0 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f  filled with zero
287d0 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62  es.  ^A zeroblob
287e0 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d   uses a fixed am
287f0 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a  ount of memory.*
28800 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67  * (just an integ
28810 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73  er to hold its s
28820 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73  ize) while it is
28830 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64   being processed
28840 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61  ..** Zeroblobs a
28850 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73  re intended to s
28860 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c  erve as placehol
28870 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77  ders for BLOBs w
28880 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20  hose.** content 
28890 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e  is later written
288a0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
288b0 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69  e3_blob_open | i
288c0 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20  ncremental BLOB 
288d0 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  I/O] routines..*
288e0 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61  * ^A negative va
288f0 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f  lue for the zero
28900 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20  blob results in 
28910 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
28920 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  OB..**.** ^If an
28930 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  y of the sqlite3
28940 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
28950 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69  es are called wi
28960 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
28970 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72  r.** for the [pr
28980 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
28990 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72 65 70  ] or with a prep
289a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66  ared statement f
289b0 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c  or which.** [sql
289c0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
289d0 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72   been called mor
289e0 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20  e recently than 
289f0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
28a00 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63  ],.** then the c
28a10 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  all will return 
28a20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
28a30 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33    If any sqlite3
28a40 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74  _bind_().** rout
28a50 69 6e 65 20 69 73 20 70 61 73 73 65 64 20 61 20  ine is passed a 
28a60 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
28a70 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62 65  ent] that has be
28a80 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68  en finalized, th
28a90 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75  e.** result is u
28aa0 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f  ndefined and pro
28ab0 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a  bably harmful..*
28ac0 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61  *.** ^Bindings a
28ad0 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62  re not cleared b
28ae0 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  y the [sqlite3_r
28af0 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e  eset()] routine.
28b00 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72  .** ^Unbound par
28b10 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65  ameters are inte
28b20 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e  rpreted as NULL.
28b30 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
28b40 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69  te3_bind_* routi
28b50 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  nes return [SQLI
28b60 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
28b70 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f  s or an.** [erro
28b80 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68  r code] if anyth
28b90 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a  ing goes wrong..
28ba0 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47  ** ^[SQLITE_RANG
28bb0 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  E] is returned i
28bc0 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a  f the parameter.
28bd0 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20  ** index is out 
28be0 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c  of range.  ^[SQL
28bf0 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65  ITE_NOMEM] is re
28c00 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63  turned if malloc
28c10 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20  () fails..**.** 
28c20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
28c30 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
28c40 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b  r_count()],.** [
28c50 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
28c60 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20  ameter_name()], 
28c70 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  and [sqlite3_bin
28c80 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
28c90 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  x()]..*/.int sql
28ca0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73  ite3_bind_blob(s
28cb0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
28cc0 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
28cd0 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76  int n, void(*)(v
28ce0 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
28cf0 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28  te3_bind_double(
28d00 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
28d10 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74  nt, double);.int
28d20 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e   sqlite3_bind_in
28d30 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
28d40 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20   int, int);.int 
28d50 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74  sqlite3_bind_int
28d60 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
28d70 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69  , int, sqlite3_i
28d80 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74  nt64);.int sqlit
28d90 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c  e3_bind_null(sql
28da0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29  ite3_stmt*, int)
28db0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
28dc0 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  nd_text(sqlite3_
28dd0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
28de0 74 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20  t char*, int n, 
28df0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
28e00 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
28e10 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  d_text16(sqlite3
28e20 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
28e30 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
28e40 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
28e50 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
28e60 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73  _value(sqlite3_s
28e70 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
28e80 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29   sqlite3_value*)
28e90 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
28ea0 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69  nd_zeroblob(sqli
28eb0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
28ec0 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int n);../*.** C
28ed0 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
28ee0 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72  Of SQL Parameter
28ef0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  s.**.** ^This ro
28f00 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65  utine can be use
28f10 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75  d to find the nu
28f20 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72  mber of [SQL par
28f30 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61  ameters].** in a
28f40 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
28f50 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61  ment].  SQL para
28f60 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e  meters are token
28f70 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d  s of the.** form
28f80 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a   "?", "?NNN", ":
28f90 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72  AAA", "$AAA", or
28fa0 20 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72   "@AAA" that ser
28fb0 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f  ve as.** placeho
28fc0 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73  lders for values
28fd0 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74   that are [sqlit
28fe0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62  e3_bind_blob | b
28ff0 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20  ound].** to the 
29000 70 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20  parameters at a 
29010 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a  later time..**.*
29020 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65  * ^(This routine
29030 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e   actually return
29040 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
29050 68 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68  he largest (righ
29060 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65  tmost).** parame
29070 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72  ter. For all for
29080 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20  ms except ?NNN, 
29090 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73  this will corres
290a0 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e  pond to the.** n
290b0 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20  umber of unique 
290c0 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20  parameters.  If 
290d0 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  parameters of th
290e0 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20  e ?NNN form are 
290f0 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d  used,.** there m
29100 61 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68  ay be gaps in th
29110 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  e list.)^.**.** 
29120 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
29130 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
29140 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
29150 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
29160 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
29170 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
29180 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
29190 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e  _index()]..*/.in
291a0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  t sqlite3_bind_p
291b0 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73  arameter_count(s
291c0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
291d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
291e0 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50  Name Of A Host P
291f0 61 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e  arameter.**.** ^
29200 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
29210 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
29220 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72  P,N) interface r
29230 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61  eturns.** the na
29240 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b  me of the N-th [
29250 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69  SQL parameter] i
29260 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  n the [prepared 
29270 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a  statement] P..**
29280 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72   ^(SQL parameter
29290 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f  s of the form "?
292a0 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f  NNN" or ":AAA" o
292b0 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41  r "@AAA" or "$AA
292c0 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d  A".** have a nam
292d0 65 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73  e which is the s
292e0 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20  tring "?NNN" or 
292f0 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22  ":AAA" or "@AAA"
29300 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65   or "$AAA".** re
29310 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49  spectively..** I
29320 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
29330 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f  he initial ":" o
29340 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20  r "$" or "@" or 
29350 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64  "?".** is includ
29360 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  ed as part of th
29370 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61  e name.)^.** ^Pa
29380 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
29390 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74  form "?" without
293a0 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74   a following int
293b0 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d  eger have no nam
293c0 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66  e.** and are ref
293d0 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d  erred to as "nam
293e0 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79  eless" or "anony
293f0 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22  mous parameters"
29400 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
29410 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  st host paramete
29420 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f  r has an index o
29430 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a  f 1, not 0..**.*
29440 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20  * ^If the value 
29450 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
29460 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68  e or if the N-th
29470 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a   parameter is.**
29480 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20   nameless, then 
29490 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64  NULL is returned
294a0 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  .  ^The returned
294b0 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c   string is.** al
294c0 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e  ways in UTF-8 en
294d0 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74  coding even if t
294e0 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74  he named paramet
294f0 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e  er was.** origin
29500 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61  ally specified a
29510 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c  s UTF-16 in [sql
29520 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
29530 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
29540 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
29550 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
29560 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
29570 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
29580 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
29590 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
295a0 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a  _count()], and.*
295b0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
295c0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
295d0 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  )]..*/.const cha
295e0 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  r *sqlite3_bind_
295f0 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73  parameter_name(s
29600 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
29610 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
29620 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20  REF: Index Of A 
29630 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41  Parameter With A
29640 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a   Given Name.**.*
29650 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e  * ^Return the in
29660 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61  dex of an SQL pa
29670 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74  rameter given it
29680 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a  s name.  ^The.**
29690 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74   index value ret
296a0 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c  urned is suitabl
296b0 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65  e for use as the
296c0 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d   second.** param
296d0 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
296e0 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
296f0 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20  e3_bind()].  ^A 
29700 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72  zero.** is retur
29710 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69  ned if no matchi
29720 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ng parameter is 
29730 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72  found.  ^The par
29740 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d  ameter.** name m
29750 75 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20  ust be given in 
29760 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68  UTF-8 even if th
29770 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65  e original state
29780 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70  ment.** was prep
29790 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36  ared from UTF-16
297a0 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c   text using [sql
297b0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
297c0 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  2()]..**.** See 
297d0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
297e0 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
297f0 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
29800 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
29810 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61  eter_count()], a
29820 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
29830 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
29840 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  dex()]..*/.int s
29850 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
29860 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69  meter_index(sqli
29870 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74  te3_stmt*, const
29880 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a   char *zName);..
29890 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
298a0 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e  Reset All Bindin
298b0 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64  gs On A Prepared
298c0 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a   Statement.**.**
298d0 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68   ^Contrary to th
298e0 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d  e intuition of m
298f0 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65  any, [sqlite3_re
29900 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20  set()] does not 
29910 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71  reset.** the [sq
29920 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
29930 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61  | bindings] on a
29940 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
29950 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74  ment]..** ^Use t
29960 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72  his routine to r
29970 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61  eset all host pa
29980 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c  rameters to NULL
29990 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
299a0 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28  _clear_bindings(
299b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
299c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
299d0 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d   Number Of Colum
299e0 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53  ns In A Result S
299f0 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e  et.**.** ^Return
29a00 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
29a10 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
29a20 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65  sult set returne
29a30 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65  d by the.** [pre
29a40 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
29a50 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  . ^This routine 
29a60 72 65 74 75 72 6e 73 20 30 20 69 66 20 70 53 74  returns 0 if pSt
29a70 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20  mt is an SQL.** 
29a80 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64  statement that d
29a90 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64  oes not return d
29aa0 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  ata (for example
29ab0 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a   an [UPDATE])..*
29ac0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
29ad0 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
29ae0 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  nt()].*/.int sql
29af0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
29b00 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
29b10 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
29b20 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20  API3REF: Column 
29b30 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c  Names In A Resul
29b40 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  t Set.**.** ^The
29b50 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
29b60 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69  rn the name assi
29b70 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69 63  gned to a partic
29b80 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  ular column.** i
29b90 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
29ba0 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73   of a [SELECT] s
29bb0 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20  tatement.  ^The 
29bc0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
29bd0 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  ame().** interfa
29be0 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
29bf0 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74  nter to a zero-t
29c00 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
29c10 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71  string.** and sq
29c20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
29c30 65 31 36 28 29 20 72 65 74 75 72 6e 73 20 61 20  e16() returns a 
29c40 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72  pointer to a zer
29c50 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
29c60 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20  UTF-16 string.  
29c70 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  ^The first param
29c80 65 74 65 72 20 69 73 20 74 68 65 20 5b 70 72 65  eter is the [pre
29c90 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
29ca0 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  .** that impleme
29cb0 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d  nts the [SELECT]
29cc0 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65   statement. ^The
29cd0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
29ce0 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75  r is the.** colu
29cf0 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65  mn number.  ^The
29d00 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e   leftmost column
29d10 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a   is number 0..**
29d20 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65  .** ^The returne
29d30 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72  d string pointer
29d40 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20   is valid until 
29d50 65 69 74 68 65 72 20 74 68 65 20 5b 70 72 65 70  either the [prep
29d60 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
29d70 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64 20  ** is destroyed 
29d80 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  by [sqlite3_fina
29d90 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c  lize()] or until
29da0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
29db0 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  s automatically.
29dc0 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79  ** reprepared by
29dd0 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20   the first call 
29de0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
29df0 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63  ()] for a partic
29e00 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75  ular run.** or u
29e10 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61  ntil the next ca
29e20 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ll to.** sqlite3
29e30 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f  _column_name() o
29e40 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
29e50 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65  _name16() on the
29e60 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a   same column..**
29e70 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
29e80 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64  malloc() fails d
29e90 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73  uring the proces
29ea0 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72  sing of either r
29eb0 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65  outine.** (for e
29ec0 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20  xample during a 
29ed0 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20  conversion from 
29ee0 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29  UTF-8 to UTF-16)
29ef0 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20   then a.** NULL 
29f00 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72  pointer is retur
29f10 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
29f20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74  name of a result
29f30 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76   column is the v
29f40 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53 22  alue of the "AS"
29f50 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74   clause for.** t
29f60 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74  hat column, if t
29f70 68 65 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c  here is an AS cl
29f80 61 75 73 65 2e 20 20 49 66 20 74 68 65 72 65 20  ause.  If there 
29f90 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a  is no AS clause.
29fa0 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65  ** then the name
29fb0 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69   of the column i
29fc0 73 20 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e  s unspecified an
29fd0 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f  d may change fro
29fe0 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65  m.** one release
29ff0 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68   of SQLite to th
2a000 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74  e next..*/.const
2a010 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
2a020 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74  olumn_name(sqlit
2a030 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29  e3_stmt*, int N)
2a040 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
2a050 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
2a060 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
2a070 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a  *, int N);../*.*
2a080 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72  * CAPI3REF: Sour
2a090 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20  ce Of Data In A 
2a0a0 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a  Query Result.**.
2a0b0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
2a0c0 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61  es provide a mea
2a0d0 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ns to determine 
2a0e0 74 68 65 20 64 61 74 61 62 61 73 65 2c 20 74 61  the database, ta
2a0f0 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c  ble, and.** tabl
2a100 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73  e column that is
2a110 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61   the origin of a
2a120 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 73 75   particular resu
2a130 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20  lt column in.** 
2a140 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
2a150 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  nt..** ^The name
2a160 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
2a170 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c   or table or col
2a180 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72  umn can be retur
2a190 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72  ned as.** either
2a1a0 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d   a UTF-8 or UTF-
2a1b0 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65  16 string.  ^The
2a1c0 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74   _database_ rout
2a1d0 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74  ines return.** t
2a1e0 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65  he database name
2a1f0 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f  , the _table_ ro
2a200 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
2a210 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e  e table name, an
2a220 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f  d.** the origin_
2a230 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
2a240 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65   the column name
2a250 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  ..** ^The return
2a260 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c  ed string is val
2a270 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72  id until the [pr
2a280 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2a290 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a  ] is destroyed.*
2a2a0 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  * using [sqlite3
2a2b0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
2a2c0 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d  until the statem
2a2d0 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ent is automatic
2a2e0 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72  ally.** reprepar
2a2f0 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
2a300 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2a310 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70  _step()] for a p
2a320 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a  articular run.**
2a330 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61   or until the sa
2a340 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  me information i
2a350 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61  s requested.** a
2a360 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72  gain in a differ
2a370 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a  ent encoding..**
2a380 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72  .** ^The names r
2a390 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20  eturned are the 
2a3a0 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61  original un-alia
2a3b0 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65  sed names of the
2a3c0 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61  .** database, ta
2a3d0 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e  ble, and column.
2a3e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
2a3f0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
2a400 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 69  ese interfaces i
2a410 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  s a [prepared st
2a420 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68  atement]..** ^Th
2a430 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  ese functions re
2a440 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  turn information
2a450 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72   about the Nth r
2a460 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74  esult column ret
2a470 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20  urned by.** the 
2a480 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65  statement, where
2a490 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64   N is the second
2a4a0 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65   function argume
2a4b0 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74  nt..** ^The left
2a4c0 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20  -most column is 
2a4d0 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65  column 0 for the
2a4e0 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  se routines..**.
2a4f0 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63  ** ^If the Nth c
2a500 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62  olumn returned b
2a510 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  y the statement 
2a520 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e  is an expression
2a530 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20   or.** subquery 
2a540 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c  and is not a col
2a550 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20  umn value, then 
2a560 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e  all of these fun
2a570 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a  ctions return.**
2a580 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72   NULL.  ^These r
2a590 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73  outine might als
2a5a0 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66  o return NULL if
2a5b0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
2a5c0 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63  tion error.** oc
2a5d0 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73  curs.  ^Otherwis
2a5e0 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74  e, they return t
2a5f0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61  he name of the a
2a600 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
2a610 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63  , table,.** or c
2a620 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79  olumn that query
2a630 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77   result column w
2a640 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f  as extracted fro
2a650 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74  m..**.** ^As wit
2a660 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69  h all other SQLi
2a670 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77  te APIs, those w
2a680 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77  hose names end w
2a690 69 74 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a  ith "16" return.
2a6a0 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  ** UTF-16 encode
2a6b0 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68  d strings and th
2a6c0 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e  e other function
2a6d0 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a  s return UTF-8..
2a6e0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49  **.** ^These API
2a6f0 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c  s are only avail
2a700 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72  able if the libr
2a710 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64  ary was compiled
2a720 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51   with the.** [SQ
2a730 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55  LITE_ENABLE_COLU
2a740 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70  MN_METADATA] C-p
2a750 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62  reprocessor symb
2a760 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f  ol..**.** If two
2a770 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73   or more threads
2a780 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72   call one or mor
2a790 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
2a7a0 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20  nes against the 
2a7b0 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64  same.** prepared
2a7c0 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63   statement and c
2a7d0 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d  olumn at the sam
2a7e0 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20  e time then the 
2a7f0 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75  results are.** u
2a800 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
2a810 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74  If two or more t
2a820 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20  hreads call one 
2a830 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69  or more.** [sqli
2a840 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
2a850 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d  ase_name | colum
2a860 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72  n metadata inter
2a870 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68  faces].** for th
2a880 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64  e same [prepared
2a890 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20   statement] and 
2a8a0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  result column.**
2a8b0 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
2a8c0 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  e then the resul
2a8d0 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
2a8e0 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
2a8f0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2a900 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71  database_name(sq
2a910 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2a920 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
2a930 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
2a940 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c  abase_name16(sql
2a950 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
2a960 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
2a970 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
2a980 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  e_name(sqlite3_s
2a990 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
2a9a0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
2a9b0 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65  olumn_table_name
2a9c0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2a9d0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61  ,int);.const cha
2a9e0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
2a9f0 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71  n_origin_name(sq
2aa00 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2aa10 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
2aa20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
2aa30 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  gin_name16(sqlit
2aa40 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a  e3_stmt*,int);..
2aa50 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2aa60 44 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70  Declared Datatyp
2aa70 65 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73  e Of A Query Res
2aa80 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ult.**.** ^(The 
2aa90 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
2aaa0 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  is a [prepared s
2aab0 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66  tatement]..** If
2aac0 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20   this statement 
2aad0 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74  is a [SELECT] st
2aae0 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20  atement and the 
2aaf0 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  Nth column of th
2ab00 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65  e.** returned re
2ab10 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74  sult set of that
2ab20 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74   [SELECT] is a t
2ab30 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74  able column (not
2ab40 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f   an.** expressio
2ab50 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74  n or subquery) t
2ab60 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64  hen the declared
2ab70 20 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62   type of the tab
2ab80 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20  le.** column is 
2ab90 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66  returned.)^  ^If
2aba0 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
2abb0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
2abc0 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65  t is an.** expre
2abd0 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72  ssion or subquer
2abe0 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70  y, then a NULL p
2abf0 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e  ointer is return
2ac00 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  ed..** ^The retu
2ac10 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61  rned string is a
2ac20 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f  lways UTF-8 enco
2ac30 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72  ded..**.** ^(For
2ac40 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20   example, given 
2ac50 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  the database sch
2ac60 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54  ema:.**.** CREAT
2ac70 45 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41  E TABLE t1(c1 VA
2ac80 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e  RIANT);.**.** an
2ac90 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  d the following 
2aca0 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20  statement to be 
2acb0 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20  compiled:.**.** 
2acc0 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63  SELECT c1 + 1, c
2acd0 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a  1 FROM t1;.**.**
2ace0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f   this routine wo
2acf0 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73  uld return the s
2ad00 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20  tring "VARIANT" 
2ad10 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72  for the second r
2ad20 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  esult.** column 
2ad30 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55  (i==1), and a NU
2ad40 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74  LL pointer for t
2ad50 68 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20  he first result 
2ad60 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e  column (i==0).)^
2ad70 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75  .**.** ^SQLite u
2ad80 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d  ses dynamic run-
2ad90 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53  time typing.  ^S
2ada0 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 61  o just because a
2adb0 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65   column.** is de
2adc0 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69  clared to contai
2add0 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74  n a particular t
2ade0 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61  ype does not mea
2adf0 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61  n that the.** da
2ae00 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61  ta stored in tha
2ae10 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74  t column is of t
2ae20 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65  he declared type
2ae30 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20  .  SQLite is.** 
2ae40 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20  strongly typed, 
2ae50 62 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 69  but the typing i
2ae60 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74  s dynamic not st
2ae70 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20  atic.  ^Type.** 
2ae80 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  is associated wi
2ae90 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61  th individual va
2aea0 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74  lues, not with t
2aeb0 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a  he containers.**
2aec0 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68   used to hold th
2aed0 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63  ose values..*/.c
2aee0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
2aef0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
2af00 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  pe(sqlite3_stmt*
2af10 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
2af20 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2af30 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c  n_decltype16(sql
2af40 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
2af50 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2af60 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51  : Evaluate An SQ
2af70 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a  L Statement.**.*
2af80 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 61  * After a [prepa
2af90 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68  red statement] h
2afa0 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64  as been prepared
2afb0 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a   using either.**
2afc0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2afd0 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
2afe0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2aff0 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68  ()] or one of th
2b000 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
2b010 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f  rfaces [sqlite3_
2b020 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73  prepare()] or [s
2b030 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2b040 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69  ()], this functi
2b050 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61  on.** must be ca
2b060 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  lled one or more
2b070 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61   times to evalua
2b080 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  te the statement
2b090 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61  ..**.** The deta
2b0a0 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 76  ils of the behav
2b0b0 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74  ior of the sqlit
2b0c0 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66  e3_step() interf
2b0d0 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e  ace depend.** on
2b0e0 20 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61   whether the sta
2b0f0 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61  tement was prepa
2b100 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65  red using the ne
2b110 77 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 61  wer "v2" interfa
2b120 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ce.** [sqlite3_p
2b130 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
2b140 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2b150 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65  e16_v2()] or the
2b160 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a   older legacy.**
2b170 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69   interface [sqli
2b180 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61  te3_prepare()] a
2b190 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
2b1a0 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75  are16()].  The u
2b1b0 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77  se of the.** new
2b1c0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20   "v2" interface 
2b1d0 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  is recommended f
2b1e0 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  or new applicati
2b1f0 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 61  ons but the lega
2b200 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  cy.** interface 
2b210 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f  will continue to
2b220 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a   be supported..*
2b230 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67  *.** ^In the leg
2b240 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74  acy interface, t
2b250 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
2b260 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b  will be either [
2b270 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a  SQLITE_BUSY],.**
2b280 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20   [SQLITE_DONE], 
2b290 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53  [SQLITE_ROW], [S
2b2a0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72  QLITE_ERROR], or
2b2b0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
2b2c0 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22  ..** ^With the "
2b2d0 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61  v2" interface, a
2b2e0 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20  ny of the other 
2b2f0 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f  [result codes] o
2b300 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  r.** [extended r
2b310 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67  esult codes] mig
2b320 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61  ht be returned a
2b330 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b  s well..**.** ^[
2b340 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61  SQLITE_BUSY] mea
2b350 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61  ns that the data
2b360 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20  base engine was 
2b370 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72  unable to acquir
2b380 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  e the.** databas
2b390 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73  e locks it needs
2b3a0 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20   to do its job. 
2b3b0 20 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d 65   ^If the stateme
2b3c0 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d  nt is a [COMMIT]
2b3d0 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75  .** or occurs ou
2b3e0 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c  tside of an expl
2b3f0 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
2b400 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72  , then you can r
2b410 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74  etry the.** stat
2b420 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73  ement.  If the s
2b430 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20  tatement is not 
2b440 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f  a [COMMIT] and o
2b450 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 6e 0a  ccurs within an.
2b460 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  ** explicit tran
2b470 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75  saction then you
2b480 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b   should rollback
2b490 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
2b4a0 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69   before.** conti
2b4b0 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53  nuing..**.** ^[S
2b4c0 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e  QLITE_DONE] mean
2b4d0 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65  s that the state
2b4e0 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65  ment has finishe
2b4f0 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73  d executing.** s
2b500 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71  uccessfully.  sq
2b510 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f  lite3_step() sho
2b520 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65  uld not be calle
2b530 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20  d again on this 
2b540 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69  virtual.** machi
2b550 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 74  ne without first
2b560 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
2b570 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65  3_reset()] to re
2b580 73 65 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a  set the virtual.
2b590 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20  ** machine back 
2b5a0 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73  to its initial s
2b5b0 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  tate..**.** ^If 
2b5c0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
2b5d0 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64  t being executed
2b5e0 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74   returns any dat
2b5f0 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f  a, then [SQLITE_
2b600 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72  ROW].** is retur
2b610 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20  ned each time a 
2b620 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20  new row of data 
2b630 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f  is ready for pro
2b640 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a  cessing by the.*
2b650 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61  * caller. The va
2b660 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65  lues may be acce
2b670 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b  ssed using the [
2b680 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
2b690 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c  nctions]..** sql
2b6a0 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63  ite3_step() is c
2b6b0 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72  alled again to r
2b6c0 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74  etrieve the next
2b6d0 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a   row of data..**
2b6e0 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52  .** ^[SQLITE_ERR
2b6f0 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61  OR] means that a
2b700 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20   run-time error 
2b710 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74  (such as a const
2b720 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69  raint.** violati
2b730 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64  on) has occurred
2b740 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
2b750 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
2b760 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a  called again on.
2b770 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20  ** the VM. More 
2b780 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20  information may 
2b790 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c  be found by call
2b7a0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  ing [sqlite3_err
2b7b0 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68  msg()]..** ^With
2b7c0 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
2b7d0 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70  rface, a more sp
2b7e0 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64  ecific error cod
2b7f0 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a  e (for example,.
2b800 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  ** [SQLITE_INTER
2b810 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53  RUPT], [SQLITE_S
2b820 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f  CHEMA], [SQLITE_
2b830 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f  CORRUPT], and so
2b840 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62   forth).** can b
2b850 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61  e obtained by ca
2b860 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
2b870 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a  eset()] on the.*
2b880 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
2b890 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65  ement].  ^In the
2b8a0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c   "v2" interface,
2b8b0 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65  .** the more spe
2b8c0 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65  cific error code
2b8d0 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72   is returned dir
2b8e0 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33  ectly by sqlite3
2b8f0 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b  _step()..**.** [
2b900 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d  SQLITE_MISUSE] m
2b910 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68  eans that the th
2b920 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63  is routine was c
2b930 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69  alled inappropri
2b940 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70  ately..** Perhap
2b950 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20  s it was called 
2b960 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  on a [prepared s
2b970 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68  tatement] that h
2b980 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65  as.** already be
2b990 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  en [sqlite3_fina
2b9a0 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64  lize | finalized
2b9b0 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74  ] or on one that
2b9c0 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73   had.** previous
2b9d0 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  ly returned [SQL
2b9e0 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53  ITE_ERROR] or [S
2b9f0 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72  QLITE_DONE].  Or
2ba00 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20   it could.** be 
2ba10 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68  the case that th
2ba20 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
2ba30 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65  connection is be
2ba40 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20  ing used by two 
2ba50 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61  or.** more threa
2ba60 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d  ds at the same m
2ba70 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a  oment in time..*
2ba80 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72  *.** For all ver
2ba90 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
2baa0 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64  up to and includ
2bab0 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20  ing 3.6.23.1, a 
2bac0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
2bad0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61 73  te3_reset()] was
2bae0 20 72 65 71 75 69 72 65 64 20 61 66 74 65 72 20   required after 
2baf0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72  sqlite3_step() r
2bb00 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67  eturned anything
2bb10 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  .** other than [
2bb20 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f  SQLITE_ROW] befo
2bb30 72 65 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e  re any subsequen
2bb40 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a  t invocation of.
2bb50 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
2bb60 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20 72  ).  Failure to r
2bb70 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65  eset the prepare
2bb80 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  d statement usin
2bb90 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  g .** [sqlite3_r
2bba0 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72 65  eset()] would re
2bbb0 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49  sult in an [SQLI
2bbc0 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72  TE_MISUSE] retur
2bbd0 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65  n from.** sqlite
2bbe0 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20 61  3_step().  But a
2bbf0 66 74 65 72 20 76 65 72 73 69 6f 6e 20 33 2e 36  fter version 3.6
2bc00 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f 73  .23.1, sqlite3_s
2bc10 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63  tep() began.** c
2bc20 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
2bc30 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74  reset()] automat
2bc40 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63  ically in this c
2bc50 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68  ircumstance rath
2bc60 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72  er.** than retur
2bc70 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53  ning [SQLITE_MIS
2bc80 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e  USE].  This is n
2bc90 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20  ot considered a 
2bca0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a  compatibility.**
2bcb0 20 62 72 65 61 6b 20 62 65 63 61 75 73 65 20 61   break because a
2bcc0 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  ny application t
2bcd0 68 61 74 20 65 76 65 72 20 72 65 63 65 69 76 65  hat ever receive
2bce0 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55  s an SQLITE_MISU
2bcf0 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62  SE error.** is b
2bd00 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74  roken by definit
2bd10 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ion.  The [SQLIT
2bd20 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54  E_OMIT_AUTORESET
2bd30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
2bd40 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20  ption.** can be 
2bd50 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20  used to restore 
2bd60 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  the legacy behav
2bd70 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f  ior..**.** <b>Go
2bd80 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c  ofy Interface Al
2bd90 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20  ert:</b> In the 
2bda0 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
2bdb0 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74  , the sqlite3_st
2bdc0 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61  ep().** API alwa
2bdd0 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e  ys returns a gen
2bde0 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c  eric error code,
2bdf0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
2be00 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a   following any.*
2be10 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68  * error other th
2be20 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  an [SQLITE_BUSY]
2be30 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53   and [SQLITE_MIS
2be40 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20  USE].  You must 
2be50 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  call.** [sqlite3
2be60 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
2be70 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2be80 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  ] in order to fi
2be90 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a  nd one of the.**
2bea0 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72   specific [error
2beb0 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74   codes] that bet
2bec0 74 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68  ter describes th
2bed0 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61  e error..** We a
2bee0 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69  dmit that this i
2bef0 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e  s a goofy design
2bf00 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68  .  The problem h
2bf10 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a  as been fixed.**
2bf20 20 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69   with the "v2" i
2bf30 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f  nterface.  If yo
2bf40 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66  u prepare all of
2bf50 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d   your SQL statem
2bf60 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69  ents.** using ei
2bf70 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ther [sqlite3_pr
2bf80 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
2bf90 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2bfa0 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a  6_v2()] instead.
2bfb0 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79  ** of the legacy
2bfc0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2bfd0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
2bfe0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 69  3_prepare16()] i
2bff0 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68  nterfaces,.** th
2c000 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63  en the more spec
2c010 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65  ific [error code
2c020 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20  s] are returned 
2c030 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73  directly.** by s
2c040 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
2c050 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22  The use of the "
2c060 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73  v2" interface is
2c070 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f   recommended..*/
2c080 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65  .int sqlite3_ste
2c090 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  p(sqlite3_stmt*)
2c0a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2c0b0 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  F: Number of col
2c0c0 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74  umns in a result
2c0d0 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20   set.**.** ^The 
2c0e0 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
2c0f0 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63 65 20  nt(P) interface 
2c100 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
2c110 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
2c120 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20   the.** current 
2c130 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
2c140 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72  t set of [prepar
2c150 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e  ed statement] P.
2c160 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64  .** ^If prepared
2c170 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65   statement P doe
2c180 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c  s not have resul
2c190 74 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 75  ts ready to retu
2c1a0 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73  rn.** (via calls
2c1b0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
2c1c0 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71  _column_int | sq
2c1d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29  lite3_column_*()
2c1e0 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63  ] of.** interfac
2c1f0 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33  es) then sqlite3
2c200 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72  _data_count(P) r
2c210 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68  eturns 0..** ^Th
2c220 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
2c230 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20  ount(P) routine 
2c240 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69  also returns 0 i
2c250 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  f P is a NULL po
2c260 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73  inter..** ^The s
2c270 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
2c280 74 28 50 29 20 72 6f 75 74 69 6e 65 20 72 65 74  t(P) routine ret
2c290 75 72 6e 73 20 30 20 69 66 20 74 68 65 20 70 72  urns 0 if the pr
2c2a0 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a  evious call to.*
2c2b0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d  * [sqlite3_step]
2c2c0 28 50 29 20 72 65 74 75 72 6e 65 64 20 5b 53 51  (P) returned [SQ
2c2d0 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68  LITE_DONE].  ^Th
2c2e0 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
2c2f0 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20  ount(P).** will 
2c300 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20  return non-zero 
2c310 69 66 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  if previous call
2c320 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
2c330 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 0a 2a  p](P) returned.*
2c340 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  * [SQLITE_ROW], 
2c350 65 78 63 65 70 74 20 69 6e 20 74 68 65 20 63 61  except in the ca
2c360 73 65 20 6f 66 20 74 68 65 20 5b 50 52 41 47 4d  se of the [PRAGM
2c370 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61  A incremental_va
2c380 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69  cuum].** where i
2c390 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  t always returns
2c3a0 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 63 68   zero since each
2c3b0 20 73 74 65 70 20 6f 66 20 74 68 61 74 20 6d 75   step of that mu
2c3c0 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67  lti-step.** prag
2c3d0 6d 61 20 72 65 74 75 72 6e 73 20 30 20 63 6f 6c  ma returns 0 col
2c3e0 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a  umns of data..**
2c3f0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
2c400 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
2c410 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71  unt()].*/.int sq
2c420 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2c430 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
2c440 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
2c450 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e  PI3REF: Fundamen
2c460 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a  tal Datatypes.**
2c470 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54   KEYWORDS: SQLIT
2c480 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45  E_TEXT.**.** ^(E
2c490 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51  very value in SQ
2c4a0 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20  Lite has one of 
2c4b0 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c  five fundamental
2c4c0 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a   datatypes:.**.*
2c4d0 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36  * <ul>.** <li> 6
2c4e0 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
2c4f0 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d  eger.** <li> 64-
2c500 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e  bit IEEE floatin
2c510 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a  g point number.*
2c520 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a  * <li> string.**
2c530 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c   <li> BLOB.** <l
2c540 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e  i> NULL.** </ul>
2c550 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  )^.**.** These c
2c560 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64  onstants are cod
2c570 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74  es for each of t
2c580 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a  hose types..**.*
2c590 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  * Note that the 
2c5a0 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73  SQLITE_TEXT cons
2c5b0 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73  tant was also us
2c5c0 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72  ed in SQLite ver
2c5d0 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20  sion 2.** for a 
2c5e0 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65  completely diffe
2c5f0 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53  rent meaning.  S
2c600 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e  oftware that lin
2c610 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a  ks against both.
2c620 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  ** SQLite versio
2c630 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76  n 2 and SQLite v
2c640 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20  ersion 3 should 
2c650 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54  use SQLITE3_TEXT
2c660 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f  , not.** SQLITE_
2c670 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  TEXT..*/.#define
2c680 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20   SQLITE_INTEGER 
2c690 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
2c6a0 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65  E_FLOAT    2.#de
2c6b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42  fine SQLITE_BLOB
2c6c0 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
2c6d0 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35  QLITE_NULL     5
2c6e0 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54  .#ifdef SQLITE_T
2c6f0 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  EXT.# undef SQLI
2c700 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20  TE_TEXT.#else.# 
2c710 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45  define SQLITE_TE
2c720 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a  XT     3.#endif.
2c730 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f  #define SQLITE3_
2c740 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a  TEXT     3../*.*
2c750 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75  * CAPI3REF: Resu
2c760 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41  lt Values From A
2c770 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52   Query.** KEYWOR
2c780 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65  DS: {column acce
2c790 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a  ss functions}.**
2c7a0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
2c7b0 65 73 20 66 6f 72 6d 20 74 68 65 20 22 72 65 73  es form the "res
2c7c0 75 6c 74 20 73 65 74 22 20 69 6e 74 65 72 66 61  ult set" interfa
2c7d0 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ce..**.** ^These
2c7e0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
2c7f0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
2c800 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75  ut a single colu
2c810 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  mn of the curren
2c820 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20  t.** result row 
2c830 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e  of a query.  ^In
2c840 20 65 76 65 72 79 20 63 61 73 65 20 74 68 65 20   every case the 
2c850 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
2c860 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  s a pointer.** t
2c870 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  o the [prepared 
2c880 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
2c890 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74  is being evaluat
2c8a0 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33  ed (the [sqlite3
2c8b0 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20  _stmt*].** that 
2c8c0 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f  was returned fro
2c8d0 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  m [sqlite3_prepa
2c8e0 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20  re_v2()] or one 
2c8f0 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29  of its variants)
2c900 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f  .** and the seco
2c910 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
2c920 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
2c930 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68  column for which
2c940 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
2c950 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e  should be return
2c960 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  ed. ^The leftmos
2c970 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  t column of the 
2c980 72 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 74  result set has t
2c990 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e  he index 0..** ^
2c9a0 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  The number of co
2c9b0 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
2c9c0 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65 72  ult can be deter
2c9d0 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b  mined using.** [
2c9e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
2c9f0 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  ount()]..**.** I
2ca00 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
2ca10 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72  ent does not cur
2ca20 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20  rently point to 
2ca30 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20  a valid row, or 
2ca40 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e  if the.** column
2ca50 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66   index is out of
2ca60 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75   range, the resu
2ca70 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  lt is undefined.
2ca80 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
2ca90 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63  es may only be c
2caa0 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d  alled when the m
2cab0 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
2cac0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  to.** [sqlite3_s
2cad0 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72  tep()] has retur
2cae0 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  ned [SQLITE_ROW]
2caf0 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20   and neither.** 
2cb00 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2cb10 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  ] nor [sqlite3_f
2cb20 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20  inalize()] have 
2cb30 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73  been called subs
2cb40 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20  equently..** If 
2cb50 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75  any of these rou
2cb60 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
2cb70 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
2cb80 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b  reset()] or.** [
2cb90 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2cba0 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71  ()] or after [sq
2cbb0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
2cbc0 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f  s returned.** so
2cbd0 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68  mething other th
2cbe0 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  an [SQLITE_ROW],
2cbf0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
2cc00 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49   undefined..** I
2cc10 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  f [sqlite3_step(
2cc20 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
2cc30 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
2cc40 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a  te3_finalize()].
2cc50 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72  ** are called fr
2cc60 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74  om a different t
2cc70 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20  hread while any 
2cc80 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
2cc90 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67  s.** are pending
2cca0 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  , then the resul
2ccb0 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
2ccc0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2ccd0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
2cce0 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
2ccf0 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  ns the.** [SQLIT
2cd00 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61  E_INTEGER | data
2cd10 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74  type code] for t
2cd20 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20  he initial data 
2cd30 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72  type.** of the r
2cd40 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e  esult column.  ^
2cd50 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c  The returned val
2cd60 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  ue is one of [SQ
2cd70 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a  LITE_INTEGER],.*
2cd80 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d  * [SQLITE_FLOAT]
2cd90 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c  , [SQLITE_TEXT],
2cda0 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20   [SQLITE_BLOB], 
2cdb0 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d  or [SQLITE_NULL]
2cdc0 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20  .  The value.** 
2cdd0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
2cde0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
2cdf0 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e  ) is only meanin
2ce00 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a  gful if no type.
2ce10 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68  ** conversions h
2ce20 61 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20  ave occurred as 
2ce30 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e  described below.
2ce40 20 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63    After a type c
2ce50 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68  onversion,.** th
2ce60 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
2ce70 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
2ce80 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64  mn_type() is und
2ce90 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a  efined.  Future.
2cea0 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  ** versions of S
2ceb0 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65  QLite may change
2cec0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
2ced0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2cee0 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77  type().** follow
2cef0 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65  ing a type conve
2cf00 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  rsion..**.** ^If
2cf10 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
2cf20 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73   BLOB or UTF-8 s
2cf30 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73  tring then the s
2cf40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2cf50 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  tes().** routine
2cf60 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
2cf70 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
2cf80 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72  that BLOB or str
2cf90 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
2cfa0 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d  result is a UTF-
2cfb0 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  16 string, then 
2cfc0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2cfd0 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a  ytes() converts.
2cfe0 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f  ** the string to
2cff0 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20   UTF-8 and then 
2d000 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
2d010 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20  er of bytes..** 
2d020 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2d030 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75  s a numeric valu
2d040 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  e then sqlite3_c
2d050 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73  olumn_bytes() us
2d060 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  es.** [sqlite3_s
2d070 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f  nprintf()] to co
2d080 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65  nvert that value
2d090 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69   to a UTF-8 stri
2d0a0 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a  ng and returns.*
2d0b0 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
2d0c0 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74  bytes in that st
2d0d0 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
2d0e0 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c   result is NULL,
2d0f0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
2d100 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74  lumn_bytes() ret
2d110 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  urns zero..**.**
2d120 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
2d130 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46  is a BLOB or UTF
2d140 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20  -16 string then 
2d150 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  the sqlite3_colu
2d160 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20  mn_bytes16().** 
2d170 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
2d180 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2d190 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42  tes in that BLOB
2d1a0 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e   or string..** ^
2d1b0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2d1c0 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c   a UTF-8 string,
2d1d0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
2d1e0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63  lumn_bytes16() c
2d1f0 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73  onverts.** the s
2d200 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20  tring to UTF-16 
2d210 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73  and then returns
2d220 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2d230 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ytes..** ^If the
2d240 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d   result is a num
2d250 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20  eric value then 
2d260 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2d270 79 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a  ytes16() uses.**
2d280 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
2d290 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74  tf()] to convert
2d2a0 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61   that value to a
2d2b0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61   UTF-16 string a
2d2c0 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68  nd returns.** th
2d2d0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2d2e0 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67  s in that string
2d2f0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
2d300 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ult is NULL, the
2d310 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
2d320 5f 62 79 74 65 73 31 36 28 29 20 72 65 74 75 72  _bytes16() retur
2d330 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e  ns zero..**.** ^
2d340 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  The values retur
2d350 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
2d360 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20  column_bytes()] 
2d370 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  and .** [sqlite3
2d380 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2d390 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64  )] do not includ
2d3a0 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69  e the zero termi
2d3b0 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e  nators at the en
2d3c0 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69  d.** of the stri
2d3d0 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74  ng.  ^For clarit
2d3e0 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72 65  y: the values re
2d3f0 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
2d400 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2d410 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  es()] and [sqlit
2d420 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2d430 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d  6()] are the num
2d440 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20  ber of.** bytes 
2d450 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e  in the string, n
2d460 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ot the number of
2d470 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a   characters..**.
2d480 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75  ** ^Strings retu
2d490 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
2d4a0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e  column_text() an
2d4b0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
2d4c0 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76  _text16(),.** ev
2d4d0 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73  en empty strings
2d4e0 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72  , are always zer
2d4f0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e  o-terminated.  ^
2d500 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61  The return.** va
2d510 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
2d520 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66  _column_blob() f
2d530 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  or a zero-length
2d540 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20   BLOB is a NULL 
2d550 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
2d560 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72  The object retur
2d570 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
2d580 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
2d590 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74  is an.** [unprot
2d5a0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2d5b0 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e  lue] object.  An
2d5c0 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
2d5d0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2d5e0 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65  t.** may only be
2d5f0 20 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c 69   used with [sqli
2d600 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29  te3_bind_value()
2d610 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
2d620 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a  esult_value()]..
2d630 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f  ** If the [unpro
2d640 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2d650 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74  alue] object ret
2d660 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
2d670 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
2d680 65 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20  e()] is used in 
2d690 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69  any other way, i
2d6a0 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a  ncluding calls.*
2d6b0 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69  * to routines li
2d6c0 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ke [sqlite3_valu
2d6d0 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74  e_int()], [sqlit
2d6e0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
2d6f0 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ,.** or [sqlite3
2d700 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c  _value_bytes()],
2d710 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
2d720 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
2d730 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
2d740 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f  tines attempt to
2d750 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c   convert the val
2d760 75 65 20 77 68 65 72 65 20 61 70 70 72 6f 70 72  ue where appropr
2d770 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65  iate.  ^For.** e
2d780 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69  xample, if the i
2d790 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e  nternal represen
2d7a0 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20  tation is FLOAT 
2d7b0 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c  and a text resul
2d7c0 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65  t.** is requeste
2d7d0 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  d, [sqlite3_snpr
2d7e0 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20  intf()] is used 
2d7f0 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65  internally to pe
2d800 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e  rform the.** con
2d810 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69  version automati
2d820 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f  cally.  ^(The fo
2d830 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65  llowing table de
2d840 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72  tails the conver
2d850 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72  sions.** that ar
2d860 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a  e applied:.**.**
2d870 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a   <blockquote>.**
2d880 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22   <table border="
2d890 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20  1">.** <tr><th> 
2d8a0 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65  Internal<br>Type
2d8b0 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c   <th> Requested<
2d8c0 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f  br>Type <th>  Co
2d8d0 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c  nversion.**.** <
2d8e0 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
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 52 65 73 75 6c 74 20 69 73 20 30  <td> Result is 0
2d910 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
2d920 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  LL    <td>  FLOA
2d930 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  T    <td> Result
2d940 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c   is 0.0.** <tr><
2d950 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
2d960 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
2d970 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c   Result is a NUL
2d980 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72  L pointer.** <tr
2d990 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
2d9a0 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
2d9b0 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e  d> Result is a N
2d9c0 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c  ULL pointer.** <
2d9d0 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
2d9e0 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
2d9f0 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f  <td> Convert fro
2da00 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f  m integer to flo
2da10 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  at.** <tr><td> I
2da20 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54  NTEGER  <td>   T
2da30 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49  EXT    <td> ASCI
2da40 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  I rendering of t
2da50 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74  he integer.** <t
2da60 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
2da70 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
2da80 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45  td> Same as INTE
2da90 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72  GER->TEXT.** <tr
2daa0 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
2dab0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
2dac0 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54  d> [CAST] to INT
2dad0 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  EGER.** <tr><td>
2dae0 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20    FLOAT   <td>  
2daf0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53   TEXT    <td> AS
2db00 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  CII rendering of
2db10 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74   the float.** <t
2db20 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
2db30 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
2db40 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 42 4c  td> [CAST] to BL
2db50 4f 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  OB.** <tr><td>  
2db60 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54  TEXT    <td> INT
2db70 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53  EGER   <td> [CAS
2db80 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a  T] to INTEGER.**
2db90 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
2dba0 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
2dbb0 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
2dbc0 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64   REAL.** <tr><td
2dbd0 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
2dbe0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e    BLOB    <td> N
2dbf0 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e  o change.** <tr>
2dc00 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
2dc10 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
2dc20 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45  > [CAST] to INTE
2dc30 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  GER.** <tr><td> 
2dc40 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46   BLOB    <td>  F
2dc50 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41  LOAT    <td> [CA
2dc60 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c  ST] to REAL.** <
2dc70 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
2dc80 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
2dc90 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20  <td> Add a zero 
2dca0 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65  terminator if ne
2dcb0 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  eded.** </table>
2dcc0 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  .** </blockquote
2dcd0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61  >)^.**.** The ta
2dce0 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20  ble above makes 
2dcf0 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61  reference to sta
2dd00 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 20  ndard C library 
2dd10 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29  functions atoi()
2dd20 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20  .** and atof(). 
2dd30 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74   SQLite does not
2dd40 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73   really use thes
2dd50 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74  e functions.  It
2dd60 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20   has its.** own 
2dd70 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72  equivalent inter
2dd80 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54  nal routines.  T
2dd90 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74  he atoi() and at
2dda0 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a  of() names are.*
2ddb0 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20 74 61  * used in the ta
2ddc0 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79 20  ble for brevity 
2ddd0 61 6e 64 20 62 65 63 61 75 73 65 20 74 68 65 79  and because they
2dde0 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f   are familiar to
2ddf0 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72   most.** C progr
2de00 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  ammers..**.** No
2de10 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70  te that when typ
2de20 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63  e conversions oc
2de30 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65  cur, pointers re
2de40 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a  turned by prior.
2de50 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ** calls to sqli
2de60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
2de70 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ), sqlite3_colum
2de80 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72  n_text(), and/or
2de90 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
2dea0 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20  mn_text16() may 
2deb0 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a  be invalidated..
2dec0 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69  ** Type conversi
2ded0 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20  ons and pointer 
2dee0 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69  invalidations mi
2def0 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20  ght occur.** in 
2df00 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61  the following ca
2df10 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ses:.**.** <ul>.
2df20 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
2df30 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61  ial content is a
2df40 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65   BLOB and sqlite
2df50 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
2df60 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
2df70 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2df80 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41  () is called.  A
2df90 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72   zero-terminator
2dfa0 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e   might.**      n
2dfb0 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 20  eed to be added 
2dfc0 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f  to the string.</
2dfd0 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  li>.** <li> The 
2dfe0 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
2dff0 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e  is UTF-8 text an
2e000 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
2e010 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a  _bytes16() or.**
2e020 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
2e030 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73  lumn_text16() is
2e040 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f   called.  The co
2e050 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f  ntent must be co
2e060 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20  nverted.**      
2e070 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a  to UTF-16.</li>.
2e080 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
2e090 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55  ial content is U
2e0a0 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73  TF-16 text and s
2e0b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2e0c0 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  tes() or.**     
2e0d0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2e0e0 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64  text() is called
2e0f0 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d  .  The content m
2e100 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
2e110 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d  .**      to UTF-
2e120 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e  8.</li>.** </ul>
2e130 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69  .**.** ^Conversi
2e140 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d  ons between UTF-
2e150 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c  16be and UTF-16l
2e160 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e  e are always don
2e170 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64  e in place and d
2e180 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64  o.** not invalid
2e190 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e  ate a prior poin
2e1a0 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63  ter, though of c
2e1b0 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e  ourse the conten
2e1c0 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a  t of the buffer.
2e1d0 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f  ** that the prio
2e1e0 72 20 70 6f 69 6e 74 65 72 20 72 65 66 65 72 65  r pointer refere
2e1f0 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 65 20 62  nces will have b
2e200 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f  een modified.  O
2e210 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66  ther kinds.** of
2e220 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20   conversion are 
2e230 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68  done in place wh
2e240 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c  en it is possibl
2e250 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73  e, but sometimes
2e260 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74   they.** are not
2e270 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e   possible and in
2e280 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69   those cases pri
2e290 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20  or pointers are 
2e2a0 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a  invalidated..**.
2e2b0 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 61 6e  ** The safest an
2e2c0 64 20 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d  d easiest to rem
2e2d0 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20  ember policy is 
2e2e0 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20  to invoke these 
2e2f0 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f  routines.** in o
2e300 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
2e310 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20  ing ways:.**.** 
2e320 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  <ul>.**  <li>sql
2e330 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2e340 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
2e350 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2e360 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c  tes()</li>.**  <
2e370 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
2e380 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65  n_blob() followe
2e390 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
2e3a0 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e  umn_bytes()</li>
2e3b0 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
2e3c0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2e3d0 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
2e3e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2e3f0 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  s16()</li>.** </
2e400 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68  ul>.**.** In oth
2e410 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68  er words, you sh
2e420 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65  ould call sqlite
2e430 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
2e440 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
2e450 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71  mn_blob(), or sq
2e460 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2e470 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66  t16() first to f
2e480 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a  orce the result.
2e490 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69  ** into the desi
2e4a0 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e  red format, then
2e4b0 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
2e4c0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
2e4d0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
2e4e0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f  umn_bytes16() to
2e4f0 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f   find the size o
2e500 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44  f the result.  D
2e510 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a  o not mix calls.
2e520 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ** to sqlite3_co
2e530 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73  lumn_text() or s
2e540 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2e550 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20  ob() with calls 
2e560 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  to.** sqlite3_co
2e570 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20  lumn_bytes16(), 
2e580 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63  and do not mix c
2e590 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
2e5a0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a  column_text16().
2e5b0 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  ** with calls to
2e5c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2e5d0 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  bytes()..**.** ^
2e5e0 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74  The pointers ret
2e5f0 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20  urned are valid 
2e600 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e  until a type con
2e610 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61  version occurs a
2e620 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61  s.** described a
2e630 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b  bove, or until [
2e640 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2e650 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
2e660 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  t()] or.** [sqli
2e670 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2e680 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65  is called.  ^The
2e690 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73   memory space us
2e6a0 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e  ed to hold strin
2e6b0 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20  gs.** and BLOBs 
2e6c0 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74  is freed automat
2e6d0 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e  ically.  Do <b>n
2e6e0 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20  ot</b> pass the 
2e6f0 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
2e700 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
2e710 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
2e720 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ], [sqlite3_colu
2e730 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e  mn_text()], etc.
2e740 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65   into.** [sqlite
2e750 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  3_free()]..**.**
2e760 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61   ^(If a memory a
2e770 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20  llocation error 
2e780 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68  occurs during th
2e790 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  e evaluation of 
2e7a0 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20  any.** of these 
2e7b0 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61  routines, a defa
2e7c0 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65 74  ult value is ret
2e7d0 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61  urned.  The defa
2e7e0 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20  ult value.** is 
2e7f0 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 65 67  either the integ
2e800 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69  er 0, the floati
2e810 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20  ng point number 
2e820 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a  0.0, or a NULL.*
2e830 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73  * pointer.  Subs
2e840 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
2e850 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
2e860 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a  ()] will return.
2e870 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ** [SQLITE_NOMEM
2e880 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f  ].)^.*/.const vo
2e890 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
2e8a0 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  mn_blob(sqlite3_
2e8b0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2e8c0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
2e8d0 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74  lumn_bytes(sqlit
2e8e0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2e8f0 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
2e900 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2e910 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2e920 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65  nt iCol);.double
2e930 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2e940 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73  double(sqlite3_s
2e950 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2e960 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
2e970 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  umn_int(sqlite3_
2e980 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2e990 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
2e9a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
2e9b0 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  nt64(sqlite3_stm
2e9c0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63  t*, int iCol);.c
2e9d0 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68  onst unsigned ch
2e9e0 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
2e9f0 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  mn_text(sqlite3_
2ea00 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2ea10 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
2ea20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2ea30 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t16(sqlite3_stmt
2ea40 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
2ea50 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
2ea60 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74  _type(sqlite3_st
2ea70 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2ea80 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73  sqlite3_value *s
2ea90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
2eaa0 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lue(sqlite3_stmt
2eab0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f  *, int iCol);../
2eac0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2ead0 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65  estroy A Prepare
2eae0 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
2eaf0 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ct.**.** ^The sq
2eb00 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2eb10 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
2eb20 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20  led to delete a 
2eb30 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2eb40 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ent]..** ^If the
2eb50 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61   most recent eva
2eb60 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73  luation of the s
2eb70 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74  tatement encount
2eb80 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a  ered no errors.*
2eb90 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74 61 74  * or if the stat
2eba0 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62  ement is never b
2ebb0 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74  een evaluated, t
2ebc0 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  hen sqlite3_fina
2ebd0 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a  lize() returns.*
2ebe0 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49  * SQLITE_OK.  ^I
2ebf0 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
2ec00 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  t evaluation of 
2ec10 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c  statement S fail
2ec20 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  ed, then.** sqli
2ec30 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20  te3_finalize(S) 
2ec40 72 65 74 75 72 6e 73 20 74 68 65 20 61 70 70 72  returns the appr
2ec50 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63  opriate [error c
2ec60 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65  ode] or.** [exte
2ec70 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d  nded error code]
2ec80 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2ec90 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
2eca0 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
2ecb0 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f  called at any po
2ecc0 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68  int during.** th
2ecd0 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20  e life cycle of 
2ece0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2ecf0 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72  ent] S:.** befor
2ed00 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73  e statement S is
2ed10 20 65 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c   ever evaluated,
2ed20 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72   after.** one or
2ed30 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b   more calls to [
2ed40 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2ed50 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63  , or after any c
2ed60 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  all.** to [sqlit
2ed70 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72  e3_step()] regar
2ed80 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
2ed90 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74   or not the stat
2eda0 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d  ement has.** com
2edb0 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e  pleted execution
2edc0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e  ..**.** ^Invokin
2edd0 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  g sqlite3_finali
2ede0 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70  ze() on a NULL p
2edf0 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d  ointer is a harm
2ee00 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a  less no-op..**.*
2ee10 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
2ee20 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20  n must finalize 
2ee30 65 76 65 72 79 20 5b 70 72 65 70 61 72 65 64 20  every [prepared 
2ee40 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72  statement] in or
2ee50 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20  der to avoid.** 
2ee60 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20  resource leaks. 
2ee70 20 49 74 20 69 73 20 61 20 67 72 69 65 76 6f 75   It is a grievou
2ee80 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20  s error for the 
2ee90 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74  application to t
2eea0 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70  ry to use.** a p
2eeb0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2eec0 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  t after it has b
2eed0 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20  een finalized.  
2eee0 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72 65  Any use of a pre
2eef0 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
2ef00 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20  nt after it has 
2ef10 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63  been finalized c
2ef20 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64  an result in und
2ef30 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e  efined and.** un
2ef40 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69  desirable behavi
2ef50 6f 72 20 73 75 63 68 20 61 73 20 73 65 67 66 61  or such as segfa
2ef60 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f  ults and heap co
2ef70 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74  rruption..*/.int
2ef80 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
2ef90 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  e(sqlite3_stmt *
2efa0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
2efb0 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41  API3REF: Reset A
2efc0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
2efd0 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ent Object.**.**
2efe0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
2eff0 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  et() function is
2f000 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74   called to reset
2f010 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2f020 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63  tement].** objec
2f030 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  t back to its in
2f040 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61  itial state, rea
2f050 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63  dy to be re-exec
2f060 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51  uted..** ^Any SQ
2f070 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69  L statement vari
2f080 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76  ables that had v
2f090 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74  alues bound to t
2f0a0 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65  hem using.** the
2f0b0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2f0c0 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69  lob | sqlite3_bi
2f0d0 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61  nd_*() API] reta
2f0e0 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e  in their values.
2f0f0 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33  .** Use [sqlite3
2f100 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28  _clear_bindings(
2f110 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  )] to reset the 
2f120 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20  bindings..**.** 
2f130 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  ^The [sqlite3_re
2f140 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63  set(S)] interfac
2f150 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 72  e resets the [pr
2f160 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2f170 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74  ] S.** back to t
2f180 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
2f190 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a  its program..**.
2f1a0 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
2f1b0 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
2f1c0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
2f1d0 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65   for the.** [pre
2f1e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2f1f0 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c   S returned [SQL
2f200 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c  ITE_ROW] or [SQL
2f210 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72  ITE_DONE],.** or
2f220 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   if [sqlite3_ste
2f230 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20  p(S)] has never 
2f240 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c  before been call
2f250 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e  ed on S,.** then
2f260 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2f270 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  S)] returns [SQL
2f280 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  ITE_OK]..**.** ^
2f290 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
2f2a0 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
2f2b0 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72  te3_step(S)] for
2f2c0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
2f2d0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
2f2e0 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f  ndicated an erro
2f2f0 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69  r, then.** [sqli
2f300 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65  te3_reset(S)] re
2f310 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72  turns an appropr
2f320 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65  iate [error code
2f330 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73  ]..**.** ^The [s
2f340 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
2f350 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20   interface does 
2f360 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76  not change the v
2f370 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20  alues.** of any 
2f380 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2f390 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20  ob|bindings] on 
2f3a0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2f3b0 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69  atement] S..*/.i
2f3c0 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74  nt sqlite3_reset
2f3d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
2f3e0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
2f3f0 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f  PI3REF: Create O
2f400 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46  r Redefine SQL F
2f410 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57  unctions.** KEYW
2f420 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20  ORDS: {function 
2f430 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  creation routine
2f440 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  s}.** KEYWORDS: 
2f450 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  {application-def
2f460 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
2f470 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  n}.** KEYWORDS: 
2f480 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  {application-def
2f490 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
2f4a0 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ns}.**.** ^These
2f4b0 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c   functions (coll
2f4c0 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61  ectively known a
2f4d0 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  s "function crea
2f4e0 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a  tion routines").
2f4f0 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61  ** are used to a
2f500 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  dd SQL functions
2f510 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f   or aggregates o
2f520 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68  r to redefine th
2f530 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66  e behavior.** of
2f540 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75   existing SQL fu
2f550 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65  nctions or aggre
2f560 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79  gates.  The only
2f570 20 64 69 66 66 65 72 65 6e 63 65 73 20 62 65 74   differences bet
2f580 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f  ween.** these ro
2f590 75 74 69 6e 65 73 20 61 72 65 20 74 68 65 20 74  utines are the t
2f5a0 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70  ext encoding exp
2f5b0 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65  ected for.** the
2f5c0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
2f5d0 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  r (the name of t
2f5e0 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e  he function bein
2f5f0 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e  g created).** an
2f600 64 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f  d the presence o
2f610 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64  r absence of a d
2f620 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61  estructor callba
2f630 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70  ck for.** the ap
2f640 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
2f650 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
2f660 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
2f670 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62  er is the [datab
2f680 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2f690 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c  to which the SQL
2f6a0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
2f6b0 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49  to be added.  ^I
2f6c0 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
2f6d0 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20   uses more than 
2f6e0 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  one database.** 
2f6f0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20  connection then 
2f700 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2f710 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
2f720 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a  s must be added.
2f730 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61 62  ** to each datab
2f740 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73  ase connection s
2f750 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  eparately..**.**
2f760 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
2f770 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61  ameter is the na
2f780 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75  me of the SQL fu
2f790 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65  nction to be cre
2f7a0 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66  ated or.** redef
2f7b0 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67  ined.  ^The leng
2f7c0 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69  th of the name i
2f7d0 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35  s limited to 255
2f7e0 20 62 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d   bytes in a UTF-
2f7f0 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74  8.** representat
2f800 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f  ion, exclusive o
2f810 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69  f the zero-termi
2f820 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68  nator.  ^Note th
2f830 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c  at the name.** l
2f840 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69  ength limit is i
2f850 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e  n UTF-8 bytes, n
2f860 6f 74 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f  ot characters no
2f870 72 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20  r UTF-16 bytes. 
2f880 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70   .** ^Any attemp
2f890 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75  t to create a fu
2f8a0 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f  nction with a lo
2f8b0 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c  nger name.** wil
2f8c0 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c  l result in [SQL
2f8d0 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e  ITE_MISUSE] bein
2f8e0 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  g returned..**.*
2f8f0 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72  * ^The third par
2f900 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a  ameter (nArg).**
2f910 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
2f920 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  f arguments that
2f930 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2f940 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
2f950 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69  e takes. ^If thi
2f960 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d  s parameter is -
2f970 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20  1, then the SQL 
2f980 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
2f990 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b  ggregate may tak
2f9a0 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20  e any number of 
2f9b0 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65  arguments betwee
2f9c0 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69  n 0 and the limi
2f9d0 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c  t.** set by [sql
2f9e0 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c  ite3_limit]([SQL
2f9f0 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
2fa00 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68  ON_ARG]).  If th
2fa10 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d  e third.** param
2fa20 65 74 65 72 20 69 73 20 6c 65 73 73 20 74 68 61  eter is less tha
2fa30 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20  n -1 or greater 
2fa40 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68  than 127 then th
2fa50 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a  e behavior is.**
2fa60 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
2fa70 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61  * ^The fourth pa
2fa80 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65  rameter, eTextRe
2fa90 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61  p, specifies wha
2faa0 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  t.** [SQLITE_UTF
2fab0 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  8 | text encodin
2fac0 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63  g] this SQL func
2fad0 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72  tion prefers for
2fae0 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65  .** its paramete
2faf0 72 73 2e 20 20 45 76 65 72 79 20 53 51 4c 20 66  rs.  Every SQL f
2fb00 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
2fb10 74 61 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 61  tation must be a
2fb20 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77  ble to work.** w
2fb30 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d 31  ith UTF-8, UTF-1
2fb40 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62 65  6le, or UTF-16be
2fb50 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c  .  But some impl
2fb60 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20  ementations may 
2fb70 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63  be.** more effic
2fb80 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65 6e  ient with one en
2fb90 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74  coding than anot
2fba0 68 65 72 2e 20 20 5e 41 6e 20 61 70 70 6c 69 63  her.  ^An applic
2fbb0 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20 69 6e 76  ation may.** inv
2fbc0 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  oke sqlite3_crea
2fbd0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72  te_function() or
2fbe0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2fbf0 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c  function16() mul
2fc00 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77  tiple.** times w
2fc10 69 74 68 20 74 68 65 20 73 61 6d 65 20 66 75 6e  ith the same fun
2fc20 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20 64  ction but with d
2fc30 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73 20  ifferent values 
2fc40 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20  of eTextRep..** 
2fc50 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69  ^When multiple i
2fc60 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
2fc70 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  f the same funct
2fc80 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c  ion are availabl
2fc90 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c  e, SQLite.** wil
2fca0 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74  l pick the one t
2fcb0 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65  hat involves the
2fcc0 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66   least amount of
2fcd0 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e   data conversion
2fce0 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73  ..** If there is
2fcf0 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 69   only a single i
2fd00 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68  mplementation wh
2fd10 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61 72  ich does not car
2fd20 65 20 77 68 61 74 20 74 65 78 74 0a 2a 2a 20 65  e what text.** e
2fd30 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 2c  ncoding is used,
2fd40 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68   then the fourth
2fd50 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
2fd60 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d   be [SQLITE_ANY]
2fd70 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69  ..**.** ^(The fi
2fd80 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  fth parameter is
2fd90 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f   an arbitrary po
2fda0 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c  inter.  The impl
2fdb0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
2fdc0 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61  e.** function ca
2fdd0 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f  n gain access to
2fde0 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73   this pointer us
2fdf0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65  ing [sqlite3_use
2fe00 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a  r_data()].)^.**.
2fe10 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20 73  ** ^The sixth, s
2fe20 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68 74  eventh and eight
2fe30 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46  h parameters, xF
2fe40 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78  unc, xStep and x
2fe50 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f  Final, are.** po
2fe60 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67  inters to C-lang
2fe70 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74  uage functions t
2fe80 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  hat implement th
2fe90 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
2fea0 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20  r.** aggregate. 
2feb0 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75  ^A scalar SQL fu
2fec0 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
2fed0 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  an implementatio
2fee0 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a  n of the xFunc.*
2fef0 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b  * callback only;
2ff00 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d   NULL pointers m
2ff10 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73  ust be passed as
2ff20 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20 78   the xStep and x
2ff30 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74  Final.** paramet
2ff40 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 61  ers. ^An aggrega
2ff50 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  te SQL function 
2ff60 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c  requires an impl
2ff70 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53  ementation of xS
2ff80 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61  tep.** and xFina
2ff90 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74  l and NULL point
2ffa0 65 72 20 6d 75 73 74 20 62 65 20 70 61 73 73 65  er must be passe
2ffb0 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f  d for xFunc. ^To
2ffc0 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74   delete an exist
2ffd0 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  ing.** SQL funct
2ffe0 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
2fff0 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e  , pass NULL poin
30000 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 72  ters for all thr
30010 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63  ee function.** c
30020 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20  allbacks..**.** 
30030 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20 70  ^(If the ninth p
30040 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
30050 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
30060 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20  ion_v2() is not 
30070 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74  NULL,.** then it
30080 20 69 73 20 64 65 73 74 72 75 63 74 6f 72 20 66   is destructor f
30090 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  or the applicati
300a0 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e  on data pointer.
300b0 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75 63   .** The destruc
300c0 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  tor is invoked w
300d0 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  hen the function
300e0 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69 74   is deleted, eit
300f0 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20  her by being.** 
30100 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 68  overloaded or wh
30110 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
30120 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65  connection close
30130 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73  s.)^.** ^The des
30140 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f 20  tructor is also 
30150 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63  invoked if the c
30160 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  all to.** sqlite
30170 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
30180 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a  n_v2() fails..**
30190 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74 72   ^When the destr
301a0 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f  uctor callback o
301b0 66 20 74 68 65 20 74 65 6e 74 68 20 70 61 72 61  f the tenth para
301c0 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 64  meter is invoked
301d0 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 65  , it.** is passe
301e0 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  d a single argum
301f0 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 63  ent which is a c
30200 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c 69  opy of the appli
30210 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20  cation data .** 
30220 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77 61  pointer which wa
30230 73 20 74 68 65 20 66 69 66 74 68 20 70 61 72 61  s the fifth para
30240 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
30250 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
30260 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74  _v2()..**.** ^It
30270 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f   is permitted to
30280 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70   register multip
30290 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
302a0 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a  ns of the same.*
302b0 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68  * functions with
302c0 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62   the same name b
302d0 75 74 20 77 69 74 68 20 65 69 74 68 65 72 20 64  ut with either d
302e0 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73  iffering numbers
302f0 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73   of.** arguments
30300 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 72   or differing pr
30310 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
30320 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65  odings.  ^SQLite
30330 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65   will use.** the
30340 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
30350 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c  that most closel
30360 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61  y matches the wa
30370 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a  y in which the.*
30380 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  * SQL function i
30390 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63  s used.  ^A func
303a0 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
303b0 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e  ion with a non-n
303c0 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20  egative.** nArg 
303d0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62  parameter is a b
303e0 65 74 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e  etter match than
303f0 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c   a function impl
30400 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a  ementation with.
30410 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41  ** a negative nA
30420 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e  rg.  ^A function
30430 20 77 68 65 72 65 20 74 68 65 20 70 72 65 66 65   where the prefe
30440 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
30450 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68  ng.** matches th
30460 65 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64  e database encod
30470 69 6e 67 20 69 73 20 61 20 62 65 74 74 65 72 0a  ing is a better.
30480 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  ** match than a 
30490 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
304a0 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64  he encoding is d
304b0 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e  ifferent.  .** ^
304c0 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  A function where
304d0 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69   the encoding di
304e0 66 66 65 72 65 6e 63 65 20 69 73 20 62 65 74 77  fference is betw
304f0 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20  een UTF16le and 
30500 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20  UTF16be.** is a 
30510 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61  closer match tha
30520 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  n a function whe
30530 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
30540 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a  difference is.**
30550 20 62 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e   between UTF8 an
30560 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e  d UTF16..**.** ^
30570 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f  Built-in functio
30580 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f  ns may be overlo
30590 61 64 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c  aded by new appl
305a0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
305b0 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  functions..**.**
305c0 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e   ^An application
305d0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
305e0 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74  n is permitted t
305f0 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20  o call other.** 
30600 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
30610 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63  s.  However, suc
30620 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74  h calls must not
30630 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61  .** close the da
30640 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
30650 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f  n nor finalize o
30660 72 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70  r reset the prep
30670 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  ared.** statemen
30680 74 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 66  t in which the f
30690 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
306a0 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ng..*/.int sqlit
306b0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
306c0 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  on(.  sqlite3 *d
306d0 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  b,.  const char 
306e0 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
306f0 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
30700 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
30710 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64  id *pApp,.  void
30720 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65   (*xFunc)(sqlite
30730 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
30740 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
30750 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
30760 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
30770 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
30780 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
30790 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33  *xFinal)(sqlite3
307a0 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e  _context*).);.in
307b0 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
307c0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73  _function16(.  s
307d0 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
307e0 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74  nst void *zFunct
307f0 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
30800 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
30810 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
30820 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
30830 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
30840 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
30850 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
30860 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
30870 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
30880 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
30890 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
308a0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
308b0 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  t*).);.int sqlit
308c0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
308d0 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  on_v2(.  sqlite3
308e0 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68   *db,.  const ch
308f0 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  ar *zFunctionNam
30900 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
30910 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
30920 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76   void *pApp,.  v
30930 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c  oid (*xFunc)(sql
30940 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
30950 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
30960 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74  *),.  void (*xSt
30970 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ep)(sqlite3_cont
30980 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
30990 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
309a0 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69  d (*xFinal)(sqli
309b0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20  te3_context*),. 
309c0 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29   void(*xDestroy)
309d0 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a  (void*).);../*.*
309e0 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74  * CAPI3REF: Text
309f0 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a   Encodings.**.**
30a00 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20   These constant 
30a10 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63  define integer c
30a20 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73  odes that repres
30a30 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a  ent the various.
30a40 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ** text encoding
30a50 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53  s supported by S
30a60 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  QLite..*/.#defin
30a70 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20  e SQLITE_UTF8   
30a80 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
30a90 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45  e SQLITE_UTF16LE
30aa0 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
30ab0 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45  e SQLITE_UTF16BE
30ac0 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
30ad0 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20  e SQLITE_UTF16  
30ae0 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20          4    /* 
30af0 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  Use native byte 
30b00 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65  order */.#define
30b10 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20   SQLITE_ANY     
30b20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73         5    /* s
30b30 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
30b40 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23  nction only */.#
30b50 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
30b60 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20  F16_ALIGNED  8  
30b70 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65    /* sqlite3_cre
30b80 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e  ate_collation on
30b90 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ly */../*.** CAP
30ba0 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65  I3REF: Deprecate
30bb0 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44  d Functions.** D
30bc0 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20  EPRECATED.**.** 
30bd0 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
30be0 61 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d  are [deprecated]
30bf0 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d  .  In order to m
30c00 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77  aintain.** backw
30c10 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
30c20 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f  ty with older co
30c30 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69  de, these functi
30c40 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a  ons continue .**
30c50 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
30c60 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20  .  However, new 
30c70 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  applications sho
30c80 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65  uld avoid.** the
30c90 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75   use of these fu
30ca0 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c  nctions.  To hel
30cb0 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70  p encourage peop
30cc0 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75  le to avoid.** u
30cd0 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74  sing these funct
30ce0 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74  ions, we are not
30cf0 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79   going to tell y
30d00 6f 75 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e  ou what they do.
30d10 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
30d20 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54  TE_OMIT_DEPRECAT
30d30 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  ED.SQLITE_DEPREC
30d40 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
30d50 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74  _aggregate_count
30d60 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
30d70 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  *);.SQLITE_DEPRE
30d80 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
30d90 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65  3_expired(sqlite
30da0 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45  3_stmt*);.SQLITE
30db0 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
30dc0 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72  sqlite3_transfer
30dd0 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65  _bindings(sqlite
30de0 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33  3_stmt*, sqlite3
30df0 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  _stmt*);.SQLITE_
30e00 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
30e10 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65  qlite3_global_re
30e20 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c  cover(void);.SQL
30e30 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76  ITE_DEPRECATED v
30e40 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65  oid sqlite3_thre
30e50 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29  ad_cleanup(void)
30e60 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
30e70 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
30e80 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69  memory_alarm(voi
30e90 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
30ea0 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 0a 20  e3_int64,int),. 
30eb0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
30ec0 20 20 20 20 20 76 6f 69 64 2a 2c 73 71 6c 69 74       void*,sqlit
30ed0 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69  e3_int64);.#endi
30ee0 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
30ef0 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c  F: Obtaining SQL
30f00 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65   Function Parame
30f10 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a  ter Values.**.**
30f20 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20   The C-language 
30f30 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
30f40 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  f SQL functions 
30f50 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 20 75  and aggregates u
30f60 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20  ses.** this set 
30f70 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75  of interface rou
30f80 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20  tines to access 
30f90 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 76 61  the parameter va
30fa0 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66  lues on.** the f
30fb0 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65  unction or aggre
30fc0 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  gate..**.** The 
30fd0 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61  xFunc (for scala
30fe0 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20  r functions) or 
30ff0 78 53 74 65 70 20 28 66 6f 72 20 61 67 67 72 65  xStep (for aggre
31000 67 61 74 65 73 29 20 70 61 72 61 6d 65 74 65 72  gates) parameter
31010 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33  s.** to [sqlite3
31020 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
31030 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
31040 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
31050 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20  16()].** define 
31060 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69  callbacks that i
31070 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c  mplement the SQL
31080 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
31090 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68  ggregates..** Th
310a0 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
310b0 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63  to these callbac
310c0 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  ks is an array o
310d0 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a  f pointers to.**
310e0 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
310f0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
31100 74 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e  ts.  There is on
31110 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
31120 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20  ] object for.** 
31130 65 61 63 68 20 70 61 72 61 6d 65 74 65 72 20 74  each parameter t
31140 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  o the SQL functi
31150 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69  on.  These routi
31160 6e 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a  nes are used to.
31170 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75 65  ** extract value
31180 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69  s from the [sqli
31190 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
311a0 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ts..**.** These 
311b0 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e  routines work on
311c0 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74  ly with [protect
311d0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
311e0 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e  ] objects..** An
311f0 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65  y attempt to use
31200 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
31210 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74  on an [unprotect
31220 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
31230 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75  ].** object resu
31240 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  lts in undefined
31250 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a   behavior..**.**
31260 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
31270 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20   work just like 
31280 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
31290 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73  g [column access
312a0 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65   functions].** e
312b0 78 63 65 70 74 20 74 68 61 74 20 20 74 68 65 73  xcept that  thes
312c0 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20  e routines take 
312d0 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63  a single [protec
312e0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
312f0 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69  e] object.** poi
31300 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20  nter instead of 
31310 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  a [sqlite3_stmt*
31320 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e  ] pointer and an
31330 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20   integer column 
31340 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  number..**.** ^T
31350 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
31360 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65 72 66  _text16() interf
31370 61 63 65 20 65 78 74 72 61 63 74 73 20 61 20 55  ace extracts a U
31380 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20  TF-16 string.** 
31390 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
313a0 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20  te-order of the 
313b0 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e  host machine.  ^
313c0 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  The.** sqlite3_v
313d0 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 20  alue_text16be() 
313e0 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  and sqlite3_valu
313f0 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74  e_text16le() int
31400 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61  erfaces.** extra
31410 63 74 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ct UTF-16 string
31420 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20  s as big-endian 
31430 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61  and little-endia
31440 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  n respectively..
31450 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69  **.** ^(The sqli
31460 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69  te3_value_numeri
31470 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66 61  c_type() interfa
31480 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61  ce attempts to a
31490 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20  pply.** numeric 
314a0 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20  affinity to the 
314b0 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61  value.  This mea
314c0 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d  ns that an attem
314d0 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f  pt is.** made to
314e0 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c   convert the val
314f0 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  ue to an integer
31500 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69   or floating poi
31510 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20  nt.  If.** such 
31520 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  a conversion is 
31530 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74  possible without
31540 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61   loss of informa
31550 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a  tion (in other.*
31560 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20  * words, if the 
31570 76 61 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e  value is a strin
31580 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b  g that looks lik
31590 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74  e a number).** t
315a0 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69  hen the conversi
315b0 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e  on is performed.
315c0 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63    Otherwise no c
315d0 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73  onversion occurs
315e0 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ..** The [SQLITE
315f0 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74  _INTEGER | datat
31600 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65  ype] after conve
31610 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65  rsion is returne
31620 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73  d.)^.**.** Pleas
31630 65 20 70 61 79 20 70 61 72 74 69 63 75 6c 61 72  e pay particular
31640 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68   attention to th
31650 65 20 66 61 63 74 20 74 68 61 74 20 74 68 65 20  e fact that the 
31660 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64  pointer returned
31670 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
31680 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c  3_value_blob()],
31690 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
316a0 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b  text()], or.** [
316b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
316c0 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69  xt16()] can be i
316d0 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20 61 20  nvalidated by a 
316e0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20  subsequent call 
316f0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  to.** [sqlite3_v
31700 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b  alue_bytes()], [
31710 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
31720 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74  tes16()], [sqlit
31730 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
31740 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ,.** or [sqlite3
31750 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d  _value_text16()]
31760 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
31770 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63  utines must be c
31780 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
31790 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a  ame thread as.**
317a0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
317b0 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65 64 20  n that supplied 
317c0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
317d0 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e  ue*] parameters.
317e0 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  .*/.const void *
317f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
31800 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ob(sqlite3_value
31810 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
31820 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69  value_bytes(sqli
31830 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
31840 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62   sqlite3_value_b
31850 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76  ytes16(sqlite3_v
31860 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73  alue*);.double s
31870 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75  qlite3_value_dou
31880 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ble(sqlite3_valu
31890 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
318a0 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74  _value_int(sqlit
318b0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69  e3_value*);.sqli
318c0 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
318d0 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71  3_value_int64(sq
318e0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
318f0 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68  onst unsigned ch
31900 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  ar *sqlite3_valu
31910 65 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76  e_text(sqlite3_v
31920 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  alue*);.const vo
31930 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
31940 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  e_text16(sqlite3
31950 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
31960 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
31970 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c  lue_text16le(sql
31980 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
31990 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
319a0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
319b0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
319c0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
319d0 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33  lue_type(sqlite3
319e0 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
319f0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65  lite3_value_nume
31a00 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33  ric_type(sqlite3
31a10 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  _value*);../*.**
31a20 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
31a30 6e 20 41 67 67 72 65 67 61 74 65 20 46 75 6e 63  n Aggregate Func
31a40 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a  tion Context.**.
31a50 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** Implementatio
31a60 6e 73 20 6f 66 20 61 67 67 72 65 67 61 74 65 20  ns of aggregate 
31a70 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73  SQL functions us
31a80 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  e this.** routin
31a90 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65  e to allocate me
31aa0 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72 69 6e 67  mory for storing
31ab0 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a   their state..**
31ac0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74  .** ^The first t
31ad0 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ime the sqlite3_
31ae0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
31af0 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69  t(C,N) routine i
31b00 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72  s called .** for
31b10 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 61 67   a particular ag
31b20 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
31b30 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f  , SQLite.** allo
31b40 63 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72  cates N of memor
31b50 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74 68  y, zeroes out th
31b60 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72  at memory, and r
31b70 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
31b80 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77 20 6d  .** to the new m
31b90 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e  emory. ^On secon
31ba0 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  d and subsequent
31bb0 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c   calls to.** sql
31bc0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
31bd0 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68 65  ontext() for the
31be0 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20   same aggregate 
31bf0 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63  function instanc
31c00 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 62  e,.** the same b
31c10 75 66 66 65 72 20 69 73 20 72 65 74 75 72 6e 65  uffer is returne
31c20 64 2e 20 20 53 71 6c 69 74 65 33 5f 61 67 67 72  d.  Sqlite3_aggr
31c30 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
31c40 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63  is normally.** c
31c50 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20 65  alled once for e
31c60 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ach invocation o
31c70 66 20 74 68 65 20 78 53 74 65 70 20 63 61 6c 6c  f the xStep call
31c80 62 61 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e  back and then on
31c90 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20 77  e.** last time w
31ca0 68 65 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63  hen the xFinal c
31cb0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
31cc0 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72  ed.  ^(When no r
31cd0 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20  ows match.** an 
31ce0 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79 2c  aggregate query,
31cf0 20 74 68 65 20 78 53 74 65 70 28 29 20 63 61 6c   the xStep() cal
31d00 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 61 67 67  lback of the agg
31d10 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a  regate function.
31d20 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
31d30 6e 20 69 73 20 6e 65 76 65 72 20 63 61 6c 6c 65  n is never calle
31d40 64 20 61 6e 64 20 78 46 69 6e 61 6c 28 29 20 69  d and xFinal() i
31d50 73 20 63 61 6c 6c 65 64 20 65 78 61 63 74 6c 79  s called exactly
31d60 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f   once..** In tho
31d70 73 65 20 63 61 73 65 73 2c 20 73 71 6c 69 74 65  se cases, sqlite
31d80 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
31d90 65 78 74 28 29 20 6d 69 67 68 74 20 62 65 20 63  ext() might be c
31da0 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a  alled for the.**
31db0 20 66 69 72 73 74 20 74 69 6d 65 20 66 72 6f 6d   first time from
31dc0 20 77 69 74 68 69 6e 20 78 46 69 6e 61 6c 28 29   within xFinal()
31dd0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .)^.**.** ^The s
31de0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
31df0 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f  _context(C,N) ro
31e00 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
31e10 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 0a 2a 2a  NULL pointer .**
31e20 20 77 68 65 6e 20 66 69 72 73 74 20 63 61 6c 6c   when first call
31e30 65 64 20 69 66 20 4e 20 69 73 20 6c 65 73 73 20  ed if N is less 
31e40 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f  than or equal to
31e50 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20 6d 65   zero or if a me
31e60 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  mory.** allocate
31e70 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a   error occurs..*
31e80 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e  *.** ^(The amoun
31e90 74 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63  t of space alloc
31ea0 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ated by sqlite3_
31eb0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
31ec0 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74  t(C,N) is.** det
31ed0 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e  ermined by the N
31ee0 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69   parameter on fi
31ef0 72 73 74 20 73 75 63 63 65 73 73 66 75 6c 20 63  rst successful c
31f00 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74  all.  Changing t
31f10 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e  he.** value of N
31f20 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63   in subsequent c
31f30 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61  all to sqlite3_a
31f40 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
31f50 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65  () within.** the
31f60 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20   same aggregate 
31f70 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63  function instanc
31f80 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a  e will not resiz
31f90 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  e the memory.** 
31fa0 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 20 20 57  allocation.)^  W
31fb0 69 74 68 69 6e 20 74 68 65 20 78 46 69 6e 61 6c  ithin the xFinal
31fc0 20 63 61 6c 6c 62 61 63 6b 2c 20 69 74 20 69 73   callback, it is
31fd0 20 63 75 73 74 6f 6d 61 72 79 20 74 6f 20 73 65   customary to se
31fe0 74 0a 2a 2a 20 4e 3d 30 20 69 6e 20 63 61 6c 6c  t.** N=0 in call
31ff0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67  s to sqlite3_agg
32000 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
32010 2c 4e 29 20 73 6f 20 74 68 61 74 20 6e 6f 20 0a  ,N) so that no .
32020 2a 2a 20 70 6f 69 6e 74 6c 65 73 73 20 6d 65 6d  ** pointless mem
32030 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  ory allocations 
32040 6f 63 63 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51  occur..**.** ^SQ
32050 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  Lite automatical
32060 6c 79 20 66 72 65 65 73 20 74 68 65 20 6d 65 6d  ly frees the mem
32070 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  ory allocated by
32080 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67   .** sqlite3_agg
32090 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
320a0 20 77 68 65 6e 20 74 68 65 20 61 67 67 72 65 67   when the aggreg
320b0 61 74 65 20 71 75 65 72 79 20 63 6f 6e 63 6c 75  ate query conclu
320c0 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  des..**.** The f
320d0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 6d  irst parameter m
320e0 75 73 74 20 62 65 20 61 20 63 6f 70 79 20 6f 66  ust be a copy of
320f0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
32100 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66  _context | SQL f
32110 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d  unction context]
32120 20 74 68 61 74 20 69 73 20 74 68 65 20 66 69 72   that is the fir
32130 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  st parameter.** 
32140 74 6f 20 74 68 65 20 78 53 74 65 70 20 6f 72 20  to the xStep or 
32150 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20  xFinal callback 
32160 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70  routine that imp
32170 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72  lements the aggr
32180 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  egate.** functio
32190 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  n..**.** This ro
321a0 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61  utine must be ca
321b0 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
321c0 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
321d0 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67  ch.** the aggreg
321e0 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
321f0 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
32200 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67  void *sqlite3_ag
32210 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
32220 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
32230 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a  , int nBytes);..
32240 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
32250 55 73 65 72 20 44 61 74 61 20 46 6f 72 20 46 75  User Data For Fu
32260 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54  nctions.**.** ^T
32270 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  he sqlite3_user_
32280 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
32290 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
322a0 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65  of.** the pointe
322b0 72 20 74 68 61 74 20 77 61 73 20 74 68 65 20 70  r that was the p
322c0 55 73 65 72 44 61 74 61 20 70 61 72 61 6d 65 74  UserData paramet
322d0 65 72 20 28 74 68 65 20 35 74 68 20 70 61 72 61  er (the 5th para
322e0 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65  meter).** of the
322f0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
32300 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20  _function()].** 
32310 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
32320 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
32330 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  ] routines that 
32340 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65  originally.** re
32350 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70  gistered the app
32360 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64  lication defined
32370 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
32380 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75   This routine mu
32390 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
323a0 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
323b0 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68  d in which.** th
323c0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
323d0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69  fined function i
323e0 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f  s running..*/.vo
323f0 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72  id *sqlite3_user
32400 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  _data(sqlite3_co
32410 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ntext*);../*.** 
32420 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61  CAPI3REF: Databa
32430 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f  se Connection Fo
32440 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  r Functions.**.*
32450 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
32460 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
32470 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
32480 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a  urns a copy of.*
32490 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f  * the pointer to
324a0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
324b0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20  onnection] (the 
324c0 31 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a  1st parameter).*
324d0 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
324e0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
324f0 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  n()].** and [sql
32500 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
32510 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e  tion16()] routin
32520 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c  es that original
32530 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64  ly.** registered
32540 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
32550 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f   defined functio
32560 6e 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73  n..*/.sqlite3 *s
32570 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
32580 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33  b_handle(sqlite3
32590 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a  _context*);../*.
325a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e  ** CAPI3REF: Fun
325b0 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20  ction Auxiliary 
325c0 44 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  Data.**.** These
325d0 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62   functions may b
325e0 65 20 75 73 65 64 20 62 79 20 28 6e 6f 6e 2d 61  e used by (non-a
325f0 67 67 72 65 67 61 74 65 29 20 53 51 4c 20 66 75  ggregate) SQL fu
32600 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73  nctions to.** as
32610 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74 61  sociate metadata
32620 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76   with argument v
32630 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73 61  alues. If the sa
32640 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61 73 73  me value is pass
32650 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c  ed to.** multipl
32660 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  e invocations of
32670 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75   the same SQL fu
32680 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75  nction during qu
32690 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75  ery execution, u
326a0 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72  nder.** some cir
326b0 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61  cumstances the a
326c0 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61  ssociated metada
326d0 74 61 20 6d 61 79 20 62 65 20 70 72 65 73 65 72  ta may be preser
326e0 76 65 64 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65  ved.  An example
326f0 0a 2a 2a 20 6f 66 20 77 68 65 72 65 20 74 68 69  .** of where thi
32700 73 20 6d 69 67 68 74 20 62 65 20 75 73 65 66 75  s might be usefu
32710 6c 20 69 73 20 69 6e 20 61 20 72 65 67 75 6c 61  l is in a regula
32720 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74  r-expression mat
32730 63 68 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f  ching.** functio
32740 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20  n. The compiled 
32750 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72  version of the r
32760 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
32770 6e 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20  n can be stored 
32780 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20 61  as.** metadata a
32790 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
327a0 68 65 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e  he pattern strin
327b0 67 2e 20 20 0a 2a 2a 20 54 68 65 6e 20 61 73 20  g.  .** Then as 
327c0 6c 6f 6e 67 20 61 73 20 74 68 65 20 70 61 74 74  long as the patt
327d0 65 72 6e 20 73 74 72 69 6e 67 20 72 65 6d 61 69  ern string remai
327e0 6e 73 20 74 68 65 20 73 61 6d 65 2c 0a 2a 2a 20  ns the same,.** 
327f0 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67  the compiled reg
32800 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20  ular expression 
32810 63 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e  can be reused on
32820 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76   multiple.** inv
32830 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
32840 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  same function..*
32850 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
32860 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_get_auxdata() 
32870 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
32880 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
32890 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61  he metadata.** a
328a0 73 73 6f 63 69 61 74 65 64 20 62 79 20 74 68 65  ssociated by the
328b0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
328c0 64 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20  data() function 
328d0 77 69 74 68 20 74 68 65 20 4e 74 68 20 61 72 67  with the Nth arg
328e0 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74  ument.** value t
328f0 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
32900 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
32910 6f 6e 2e 20 5e 49 66 20 74 68 65 72 65 20 69 73  on. ^If there is
32920 20 6e 6f 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20   no metadata.** 
32930 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
32940 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 67  the function arg
32950 75 6d 65 6e 74 2c 20 74 68 69 73 20 73 71 6c 69  ument, this sqli
32960 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
32970 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72  ) interface.** r
32980 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
32990 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  inter..**.** ^Th
329a0 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
329b0 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 69  xdata(C,N,P,X) i
329c0 6e 74 65 72 66 61 63 65 20 73 61 76 65 73 20 50  nterface saves P
329d0 20 61 73 20 6d 65 74 61 64 61 74 61 20 66 6f 72   as metadata for
329e0 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67   the N-th.** arg
329f0 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70  ument of the app
32a00 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
32a10 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 53 75 62   function.  ^Sub
32a20 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73  sequent.** calls
32a30 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f   to sqlite3_get_
32a40 61 75 78 64 61 74 61 28 43 2c 4e 29 20 72 65 74  auxdata(C,N) ret
32a50 75 72 6e 20 50 20 66 72 6f 6d 20 74 68 65 20 6d  urn P from the m
32a60 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 71  ost recent.** sq
32a70 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
32a80 61 28 43 2c 4e 2c 50 2c 58 29 20 63 61 6c 6c 20  a(C,N,P,X) call 
32a90 69 66 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  if the metadata 
32aa0 69 73 20 73 74 69 6c 6c 20 76 61 6c 69 64 20 6f  is still valid o
32ab0 72 0a 2a 2a 20 4e 55 4c 4c 20 69 66 20 74 68 65  r.** NULL if the
32ac0 20 6d 65 74 61 64 61 74 61 20 68 61 73 20 62 65   metadata has be
32ad0 65 6e 20 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a  en discarded..**
32ae0 20 5e 41 66 74 65 72 20 65 61 63 68 20 63 61 6c   ^After each cal
32af0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74  l to sqlite3_set
32b00 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58  _auxdata(C,N,P,X
32b10 29 20 77 68 65 72 65 20 58 20 69 73 20 6e 6f 74  ) where X is not
32b20 20 4e 55 4c 4c 2c 0a 2a 2a 20 53 51 4c 69 74 65   NULL,.** SQLite
32b30 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65   will invoke the
32b40 20 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63   destructor func
32b50 74 69 6f 6e 20 58 20 77 69 74 68 20 70 61 72 61  tion X with para
32b60 6d 65 74 65 72 20 50 20 65 78 61 63 74 6c 79 0a  meter P exactly.
32b70 2a 2a 20 6f 6e 63 65 2c 20 77 68 65 6e 20 74 68  ** once, when th
32b80 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 64 69  e metadata is di
32b90 73 63 61 72 64 65 64 2e 0a 2a 2a 20 53 51 4c 69  scarded..** SQLi
32ba0 74 65 20 69 73 20 66 72 65 65 20 74 6f 20 64 69  te is free to di
32bb0 73 63 61 72 64 20 74 68 65 20 6d 65 74 61 64 61  scard the metada
32bc0 74 61 20 61 74 20 61 6e 79 20 74 69 6d 65 2c 20  ta at any time, 
32bd0 69 6e 63 6c 75 64 69 6e 67 3a 20 3c 75 6c 3e 0a  including: <ul>.
32be0 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 74 68 65  ** <li> when the
32bf0 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66   corresponding f
32c00 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65  unction paramete
32c10 72 20 63 68 61 6e 67 65 73 2c 20 6f 72 0a 2a 2a  r changes, or.**
32c20 20 3c 6c 69 3e 20 77 68 65 6e 20 5b 73 71 6c 69   <li> when [sqli
32c30 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
32c40 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
32c50 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 66  e()] is called f
32c60 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 53  or the.**      S
32c70 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 6f 72  QL statement, or
32c80 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 73 71  .** <li> when sq
32c90 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
32ca0 61 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61  a() is invoked a
32cb0 67 61 69 6e 20 6f 6e 20 74 68 65 20 73 61 6d 65  gain on the same
32cc0 20 70 61 72 61 6d 65 74 65 72 2c 20 6f 72 0a 2a   parameter, or.*
32cd0 2a 20 3c 6c 69 3e 20 64 75 72 69 6e 67 20 74 68  * <li> during th
32ce0 65 20 6f 72 69 67 69 6e 61 6c 20 73 71 6c 69 74  e original sqlit
32cf0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
32d00 20 63 61 6c 6c 20 77 68 65 6e 20 61 20 6d 65 6d   call when a mem
32d10 6f 72 79 20 0a 2a 2a 20 20 20 20 20 20 61 6c 6c  ory .**      all
32d20 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63  ocation error oc
32d30 63 75 72 73 2e 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  curs. </ul>)^.**
32d40 0a 2a 2a 20 4e 6f 74 65 20 74 68 65 20 6c 61 73  .** Note the las
32d50 74 20 62 75 6c 6c 65 74 20 69 6e 20 70 61 72 74  t bullet in part
32d60 69 63 75 6c 61 72 2e 20 20 54 68 65 20 64 65 73  icular.  The des
32d70 74 72 75 63 74 6f 72 20 58 20 69 6e 20 0a 2a 2a  tructor X in .**
32d80 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
32d90 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 6d 69  data(C,N,P,X) mi
32da0 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20 69 6d  ght be called im
32db0 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72  mediately, befor
32dc0 65 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33  e the.** sqlite3
32dd0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69  _set_auxdata() i
32de0 6e 74 65 72 66 61 63 65 20 65 76 65 6e 20 72 65  nterface even re
32df0 74 75 72 6e 73 2e 20 20 48 65 6e 63 65 20 73 71  turns.  Hence sq
32e00 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
32e10 61 28 29 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65  a().** should be
32e20 20 63 61 6c 6c 65 64 20 6e 65 61 72 20 74 68 65   called near the
32e30 20 65 6e 64 20 6f 66 20 74 68 65 20 66 75 6e 63   end of the func
32e40 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
32e50 69 6f 6e 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66  ion and the.** f
32e60 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
32e70 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f  tation should no
32e80 74 20 6d 61 6b 65 20 61 6e 79 20 75 73 65 20 6f  t make any use o
32e90 66 20 50 20 61 66 74 65 72 0a 2a 2a 20 73 71 6c  f P after.** sql
32ea0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
32eb0 28 29 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c  () has been call
32ec0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70  ed..**.** ^(In p
32ed0 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64 61 74  ractice, metadat
32ee0 61 20 69 73 20 70 72 65 73 65 72 76 65 64 20 62  a is preserved b
32ef0 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20  etween function 
32f00 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 66 75 6e  calls for.** fun
32f10 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 73  ction parameters
32f20 20 74 68 61 74 20 61 72 65 20 63 6f 6d 70 69 6c   that are compil
32f30 65 2d 74 69 6d 65 20 63 6f 6e 73 74 61 6e 74 73  e-time constants
32f40 2c 20 69 6e 63 6c 75 64 69 6e 67 20 6c 69 74 65  , including lite
32f50 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e  ral.** values an
32f60 64 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 20 61  d [parameters] a
32f70 6e 64 20 65 78 70 72 65 73 73 69 6f 6e 73 20 63  nd expressions c
32f80 6f 6d 70 6f 73 65 64 20 66 72 6f 6d 20 74 68 65  omposed from the
32f90 20 73 61 6d 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54   same.)^.**.** T
32fa0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75  hese routines mu
32fb0 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
32fc0 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
32fd0 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68  d in which.** th
32fe0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  e SQL function i
32ff0 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f  s running..*/.vo
33000 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f  id *sqlite3_get_
33010 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f  auxdata(sqlite3_
33020 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29  context*, int N)
33030 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73  ;.void sqlite3_s
33040 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74  et_auxdata(sqlit
33050 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
33060 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20   N, void*, void 
33070 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f  (*)(void*));.../
33080 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
33090 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e  onstants Definin
330a0 67 20 53 70 65 63 69 61 6c 20 44 65 73 74 72 75  g Special Destru
330b0 63 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a  ctor Behavior.**
330c0 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73 70  .** These are sp
330d0 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72  ecial values for
330e0 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
330f0 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20 69  that is passed i
33100 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61  n as the.** fina
33110 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f  l argument to ro
33120 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c  utines like [sql
33130 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
33140 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 64 65  ()].  ^If the de
33150 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75  structor.** argu
33160 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53  ment is SQLITE_S
33170 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20  TATIC, it means 
33180 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74  that the content
33190 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73   pointer is cons
331a0 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c  tant.** and will
331b0 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20   never change.  
331c0 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  It does not need
331d0 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64   to be destroyed
331e0 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54  .  ^The.** SQLIT
331f0 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75  E_TRANSIENT valu
33200 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  e means that the
33210 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69   content will li
33220 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a  kely change in.*
33230 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74 75 72  * the near futur
33240 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74  e and that SQLit
33250 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74  e should make it
33260 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
33270 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e  py of.** the con
33280 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75  tent before retu
33290 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rning..**.** The
332a0 20 74 79 70 65 64 65 66 20 69 73 20 6e 65 63 65   typedef is nece
332b0 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72  ssary to work ar
332c0 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e  ound problems in
332d0 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20   certain.** C++ 
332e0 63 6f 6d 70 69 6c 65 72 73 2e 0a 2a 2f 0a 74 79  compilers..*/.ty
332f0 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c  pedef void (*sql
33300 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f  ite3_destructor_
33310 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64  type)(void*);.#d
33320 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41  efine SQLITE_STA
33330 54 49 43 20 20 20 20 20 20 28 28 73 71 6c 69 74  TIC      ((sqlit
33340 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79  e3_destructor_ty
33350 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51  pe)0).#define SQ
33360 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20  LITE_TRANSIENT  
33370 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72   ((sqlite3_destr
33380 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a  uctor_type)-1)..
33390 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
333a0 53 65 74 74 69 6e 67 20 54 68 65 20 52 65 73 75  Setting The Resu
333b0 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e  lt Of An SQL Fun
333c0 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ction.**.** Thes
333d0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75  e routines are u
333e0 73 65 64 20 62 79 20 74 68 65 20 78 46 75 6e 63  sed by the xFunc
333f0 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62   or xFinal callb
33400 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70  acks that.** imp
33410 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 74  lement SQL funct
33420 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
33430 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71  tes.  See.** [sq
33440 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
33450 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  ction()] and [sq
33460 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
33470 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f  ction16()].** fo
33480 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  r additional inf
33490 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
334a0 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
334b0 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20 6c  work very much l
334c0 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d 65 74  ike the [paramet
334d0 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69  er binding] fami
334e0 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f  ly of.** functio
334f0 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e 64 20  ns used to bind 
33500 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70  values to host p
33510 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72 65  arameters in pre
33520 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
33530 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 68  ..** Refer to th
33540 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  e [SQL parameter
33550 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
33560 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
33570 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
33580 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
33590 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74  esult_blob() int
335a0 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
335b0 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61  result from.** a
335c0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
335d0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
335e0 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77 68  o be the BLOB wh
335f0 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20 70  ose content is p
33600 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20  ointed.** to by 
33610 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
33620 65 74 65 72 20 61 6e 64 20 77 68 69 63 68 20 69  eter and which i
33630 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20 77  s N bytes long w
33640 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a  here N is the.**
33650 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
33660 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
33670 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f  ite3_result_zero
33680 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65  blob() interface
33690 73 20 73 65 74 20 74 68 65 20 72 65 73 75 6c 74  s set the result
336a0 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
336b0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
336c0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
336d0 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20  BLOB containing 
336e0 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65  all zero.** byte
336f0 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e  s and N bytes in
33700 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20 69   size, where N i
33710 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
33720 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
33730 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
33740 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62  ite3_result_doub
33750 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  le() interface s
33760 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66  ets the result f
33770 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63  rom.** an applic
33780 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
33790 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66  nction to be a f
337a0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
337b0 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  lue specified.**
337c0 20 62 79 20 69 74 73 20 32 6e 64 20 61 72 67 75   by its 2nd argu
337d0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ment..**.** ^The
337e0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
337f0 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69  error() and sqli
33800 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
33810 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  16() functions.*
33820 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c  * cause the impl
33830 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63  emented SQL func
33840 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e  tion to throw an
33850 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e   exception..** ^
33860 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20  SQLite uses the 
33870 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74  string pointed t
33880 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20  o by the.** 2nd 
33890 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c  parameter of sql
338a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
338b0 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  r() or sqlite3_r
338c0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a  esult_error16().
338d0 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74 20 6f  ** as the text o
338e0 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  f an error messa
338f0 67 65 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e 74  ge.  ^SQLite int
33900 65 72 70 72 65 74 73 20 74 68 65 20 65 72 72 6f  erprets the erro
33910 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 72  r.** message str
33920 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ing from sqlite3
33930 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
33940 61 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74  as UTF-8. ^SQLit
33950 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20  e.** interprets 
33960 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  the string from 
33970 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
33980 72 72 6f 72 31 36 28 29 20 61 73 20 55 54 46 2d  rror16() as UTF-
33990 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20  16 in native.** 
339a0 62 79 74 65 20 6f 72 64 65 72 2e 20 20 5e 49 66  byte order.  ^If
339b0 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
339c0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
339d0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a  result_error().*
339e0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
339f0 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73  ult_error16() is
33a00 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53   negative then S
33a10 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20 74  QLite takes as t
33a20 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73  he error.** mess
33a30 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70 20  age all text up 
33a40 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73  through the firs
33a50 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72  t zero character
33a60 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69  ..** ^If the thi
33a70 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
33a80 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
33a90 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c  rror() or.** sql
33aa0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
33ab0 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67  r16() is non-neg
33ac0 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74  ative then SQLit
33ad0 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e  e takes that man
33ae0 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20  y.** bytes (not 
33af0 63 68 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d  characters) from
33b00 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
33b10 65 72 20 61 73 20 74 68 65 20 65 72 72 6f 72 20  er as the error 
33b20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65  message..** ^The
33b30 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33b40 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69  error() and sqli
33b50 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
33b60 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  16().** routines
33b70 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65 20   make a private 
33b80 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f  copy of the erro
33b90 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 62  r message text b
33ba0 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65  efore.** they re
33bb0 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68  turn.  Hence, th
33bc0 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69  e calling functi
33bd0 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74  on can deallocat
33be0 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74  e or.** modify t
33bf0 68 65 20 74 65 78 74 20 61 66 74 65 72 20 74 68  he text after th
33c00 65 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75  ey return withou
33c10 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20  t harm..** ^The 
33c20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
33c30 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63  rror_code() func
33c40 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65  tion changes the
33c50 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72   error code.** r
33c60 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74  eturned by SQLit
33c70 65 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66  e as a result of
33c80 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66   an error in a f
33c90 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65  unction.  ^By de
33ca0 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72  fault,.** the er
33cb0 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49  ror code is SQLI
33cc0 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20 73 75  TE_ERROR.  ^A su
33cd0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f  bsequent call to
33ce0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33cf0 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71  error().** or sq
33d00 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
33d10 6f 72 31 36 28 29 20 72 65 73 65 74 73 20 74 68  or16() resets th
33d20 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f 20  e error code to 
33d30 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a  SQLITE_ERROR..**
33d40 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
33d50 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f  _result_error_to
33d60 6f 62 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  obig() interface
33d70 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74   causes SQLite t
33d80 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72  o throw an.** er
33d90 72 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20 74  ror indicating t
33da0 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20  hat a string or 
33db0 42 4c 4f 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67  BLOB is too long
33dc0 20 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a   to represent..*
33dd0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
33de0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e  3_result_error_n
33df0 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65  omem() interface
33e00 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74   causes SQLite t
33e10 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72  o throw an.** er
33e20 72 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20 74  ror indicating t
33e30 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  hat a memory all
33e40 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a  ocation failed..
33e50 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
33e60 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 20  e3_result_int() 
33e70 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
33e80 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
33e90 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ** of the applic
33ea0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
33eb0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65  nction to be the
33ec0 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69   32-bit signed i
33ed0 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20  nteger.** value 
33ee0 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64  given in the 2nd
33ef0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54   argument..** ^T
33f00 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
33f10 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66  t_int64() interf
33f20 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
33f30 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
33f40 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
33f50 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
33f60 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69   to be the 64-bi
33f70 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
33f80 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20  .** value given 
33f90 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d  in the 2nd argum
33fa0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ent..**.** ^The 
33fb0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e  sqlite3_result_n
33fc0 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20  ull() interface 
33fd0 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20  sets the return 
33fe0 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20  value.** of the 
33ff0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
34000 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
34010 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  be NULL..**.** ^
34020 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
34030 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74  lt_text(), sqlit
34040 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
34050 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72  (),.** sqlite3_r
34060 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29  esult_text16le()
34070 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  , and sqlite3_re
34080 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29 20  sult_text16be() 
34090 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 65  interfaces.** se
340a0 74 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  t the return val
340b0 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ue of the applic
340c0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
340d0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20  nction to be.** 
340e0 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 77 68  a text string wh
340f0 69 63 68 20 69 73 20 72 65 70 72 65 73 65 6e 74  ich is represent
34100 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54 46  ed as UTF-8, UTF
34110 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20  -16 native byte 
34120 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36  order,.** UTF-16
34130 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20   little endian, 
34140 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20 65 6e  or UTF-16 big en
34150 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65  dian, respective
34160 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 74  ly..** ^SQLite t
34170 61 6b 65 73 20 74 68 65 20 74 65 78 74 20 72 65  akes the text re
34180 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 70  sult from the ap
34190 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a  plication from.*
341a0 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  * the 2nd parame
341b0 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74  ter of the sqlit
341c0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
341d0 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 5e  interfaces..** ^
341e0 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
341f0 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
34200 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
34210 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69   interfaces.** i
34220 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
34230 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72 65   SQLite takes re
34240 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 74  sult text from t
34250 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
34260 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20  .** through the 
34270 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61  first zero chara
34280 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  cter..** ^If the
34290 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
342a0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
342b0 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
342c0 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d  faces.** is non-
342d0 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61  negative, then a
342e0 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e 6f  s many bytes (no
342f0 74 20 63 68 61 72 61 63 74 65 72 73 29 20 6f 66  t characters) of
34300 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69   the text.** poi
34310 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 32  nted to by the 2
34320 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 72 65  nd parameter are
34330 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61 70   taken as the ap
34340 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
34350 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65  d.** function re
34360 73 75 6c 74 2e 20 20 49 66 20 74 68 65 20 33 72  sult.  If the 3r
34370 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e  d parameter is n
34380 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
34390 6e 20 69 74 0a 2a 2a 20 6d 75 73 74 20 62 65 20  n it.** must be 
343a0 74 68 65 20 62 79 74 65 20 6f 66 66 73 65 74 20  the byte offset 
343b0 69 6e 74 6f 20 74 68 65 20 73 74 72 69 6e 67 20  into the string 
343c0 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65  where the NUL te
343d0 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 0a 2a  rminator would.*
343e0 2a 20 61 70 70 65 61 72 20 69 66 20 74 68 65 20  * appear if the 
343f0 73 74 72 69 6e 67 20 77 68 65 72 65 20 4e 55 4c  string where NUL
34400 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66   terminated.  If
34410 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74   any NUL charact
34420 65 72 73 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20  ers occur.** in 
34430 74 68 65 20 73 74 72 69 6e 67 20 61 74 20 61 20  the string at a 
34440 62 79 74 65 20 6f 66 66 73 65 74 20 74 68 61 74  byte offset that
34450 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 74 68   is less than th
34460 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 33  e value of the 3
34470 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c  rd.** parameter,
34480 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
34490 69 6e 67 20 73 74 72 69 6e 67 20 77 69 6c 6c 20  ing string will 
344a0 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64  contain embedded
344b0 20 4e 55 4c 73 20 61 6e 64 20 74 68 65 0a 2a 2a   NULs and the.**
344c0 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65   result of expre
344d0 73 73 69 6f 6e 73 20 6f 70 65 72 61 74 69 6e 67  ssions operating
344e0 20 6f 6e 20 73 74 72 69 6e 67 73 20 77 69 74 68   on strings with
344f0 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69   embedded NULs i
34500 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
34510 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61  ^If the 4th para
34520 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
34530 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
34540 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
34550 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
34560 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d  t_blob is a non-
34570 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68  NULL pointer, th
34580 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20  en SQLite calls 
34590 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  that.** function
345a0 20 61 73 20 74 68 65 20 64 65 73 74 72 75 63 74   as the destruct
345b0 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f  or on the text o
345c0 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 68  r BLOB result wh
345d0 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e  en it has.** fin
345e0 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74  ished using that
345f0 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20   result..** ^If 
34600 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
34610 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
34620 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
34630 74 65 72 66 61 63 65 73 20 6f 72 20 74 6f 0a 2a  terfaces or to.*
34640 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
34650 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65  _blob is the spe
34660 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51  cial constant SQ
34670 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68 65  LITE_STATIC, the
34680 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75  n SQLite.** assu
34690 6d 65 73 20 74 68 61 74 20 74 68 65 20 74 65 78  mes that the tex
346a0 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74  t or BLOB result
346b0 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20   is in constant 
346c0 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e  space and does n
346d0 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20 63  ot.** copy the c
346e0 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 70 61  ontent of the pa
346f0 72 61 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c 6c  rameter nor call
34700 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e   a destructor on
34710 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20   the content.** 
34720 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69  when it has fini
34730 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20  shed using that 
34740 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74  result..** ^If t
34750 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
34760 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
34770 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
34780 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71  erfaces.** or sq
34790 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
347a0 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c  b is the special
347b0 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45   constant SQLITE
347c0 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68  _TRANSIENT.** th
347d0 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  en SQLite makes 
347e0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65  a copy of the re
347f0 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20  sult into space 
34800 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a  obtained from.**
34810 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
34820 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20  alloc()] before 
34830 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  it returns..**.*
34840 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
34850 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e  esult_value() in
34860 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
34870 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68   result of.** th
34880 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
34890 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
348a0 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68 65 0a  o be a copy the.
348b0 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
348c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
348d0 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 64 20  bject specified 
348e0 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  by the 2nd param
348f0 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 73  eter.  ^The.** s
34900 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
34910 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  lue() interface 
34920 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
34930 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
34940 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74  ue].** so that t
34950 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
34960 65 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e 20  e] specified in 
34970 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61  the parameter ma
34980 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62  y change or.** b
34990 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 66  e deallocated af
349a0 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75  ter sqlite3_resu
349b0 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75 72  lt_value() retur
349c0 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e  ns without harm.
349d0 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63 74 65  .** ^A [protecte
349e0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
349f0 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 61   object may alwa
34a00 79 73 20 62 65 20 75 73 65 64 20 77 68 65 72 65  ys be used where
34a10 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63   an.** [unprotec
34a20 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
34a30 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65 71  e] object is req
34a40 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68 65 72  uired, so either
34a50 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c  .** kind of [sql
34a60 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
34a70 63 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 77  ct can be used w
34a80 69 74 68 20 74 68 69 73 20 69 6e 74 65 72 66 61  ith this interfa
34a90 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ce..**.** If the
34aa0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
34ab0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68  called from with
34ac0 69 6e 20 74 68 65 20 64 69 66 66 65 72 65 6e 74  in the different
34ad0 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20   thread.** than 
34ae0 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69  the one containi
34af0 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ng the applicati
34b00 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
34b10 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69 76 65  ion that receive
34b20 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  d.** the [sqlite
34b30 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74  3_context] point
34b40 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20  er, the results 
34b50 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
34b60 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  /.void sqlite3_r
34b70 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74  esult_blob(sqlit
34b80 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
34b90 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
34ba0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
34bb0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
34bc0 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  ult_double(sqlit
34bd0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75  e3_context*, dou
34be0 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  ble);.void sqlit
34bf0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
34c00 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
34c10 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  , const char*, i
34c20 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
34c30 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
34c40 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
34c50 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
34c60 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
34c70 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
34c80 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63  toobig(sqlite3_c
34c90 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73  ontext*);.void s
34ca0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
34cb0 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65  ror_nomem(sqlite
34cc0 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69  3_context*);.voi
34cd0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
34ce0 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69  _error_code(sqli
34cf0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
34d00 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
34d10 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69  _result_int(sqli
34d20 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
34d30 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
34d40 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71  _result_int64(sq
34d50 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
34d60 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
34d70 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
34d80 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33  ult_null(sqlite3
34d90 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64  _context*);.void
34da0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34db0 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  text(sqlite3_con
34dc0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  text*, const cha
34dd0 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  r*, int, void(*)
34de0 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
34df0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
34e00 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e  xt16(sqlite3_con
34e10 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
34e20 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
34e30 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
34e40 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
34e50 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63  xt16le(sqlite3_c
34e60 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
34e70 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a  oid*, int,void(*
34e80 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
34e90 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
34ea0 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f  ext16be(sqlite3_
34eb0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
34ec0 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28  void*, int,void(
34ed0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
34ee0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34ef0 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f  value(sqlite3_co
34f00 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f  ntext*, sqlite3_
34f10 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71  value*);.void sq
34f20 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72  lite3_result_zer
34f30 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f  oblob(sqlite3_co
34f40 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a  ntext*, int n);.
34f50 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
34f60 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c   Define New Coll
34f70 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73 0a  ating Sequences.
34f80 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e  **.** ^These fun
34f90 63 74 69 6f 6e 73 20 61 64 64 2c 20 72 65 6d 6f  ctions add, remo
34fa0 76 65 2c 20 6f 72 20 6d 6f 64 69 66 79 20 61 20  ve, or modify a 
34fb0 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61 73 73 6f  [collation] asso
34fc0 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74  ciated.** with t
34fd0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
34fe0 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69  nection] specifi
34ff0 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
35000 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
35010 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65  ^The name of the
35020 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 61 20   collation is a 
35030 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20  UTF-8 string.** 
35040 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61  for sqlite3_crea
35050 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61  te_collation() a
35060 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nd sqlite3_creat
35070 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
35080 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 36  .** and a UTF-16
35090 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76   string in nativ
350a0 65 20 62 79 74 65 20 6f 72 64 65 72 20 66 6f 72  e byte order for
350b0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
350c0 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a  collation16()..*
350d0 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d  * ^Collation nam
350e0 65 73 20 74 68 61 74 20 63 6f 6d 70 61 72 65 20  es that compare 
350f0 65 71 75 61 6c 20 61 63 63 6f 72 64 69 6e 67 20  equal according 
35100 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 72 6e  to [sqlite3_strn
35110 69 63 6d 70 28 29 5d 20 61 72 65 0a 2a 2a 20 63  icmp()] are.** c
35120 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 62 65 20  onsidered to be 
35130 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a  the same name..*
35140 2a 0a 2a 2a 20 5e 28 54 68 65 20 74 68 69 72 64  *.** ^(The third
35150 20 61 72 67 75 6d 65 6e 74 20 28 65 54 65 78 74   argument (eText
35160 52 65 70 29 20 6d 75 73 74 20 62 65 20 6f 6e 65  Rep) must be one
35170 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e 74   of the constant
35180 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  s:.** <ul>.** <l
35190 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  i> [SQLITE_UTF8]
351a0 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
351b0 45 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a 2a 20 3c  E_UTF16LE],.** <
351c0 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  li> [SQLITE_UTF1
351d0 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  6BE],.** <li> [S
351e0 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 6f 72  QLITE_UTF16], or
351f0 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
35200 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 2e  _UTF16_ALIGNED].
35210 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e  .** </ul>)^.** ^
35220 54 68 65 20 65 54 65 78 74 52 65 70 20 61 72 67  The eTextRep arg
35230 75 6d 65 6e 74 20 64 65 74 65 72 6d 69 6e 65 73  ument determines
35240 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66   the encoding of
35250 20 73 74 72 69 6e 67 73 20 70 61 73 73 65 64 0a   strings passed.
35260 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74  ** to the collat
35270 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c  ing function cal
35280 6c 62 61 63 6b 2c 20 78 43 61 6c 6c 62 61 63 6b  lback, xCallback
35290 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ..** ^The [SQLIT
352a0 45 5f 55 54 46 31 36 5d 20 61 6e 64 20 5b 53 51  E_UTF16] and [SQ
352b0 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
352c0 45 44 5d 20 76 61 6c 75 65 73 20 66 6f 72 20 65  ED] values for e
352d0 54 65 78 74 52 65 70 0a 2a 2a 20 66 6f 72 63 65  TextRep.** force
352e0 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65 20 55   strings to be U
352f0 54 46 31 36 20 77 69 74 68 20 6e 61 74 69 76 65  TF16 with native
35300 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20   byte order..** 
35310 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 46  ^The [SQLITE_UTF
35320 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75  16_ALIGNED] valu
35330 65 20 66 6f 72 20 65 54 65 78 74 52 65 70 20 66  e for eTextRep f
35340 6f 72 63 65 73 20 73 74 72 69 6e 67 73 20 74 6f  orces strings to
35350 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20 61 6e 20   begin.** on an 
35360 65 76 65 6e 20 62 79 74 65 20 61 64 64 72 65 73  even byte addres
35370 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f  s..**.** ^The fo
35380 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 70  urth argument, p
35390 41 72 67 2c 20 69 73 20 61 6e 20 61 70 70 6c 69  Arg, is an appli
353a0 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
353b0 74 65 72 20 74 68 61 74 20 69 73 20 70 61 73 73  ter that is pass
353c0 65 64 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 73  ed.** through as
353d0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
353e0 65 6e 74 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61  ent to the colla
353f0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61  ting function ca
35400 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54  llback..**.** ^T
35410 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
35420 74 2c 20 78 43 61 6c 6c 62 61 63 6b 2c 20 69 73  t, xCallback, is
35430 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
35440 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
35450 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74 69 70  tion..** ^Multip
35460 6c 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  le collating fun
35470 63 74 69 6f 6e 73 20 63 61 6e 20 62 65 20 72 65  ctions can be re
35480 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 74  gistered using t
35490 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74  he same name but
354a0 0a 2a 2a 20 77 69 74 68 20 64 69 66 66 65 72 65  .** with differe
354b0 6e 74 20 65 54 65 78 74 52 65 70 20 70 61 72 61  nt eTextRep para
354c0 6d 65 74 65 72 73 20 61 6e 64 20 53 51 4c 69 74  meters and SQLit
354d0 65 20 77 69 6c 6c 20 75 73 65 20 77 68 69 63 68  e will use which
354e0 65 76 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ever.** function
354f0 20 72 65 71 75 69 72 65 73 20 74 68 65 20 6c 65   requires the le
35500 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61  ast amount of da
35510 74 61 20 74 72 61 6e 73 66 6f 72 6d 61 74 69 6f  ta transformatio
35520 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 78 43  n..** ^If the xC
35530 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e 74  allback argument
35540 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68   is NULL then th
35550 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
35560 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 6c 65 74  tion is.** delet
35570 65 64 2e 20 20 5e 57 68 65 6e 20 61 6c 6c 20 63  ed.  ^When all c
35580 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
35590 6e 73 20 68 61 76 69 6e 67 20 74 68 65 20 73 61  ns having the sa
355a0 6d 65 20 6e 61 6d 65 20 61 72 65 20 64 65 6c 65  me name are dele
355b0 74 65 64 2c 0a 2a 2a 20 74 68 61 74 20 63 6f 6c  ted,.** that col
355c0 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e  lation is no lon
355d0 67 65 72 20 75 73 61 62 6c 65 2e 0a 2a 2a 0a 2a  ger usable..**.*
355e0 2a 20 5e 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67  * ^The collating
355f0 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61   function callba
35600 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69  ck is invoked wi
35610 74 68 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  th a copy of the
35620 20 70 41 72 67 20 0a 2a 2a 20 61 70 70 6c 69 63   pArg .** applic
35630 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
35640 65 72 20 61 6e 64 20 77 69 74 68 20 74 77 6f 20  er and with two 
35650 73 74 72 69 6e 67 73 20 69 6e 20 74 68 65 20 65  strings in the e
35660 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69 65  ncoding specifie
35670 64 0a 2a 2a 20 62 79 20 74 68 65 20 65 54 65 78  d.** by the eTex
35680 74 52 65 70 20 61 72 67 75 6d 65 6e 74 2e 20 20  tRep argument.  
35690 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  The collating fu
356a0 6e 63 74 69 6f 6e 20 6d 75 73 74 20 72 65 74 75  nction must retu
356b0 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72  rn an.** integer
356c0 20 74 68 61 74 20 69 73 20 6e 65 67 61 74 69 76   that is negativ
356d0 65 2c 20 7a 65 72 6f 2c 20 6f 72 20 70 6f 73 69  e, zero, or posi
356e0 74 69 76 65 0a 2a 2a 20 69 66 20 74 68 65 20 66  tive.** if the f
356f0 69 72 73 74 20 73 74 72 69 6e 67 20 69 73 20 6c  irst string is l
35700 65 73 73 20 74 68 61 6e 2c 20 65 71 75 61 6c 20  ess than, equal 
35710 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20 74  to, or greater t
35720 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 2c 0a  han the second,.
35730 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  ** respectively.
35740 20 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75    A collating fu
35750 6e 63 74 69 6f 6e 20 6d 75 73 74 20 61 6c 77 61  nction must alwa
35760 79 73 20 72 65 74 75 72 6e 20 74 68 65 20 73 61  ys return the sa
35770 6d 65 20 61 6e 73 77 65 72 0a 2a 2a 20 67 69 76  me answer.** giv
35780 65 6e 20 74 68 65 20 73 61 6d 65 20 69 6e 70 75  en the same inpu
35790 74 73 2e 20 20 49 66 20 74 77 6f 20 6f 72 20 6d  ts.  If two or m
357a0 6f 72 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  ore collating fu
357b0 6e 63 74 69 6f 6e 73 20 61 72 65 20 72 65 67 69  nctions are regi
357c0 73 74 65 72 65 64 0a 2a 2a 20 74 6f 20 74 68 65  stered.** to the
357d0 20 73 61 6d 65 20 63 6f 6c 6c 61 74 69 6f 6e 20   same collation 
357e0 6e 61 6d 65 20 28 75 73 69 6e 67 20 64 69 66 66  name (using diff
357f0 65 72 65 6e 74 20 65 54 65 78 74 52 65 70 20 76  erent eTextRep v
35800 61 6c 75 65 73 29 20 74 68 65 6e 20 61 6c 6c 0a  alues) then all.
35810 2a 2a 20 6d 75 73 74 20 67 69 76 65 20 61 6e 20  ** must give an 
35820 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 73 77 65  equivalent answe
35830 72 20 77 68 65 6e 20 69 6e 76 6f 6b 65 64 20 77  r when invoked w
35840 69 74 68 20 65 71 75 69 76 61 6c 65 6e 74 20 73  ith equivalent s
35850 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 20 63  trings..** The c
35860 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
35870 6e 20 6d 75 73 74 20 6f 62 65 79 20 74 68 65 20  n must obey the 
35880 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f 70 65 72  following proper
35890 74 69 65 73 20 66 6f 72 20 61 6c 6c 0a 2a 2a 20  ties for all.** 
358a0 73 74 72 69 6e 67 73 20 41 2c 20 42 2c 20 61 6e  strings A, B, an
358b0 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  d C:.**.** <ol>.
358c0 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20  ** <li> If A==B 
358d0 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a 20 3c 6c  then B==A..** <l
358e0 69 3e 20 49 66 20 41 3d 3d 42 20 61 6e 64 20 42  i> If A==B and B
358f0 3d 3d 43 20 74 68 65 6e 20 41 3d 3d 43 2e 0a 2a  ==C then A==C..*
35900 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42  * <li> If A&lt;B
35910 20 54 48 45 4e 20 42 26 67 74 3b 41 2e 0a 2a 2a   THEN B&gt;A..**
35920 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 20   <li> If A&lt;B 
35930 61 6e 64 20 42 26 6c 74 3b 43 20 74 68 65 6e 20  and B&lt;C then 
35940 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c 3e  A&lt;C..** </ol>
35950 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 6f 6c 6c  .**.** If a coll
35960 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 66  ating function f
35970 61 69 6c 73 20 61 6e 79 20 6f 66 20 74 68 65 20  ails any of the 
35980 61 62 6f 76 65 20 63 6f 6e 73 74 72 61 69 6e 74  above constraint
35990 73 20 61 6e 64 20 74 68 61 74 0a 2a 2a 20 63 6f  s and that.** co
359a0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
359b0 20 69 73 20 20 72 65 67 69 73 74 65 72 65 64 20   is  registered 
359c0 61 6e 64 20 75 73 65 64 2c 20 74 68 65 6e 20 74  and used, then t
359d0 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53  he behavior of S
359e0 51 4c 69 74 65 0a 2a 2a 20 69 73 20 75 6e 64 65  QLite.** is unde
359f0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
35a00 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
35a10 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20  _collation_v2() 
35a20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74  works like sqlit
35a30 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
35a40 69 6f 6e 28 29 0a 2a 2a 20 77 69 74 68 20 74 68  ion().** with th
35a50 65 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20  e addition that 
35a60 74 68 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c  the xDestroy cal
35a70 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
35a80 20 6f 6e 20 70 41 72 67 20 77 68 65 6e 0a 2a 2a   on pArg when.**
35a90 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   the collating f
35aa0 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74  unction is delet
35ab0 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6e  ed..** ^Collatin
35ac0 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  g functions are 
35ad0 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65  deleted when the
35ae0 79 20 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e  y are overridden
35af0 20 62 79 20 6c 61 74 65 72 0a 2a 2a 20 63 61 6c   by later.** cal
35b00 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74  ls to the collat
35b10 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 6e  ion creation fun
35b20 63 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74  ctions or when t
35b30 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  he.** [database 
35b40 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63  connection] is c
35b50 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  losed using [sql
35b60 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a  ite3_close()]..*
35b70 2a 0a 2a 2a 20 5e 54 68 65 20 78 44 65 73 74 72  *.** ^The xDestr
35b80 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 3c  oy callback is <
35b90 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c 6c 65 64  u>not</u> called
35ba0 20 69 66 20 74 68 65 20 0a 2a 2a 20 73 71 6c 69   if the .** sqli
35bb0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
35bc0 74 69 6f 6e 5f 76 32 28 29 20 66 75 6e 63 74 69  tion_v2() functi
35bd0 6f 6e 20 66 61 69 6c 73 2e 20 20 41 70 70 6c 69  on fails.  Appli
35be0 63 61 74 69 6f 6e 73 20 74 68 61 74 20 69 6e 76  cations that inv
35bf0 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  oke.** sqlite3_c
35c00 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
35c10 76 32 28 29 20 77 69 74 68 20 61 20 6e 6f 6e 2d  v2() with a non-
35c20 4e 55 4c 4c 20 78 44 65 73 74 72 6f 79 20 61 72  NULL xDestroy ar
35c30 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 0a 2a  gument should .*
35c40 2a 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  * check the retu
35c50 72 6e 20 63 6f 64 65 20 61 6e 64 20 64 69 73 70  rn code and disp
35c60 6f 73 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69  ose of the appli
35c70 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
35c80 74 65 72 0a 2a 2a 20 74 68 65 6d 73 65 6c 76 65  ter.** themselve
35c90 73 20 72 61 74 68 65 72 20 74 68 61 6e 20 65 78  s rather than ex
35ca0 70 65 63 74 69 6e 67 20 53 51 4c 69 74 65 20 74  pecting SQLite t
35cb0 6f 20 64 65 61 6c 20 77 69 74 68 20 69 74 20 66  o deal with it f
35cc0 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20 54 68 69 73  or them..** This
35cd0 20 69 73 20 64 69 66 66 65 72 65 6e 74 20 66 72   is different fr
35ce0 6f 6d 20 65 76 65 72 79 20 6f 74 68 65 72 20 53  om every other S
35cf0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
35d00 20 20 54 68 65 20 69 6e 63 6f 6e 73 69 73 74 65    The inconsiste
35d10 6e 63 79 20 0a 2a 2a 20 69 73 20 75 6e 66 6f 72  ncy .** is unfor
35d20 74 75 6e 61 74 65 20 62 75 74 20 63 61 6e 6e 6f  tunate but canno
35d30 74 20 62 65 20 63 68 61 6e 67 65 64 20 77 69 74  t be changed wit
35d40 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 62 61  hout breaking ba
35d50 63 6b 77 61 72 64 73 20 0a 2a 2a 20 63 6f 6d 70  ckwards .** comp
35d60 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a  atibility..**.**
35d70 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 73 71 6c   See also:  [sql
35d80 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
35d90 65 65 64 65 64 28 29 5d 20 61 6e 64 20 5b 73 71  eeded()] and [sq
35da0 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
35db0 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a  needed16()]..*/.
35dc0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
35dd0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20  te_collation(.  
35de0 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e  sqlite3*, .  con
35df0 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
35e00 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
35e10 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a   .  void *pArg,.
35e20 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29    int(*xCompare)
35e30 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
35e40 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74   void*,int,const
35e50 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73   void*).);.int s
35e60 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
35e70 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71  llation_v2(.  sq
35e80 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74  lite3*, .  const
35e90 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20   char *zName, . 
35ea0 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a   int eTextRep, .
35eb0 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20    void *pArg,.  
35ec0 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
35ed0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
35ee0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
35ef0 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78  oid*),.  void(*x
35f00 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a  Destroy)(void*).
35f10 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
35f20 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
35f30 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  6(.  sqlite3*, .
35f40 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e    const void *zN
35f50 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  ame,.  int eText
35f60 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41  Rep, .  void *pA
35f70 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70  rg,.  int(*xComp
35f80 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  are)(void*,int,c
35f90 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63  onst void*,int,c
35fa0 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a  onst void*).);..
35fb0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
35fc0 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64  Collation Needed
35fd0 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a   Callbacks.**.**
35fe0 20 5e 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e   ^To avoid havin
35ff0 67 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c  g to register al
36000 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  l collation sequ
36010 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20 64  ences before a d
36020 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62  atabase.** can b
36030 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65  e used, a single
36040 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
36050 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74  on may be regist
36060 65 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  ered with the.**
36070 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
36080 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20 69 6e 76  ction] to be inv
36090 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e  oked whenever an
360a0 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61   undefined colla
360b0 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65  tion.** sequence
360c0 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a   is required..**
360d0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 75 6e 63  .** ^If the func
360e0 74 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72  tion is register
360f0 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  ed using the sql
36100 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
36110 65 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20  eeded() API,.** 
36120 74 68 65 6e 20 69 74 20 69 73 20 70 61 73 73 65  then it is passe
36130 64 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75  d the names of u
36140 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69  ndefined collati
36150 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73 20  on sequences as 
36160 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64  strings.** encod
36170 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 5e 49 66  ed in UTF-8. ^If
36180 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
36190 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73  on_needed16() is
361a0 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61   used,.** the na
361b0 6d 65 73 20 61 72 65 20 70 61 73 73 65 64 20 61  mes are passed a
361c0 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68  s UTF-16 in mach
361d0 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  ine native byte 
361e0 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c  order..** ^A cal
361f0 6c 20 74 6f 20 65 69 74 68 65 72 20 66 75 6e 63  l to either func
36200 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 74 68  tion replaces th
36210 65 20 65 78 69 73 74 69 6e 67 20 63 6f 6c 6c 61  e existing colla
36220 74 69 6f 6e 2d 6e 65 65 64 65 64 20 63 61 6c 6c  tion-needed call
36230 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68  back..**.** ^(Wh
36240 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
36250 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20  is invoked, the 
36260 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70  first argument p
36270 61 73 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a  assed is a copy.
36280 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64  ** of the second
36290 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
362a0 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
362b0 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71  eeded() or.** sq
362c0 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
362d0 6e 65 65 64 65 64 31 36 28 29 2e 20 20 54 68 65  needed16().  The
362e0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
362f0 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65   is the database
36300 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  .** connection. 
36310 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   The third argum
36320 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53  ent is one of [S
36330 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51  QLITE_UTF8], [SQ
36340 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a  LITE_UTF16BE],.*
36350 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46  * or [SQLITE_UTF
36360 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e  16LE], indicatin
36370 67 20 74 68 65 20 6d 6f 73 74 20 64 65 73 69 72  g the most desir
36380 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65  able form of the
36390 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65   collation.** se
363a0 71 75 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20  quence function 
363b0 72 65 71 75 69 72 65 64 2e 20 20 54 68 65 20 66  required.  The f
363c0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
363d0 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
363e0 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63  he.** required c
363f0 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
36400 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  e.)^.**.** The c
36410 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
36420 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72   should register
36430 20 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c   the desired col
36440 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20  lation using.** 
36450 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
36460 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73  collation()], [s
36470 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
36480 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72  llation16()], or
36490 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
364a0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
364b0 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
364c0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
364d0 65 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a  eded(.  sqlite3*
364e0 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76  , .  void*, .  v
364f0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
36500 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52  ite3*,int eTextR
36510 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a  ep,const char*).
36520 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
36530 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
36540 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  6(.  sqlite3*, .
36550 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28    void*,.  void(
36560 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
36570 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63  *,int eTextRep,c
36580 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a  onst void*).);..
36590 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 48 41  #ifdef SQLITE_HA
365a0 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a 20 53 70  S_CODEC./*.** Sp
365b0 65 63 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f  ecify the key fo
365c0 72 20 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64  r an encrypted d
365d0 61 74 61 62 61 73 65 2e 20 20 54 68 69 73 20 72  atabase.  This r
365e0 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65  outine should be
365f0 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74  .** called right
36600 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f   after sqlite3_o
36610 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  pen()..**.** The
36620 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65   code to impleme
36630 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e  nt this API is n
36640 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20  ot available in 
36650 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61  the public relea
36660 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e  se.** of SQLite.
36670 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
36680 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  key(.  sqlite3 *
36690 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
366a0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
366b0 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20  e to be rekeyed 
366c0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
366d0 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20  *pKey, int nKey 
366e0 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a      /* The key *
366f0 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
36700 5f 6b 65 79 5f 76 32 28 0a 20 20 73 71 6c 69 74  _key_v2(.  sqlit
36710 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
36720 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
36730 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65  abase to be reke
36740 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  yed */.  const c
36750 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20  har *zDbName,   
36760 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20          /* Name 
36770 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
36780 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
36790 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20  *pKey, int nKey 
367a0 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a      /* The key *
367b0 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e  /.);../*.** Chan
367c0 67 65 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e  ge the key on an
367d0 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 2e 20   open database. 
367e0 20 49 66 20 74 68 65 20 63 75 72 72 65 6e 74 20   If the current 
367f0 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a  database is not.
36800 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c 20 74 68  ** encrypted, th
36810 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20  is routine will 
36820 65 6e 63 72 79 70 74 20 69 74 2e 20 20 49 66 20  encrypt it.  If 
36830 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d  pNew==0 or nNew=
36840 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  =0, the.** datab
36850 61 73 65 20 69 73 20 64 65 63 72 79 70 74 65 64  ase is decrypted
36860 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65  ..**.** The code
36870 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68   to implement th
36880 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76  is API is not av
36890 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70  ailable in the p
368a0 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a  ublic release.**
368b0 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69   of SQLite..*/.i
368c0 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79  nt sqlite3_rekey
368d0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
368e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
368f0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74     /* Database t
36900 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a  o be rekeyed */.
36910 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b    const void *pK
36920 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20  ey, int nKey    
36930 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20   /* The new key 
36940 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
36950 33 5f 72 65 6b 65 79 5f 76 32 28 0a 20 20 73 71  3_rekey_v2(.  sq
36960 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
36970 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
36980 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  Database to be r
36990 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73  ekeyed */.  cons
369a0 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c  t char *zDbName,
369b0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61             /* Na
369c0 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
369d0 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  se */.  const vo
369e0 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b  id *pKey, int nK
369f0 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65  ey     /* The ne
36a00 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  w key */.);../*.
36a10 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 61  ** Specify the a
36a20 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f  ctivation key fo
36a30 72 20 61 20 53 45 45 20 64 61 74 61 62 61 73 65  r a SEE database
36a40 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63  .  Unless .** ac
36a50 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66  tivated, none of
36a60 20 74 68 65 20 53 45 45 20 72 6f 75 74 69 6e 65   the SEE routine
36a70 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a  s will work..*/.
36a80 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74  void sqlite3_act
36a90 69 76 61 74 65 5f 73 65 65 28 0a 20 20 63 6f 6e  ivate_see(.  con
36aa0 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68  st char *zPassPh
36ab0 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41  rase        /* A
36ac0 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65  ctivation phrase
36ad0 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 23   */.);.#endif..#
36ae0 69 66 64 65 66 20 53 51 4c 49 54 45 5f 45 4e 41  ifdef SQLITE_ENA
36af0 42 4c 45 5f 43 45 52 4f 44 0a 2f 2a 0a 2a 2a 20  BLE_CEROD./*.** 
36b00 53 70 65 63 69 66 79 20 74 68 65 20 61 63 74 69  Specify the acti
36b10 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61  vation key for a
36b20 20 43 45 52 4f 44 20 64 61 74 61 62 61 73 65 2e   CEROD database.
36b30 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74    Unless .** act
36b40 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20  ivated, none of 
36b50 74 68 65 20 43 45 52 4f 44 20 72 6f 75 74 69 6e  the CEROD routin
36b60 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f  es will work..*/
36b70 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 63  .void sqlite3_ac
36b80 74 69 76 61 74 65 5f 63 65 72 6f 64 28 0a 20 20  tivate_cerod(.  
36b90 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 73  const char *zPas
36ba0 73 50 68 72 61 73 65 20 20 20 20 20 20 20 20 2f  sPhrase        /
36bb0 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68 72  * Activation phr
36bc0 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66  ase */.);.#endif
36bd0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
36be0 3a 20 53 75 73 70 65 6e 64 20 45 78 65 63 75 74  : Suspend Execut
36bf0 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 20  ion For A Short 
36c00 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  Time.**.** The s
36c10 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20 66  qlite3_sleep() f
36c20 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 74  unction causes t
36c30 68 65 20 63 75 72 72 65 6e 74 20 74 68 72 65 61  he current threa
36c40 64 20 74 6f 20 73 75 73 70 65 6e 64 20 65 78 65  d to suspend exe
36c50 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74  cution.** for at
36c60 20 6c 65 61 73 74 20 61 20 6e 75 6d 62 65 72 20   least a number 
36c70 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  of milliseconds 
36c80 73 70 65 63 69 66 69 65 64 20 69 6e 20 69 74 73  specified in its
36c90 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
36ca0 2a 20 49 66 20 74 68 65 20 6f 70 65 72 61 74 69  * If the operati
36cb0 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 73 20 6e  ng system does n
36cc0 6f 74 20 73 75 70 70 6f 72 74 20 73 6c 65 65 70  ot support sleep
36cd0 20 72 65 71 75 65 73 74 73 20 77 69 74 68 0a 2a   requests with.*
36ce0 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69  * millisecond ti
36cf0 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74  me resolution, t
36d00 68 65 6e 20 74 68 65 20 74 69 6d 65 20 77 69 6c  hen the time wil
36d10 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 75 70 20  l be rounded up 
36d20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65 73  to.** the neares
36d30 74 20 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75  t second. The nu
36d40 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63  mber of millisec
36d50 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63  onds of sleep ac
36d60 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73  tually.** reques
36d70 74 65 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65  ted from the ope
36d80 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73  rating system is
36d90 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
36da0 20 5e 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65   ^SQLite impleme
36db0 6e 74 73 20 74 68 69 73 20 69 6e 74 65 72 66 61  nts this interfa
36dc0 63 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 68  ce by calling th
36dd0 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65  e xSleep().** me
36de0 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61  thod of the defa
36df0 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
36e00 5d 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 74 68  ] object.  If th
36e10 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f  e xSleep() metho
36e20 64 0a 2a 2a 20 6f 66 20 74 68 65 20 64 65 66 61  d.** of the defa
36e30 75 6c 74 20 56 46 53 20 69 73 20 6e 6f 74 20 69  ult VFS is not i
36e40 6d 70 6c 65 6d 65 6e 74 65 64 20 63 6f 72 72 65  mplemented corre
36e50 63 74 6c 79 2c 20 6f 72 20 6e 6f 74 20 69 6d 70  ctly, or not imp
36e60 6c 65 6d 65 6e 74 65 64 20 61 74 0a 2a 2a 20 61  lemented at.** a
36e70 6c 6c 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  ll, then the beh
36e80 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33  avior of sqlite3
36e90 5f 73 6c 65 65 70 28 29 20 6d 61 79 20 64 65 76  _sleep() may dev
36ea0 69 61 74 65 20 66 72 6f 6d 20 74 68 65 20 64 65  iate from the de
36eb0 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 20 69 6e 20  scription.** in 
36ec0 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72  the previous par
36ed0 61 67 72 61 70 68 73 2e 0a 2a 2f 0a 69 6e 74 20  agraphs..*/.int 
36ee0 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 69 6e  sqlite3_sleep(in
36ef0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
36f00 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65  REF: Name Of The
36f10 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20   Folder Holding 
36f20 54 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 0a  Temporary Files.
36f30 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73 20  **.** ^(If this 
36f40 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20  global variable 
36f50 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  is made to point
36f60 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69   to a string whi
36f70 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d  ch is.** the nam
36f80 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61  e of a folder (a
36f90 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29  .k.a. directory)
36fa0 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f  , then all tempo
36fb0 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72  rary files.** cr
36fc0 65 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 20  eated by SQLite 
36fd0 77 68 65 6e 20 75 73 69 6e 67 20 61 20 62 75 69  when using a bui
36fe0 6c 74 2d 69 6e 20 5b 73 71 6c 69 74 65 33 5f 76  lt-in [sqlite3_v
36ff0 66 73 20 7c 20 56 46 53 5d 0a 2a 2a 20 77 69 6c  fs | VFS].** wil
37000 6c 20 62 65 20 70 6c 61 63 65 64 20 69 6e 20 74  l be placed in t
37010 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e 29 5e  hat directory.)^
37020 20 20 5e 49 66 20 74 68 69 73 20 76 61 72 69 61    ^If this varia
37030 62 6c 65 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c  ble.** is a NULL
37040 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53   pointer, then S
37050 51 4c 69 74 65 20 70 65 72 66 6f 72 6d 73 20 61  QLite performs a
37060 20 73 65 61 72 63 68 20 66 6f 72 20 61 6e 20 61   search for an a
37070 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 74 65  ppropriate.** te
37080 6d 70 6f 72 61 72 79 20 66 69 6c 65 20 64 69 72  mporary file dir
37090 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74  ectory..**.** It
370a0 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
370b0 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74  read or modify t
370c0 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 6e 20  his variable in 
370d0 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a  more than one.**
370e0 20 74 68 72 65 61 64 20 61 74 20 61 20 74 69 6d   thread at a tim
370f0 65 2e 20 20 49 74 20 69 73 20 6e 6f 74 20 73 61  e.  It is not sa
37100 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f  fe to read or mo
37110 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62  dify this variab
37120 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74 61  le.** if a [data
37130 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
37140 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 61   is being used a
37150 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
37160 69 6e 20 61 20 73 65 70 61 72 61 74 65 0a 2a 2a  in a separate.**
37170 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69   thread..** It i
37180 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20  s intended that 
37190 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 62 65  this variable be
371a0 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20   set once.** as 
371b0 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20  part of process 
371c0 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61  initialization a
371d0 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51  nd before any SQ
371e0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a  Lite interface.*
371f0 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20  * routines have 
37200 62 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20  been called and 
37210 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62  that this variab
37220 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e  le remain unchan
37230 67 65 64 0a 2a 2a 20 74 68 65 72 65 61 66 74 65  ged.** thereafte
37240 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74  r..**.** ^The [t
37250 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
37260 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d 61 79 20  ory pragma] may 
37270 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69  modify this vari
37280 61 62 6c 65 20 61 6e 64 20 63 61 75 73 65 0a 2a  able and cause.*
37290 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f  * it to point to
372a0 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
372b0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
372c0 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 68 65  alloc].  ^Furthe
372d0 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 74  rmore,.** the [t
372e0 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
372f0 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 6c 77 61  ory pragma] alwa
37300 79 73 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  ys assumes that 
37310 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68  any string.** th
37320 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  at this variable
37330 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 68 65   points to is he
37340 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74  ld in memory obt
37350 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b  ained from .** [
37360 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20  sqlite3_malloc] 
37370 61 6e 64 20 74 68 65 20 70 72 61 67 6d 61 20 6d  and the pragma m
37380 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 66 72  ay attempt to fr
37390 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a  ee that memory.*
373a0 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  * using [sqlite3
373b0 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65  _free]..** Hence
373c0 2c 20 69 66 20 74 68 69 73 20 76 61 72 69 61 62  , if this variab
373d0 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20 64  le is modified d
373e0 69 72 65 63 74 6c 79 2c 20 65 69 74 68 65 72 20  irectly, either 
373f0 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  it should be.** 
37400 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64  made NULL or mad
37410 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65  e to point to me
37420 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
37430 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
37440 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74  oc].** or else t
37450 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 74  he use of the [t
37460 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
37470 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 68 6f 75  ory pragma] shou
37480 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a  ld be avoided..*
37490 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20  *.** <b>Note to 
374a0 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20  Windows Runtime 
374b0 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20  users:</b>  The 
374c0 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74  temporary direct
374d0 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a  ory must be set.
374e0 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c  ** prior to call
374f0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  ing [sqlite3_ope
37500 6e 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  n] or [sqlite3_o
37510 70 65 6e 5f 76 32 5d 2e 20 20 4f 74 68 65 72 77  pen_v2].  Otherw
37520 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20  ise, various.** 
37530 66 65 61 74 75 72 65 73 20 74 68 61 74 20 72 65  features that re
37540 71 75 69 72 65 20 74 68 65 20 75 73 65 20 6f 66  quire the use of
37550 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73   temporary files
37560 20 6d 61 79 20 66 61 69 6c 2e 20 20 48 65 72 65   may fail.  Here
37570 20 69 73 20 61 6e 0a 2a 2a 20 65 78 61 6d 70 6c   is an.** exampl
37580 65 20 6f 66 20 68 6f 77 20 74 6f 20 64 6f 20 74  e of how to do t
37590 68 69 73 20 75 73 69 6e 67 20 43 2b 2b 20 77 69  his using C++ wi
375a0 74 68 20 74 68 65 20 57 69 6e 64 6f 77 73 20 52  th the Windows R
375b0 75 6e 74 69 6d 65 3a 0a 2a 2a 0a 2a 2a 20 3c 62  untime:.**.** <b
375c0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
375d0 2a 2a 20 4c 50 43 57 53 54 52 20 7a 50 61 74 68  ** LPCWSTR zPath
375e0 20 3d 20 57 69 6e 64 6f 77 73 3a 3a 53 74 6f 72   = Windows::Stor
375f0 61 67 65 3a 3a 41 70 70 6c 69 63 61 74 69 6f 6e  age::Application
37600 44 61 74 61 3a 3a 43 75 72 72 65 6e 74 2d 3e 0a  Data::Current->.
37610 2a 2a 20 26 6e 62 73 70 3b 20 20 20 20 20 54 65  ** &nbsp;     Te
37620 6d 70 6f 72 61 72 79 46 6f 6c 64 65 72 2d 3e 50  mporaryFolder->P
37630 61 74 68 2d 3e 44 61 74 61 28 29 3b 0a 2a 2a 20  ath->Data();.** 
37640 63 68 61 72 20 7a 50 61 74 68 42 75 66 26 23 39  char zPathBuf&#9
37650 31 3b 4d 41 58 5f 50 41 54 48 20 2b 20 31 26 23  1;MAX_PATH + 1&#
37660 39 33 3b 3b 0a 2a 2a 20 6d 65 6d 73 65 74 28 7a  93;;.** memset(z
37670 50 61 74 68 42 75 66 2c 20 30 2c 20 73 69 7a 65  PathBuf, 0, size
37680 6f 66 28 7a 50 61 74 68 42 75 66 29 29 3b 0a 2a  of(zPathBuf));.*
37690 2a 20 57 69 64 65 43 68 61 72 54 6f 4d 75 6c 74  * WideCharToMult
376a0 69 42 79 74 65 28 43 50 5f 55 54 46 38 2c 20 30  iByte(CP_UTF8, 0
376b0 2c 20 7a 50 61 74 68 2c 20 2d 31 2c 20 7a 50 61  , zPath, -1, zPa
376c0 74 68 42 75 66 2c 20 73 69 7a 65 6f 66 28 7a 50  thBuf, sizeof(zP
376d0 61 74 68 42 75 66 29 2c 0a 2a 2a 20 26 6e 62 73  athBuf),.** &nbs
376e0 70 3b 20 20 20 20 20 4e 55 4c 4c 2c 20 4e 55 4c  p;     NULL, NUL
376f0 4c 29 3b 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74  L);.** sqlite3_t
37700 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 20 3d 20  emp_directory = 
37710 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
37720 22 25 73 22 2c 20 7a 50 61 74 68 42 75 66 29 3b  "%s", zPathBuf);
37730 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
37740 6b 71 75 6f 74 65 3e 0a 2a 2f 0a 53 51 4c 49 54  kquote>.*/.SQLIT
37750 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a 73  E_EXTERN char *s
37760 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65  qlite3_temp_dire
37770 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ctory;../*.** CA
37780 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20  PI3REF: Name Of 
37790 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69  The Folder Holdi
377a0 6e 67 20 44 61 74 61 62 61 73 65 20 46 69 6c 65  ng Database File
377b0 73 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 69  s.**.** ^(If thi
377c0 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c  s global variabl
377d0 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69  e is made to poi
377e0 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77  nt to a string w
377f0 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e  hich is.** the n
37800 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20  ame of a folder 
37810 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72  (a.k.a. director
37820 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 64 61 74  y), then all dat
37830 61 62 61 73 65 20 66 69 6c 65 73 0a 2a 2a 20 73  abase files.** s
37840 70 65 63 69 66 69 65 64 20 77 69 74 68 20 61 20  pecified with a 
37850 72 65 6c 61 74 69 76 65 20 70 61 74 68 6e 61 6d  relative pathnam
37860 65 20 61 6e 64 20 63 72 65 61 74 65 64 20 6f 72  e and created or
37870 20 61 63 63 65 73 73 65 64 20 62 79 0a 2a 2a 20   accessed by.** 
37880 53 51 4c 69 74 65 20 77 68 65 6e 20 75 73 69 6e  SQLite when usin
37890 67 20 61 20 62 75 69 6c 74 2d 69 6e 20 77 69 6e  g a built-in win
378a0 64 6f 77 73 20 5b 73 71 6c 69 74 65 33 5f 76 66  dows [sqlite3_vf
378b0 73 20 7c 20 56 46 53 5d 20 77 69 6c 6c 20 62 65  s | VFS] will be
378c0 20 61 73 73 75 6d 65 64 0a 2a 2a 20 74 6f 20 62   assumed.** to b
378d0 65 20 72 65 6c 61 74 69 76 65 20 74 6f 20 74 68  e relative to th
378e0 61 74 20 64 69 72 65 63 74 6f 72 79 2e 29 5e 20  at directory.)^ 
378f0 5e 49 66 20 74 68 69 73 20 76 61 72 69 61 62 6c  ^If this variabl
37900 65 20 69 73 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70  e is a NULL.** p
37910 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c  ointer, then SQL
37920 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74  ite assumes that
37930 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20 66 69   all database fi
37940 6c 65 73 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  les specified.**
37950 20 77 69 74 68 20 61 20 72 65 6c 61 74 69 76 65   with a relative
37960 20 70 61 74 68 6e 61 6d 65 20 61 72 65 20 72 65   pathname are re
37970 6c 61 74 69 76 65 20 74 6f 20 74 68 65 20 63 75  lative to the cu
37980 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 0a  rrent directory.
37990 2a 2a 20 66 6f 72 20 74 68 65 20 70 72 6f 63 65  ** for the proce
379a0 73 73 2e 20 20 4f 6e 6c 79 20 74 68 65 20 77 69  ss.  Only the wi
379b0 6e 64 6f 77 73 20 56 46 53 20 6d 61 6b 65 73 20  ndows VFS makes 
379c0 75 73 65 20 6f 66 20 74 68 69 73 20 67 6c 6f 62  use of this glob
379d0 61 6c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 3b 20  al.** variable; 
379e0 69 74 20 69 73 20 69 67 6e 6f 72 65 64 20 62 79  it is ignored by
379f0 20 74 68 65 20 75 6e 69 78 20 56 46 53 2e 0a 2a   the unix VFS..*
37a00 2a 0a 2a 2a 20 43 68 61 6e 67 69 6e 67 20 74 68  *.** Changing th
37a10 65 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20  e value of this 
37a20 76 61 72 69 61 62 6c 65 20 77 68 69 6c 65 20 61  variable while a
37a30 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
37a40 74 69 6f 6e 20 69 73 0a 2a 2a 20 6f 70 65 6e 20  tion is.** open 
37a50 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 61 20  can result in a 
37a60 63 6f 72 72 75 70 74 20 64 61 74 61 62 61 73 65  corrupt database
37a70 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f  ..**.** It is no
37a80 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f  t safe to read o
37a90 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61  r modify this va
37aa0 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74  riable in more t
37ab0 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61  han one.** threa
37ac0 64 20 61 74 20 61 20 74 69 6d 65 2e 20 20 49 74  d at a time.  It
37ad0 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
37ae0 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74  read or modify t
37af0 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20  his variable.** 
37b00 69 66 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  if a [database c
37b10 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65  onnection] is be
37b20 69 6e 67 20 75 73 65 64 20 61 74 20 74 68 65 20  ing used at the 
37b30 73 61 6d 65 20 74 69 6d 65 20 69 6e 20 61 20 73  same time in a s
37b40 65 70 61 72 61 74 65 0a 2a 2a 20 74 68 72 65 61  eparate.** threa
37b50 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74 65  d..** It is inte
37b60 6e 64 65 64 20 74 68 61 74 20 74 68 69 73 20 76  nded that this v
37b70 61 72 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f  ariable be set o
37b80 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f  nce.** as part o
37b90 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61  f process initia
37ba0 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66  lization and bef
37bb0 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69  ore any SQLite i
37bc0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74  nterface.** rout
37bd0 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20 63  ines have been c
37be0 61 6c 6c 65 64 20 61 6e 64 20 74 68 61 74 20 74  alled and that t
37bf0 68 69 73 20 76 61 72 69 61 62 6c 65 20 72 65 6d  his variable rem
37c00 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a  ain unchanged.**
37c10 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a   thereafter..**.
37c20 2a 2a 20 5e 54 68 65 20 5b 64 61 74 61 5f 73 74  ** ^The [data_st
37c30 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
37c40 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79  agma] may modify
37c50 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 61   this variable a
37c60 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 74 20 74  nd cause.** it t
37c70 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72  o point to memor
37c80 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
37c90 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d  [sqlite3_malloc]
37ca0 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c  .  ^Furthermore,
37cb0 0a 2a 2a 20 74 68 65 20 5b 64 61 74 61 5f 73 74  .** the [data_st
37cc0 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
37cd0 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 61 73 73  agma] always ass
37ce0 75 6d 65 73 20 74 68 61 74 20 61 6e 79 20 73 74  umes that any st
37cf0 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68 69  ring.** that thi
37d00 73 20 76 61 72 69 61 62 6c 65 20 70 6f 69 6e 74  s variable point
37d10 73 20 74 6f 20 69 73 20 68 65 6c 64 20 69 6e 20  s to is held in 
37d20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
37d30 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  from .** [sqlite
37d40 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68  3_malloc] and th
37d50 65 20 70 72 61 67 6d 61 20 6d 61 79 20 61 74 74  e pragma may att
37d60 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74 68 61  empt to free tha
37d70 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e  t memory.** usin
37d80 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5d  g [sqlite3_free]
37d90 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20 74  ..** Hence, if t
37da0 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 73 20  his variable is 
37db0 6d 6f 64 69 66 69 65 64 20 64 69 72 65 63 74 6c  modified directl
37dc0 79 2c 20 65 69 74 68 65 72 20 69 74 20 73 68 6f  y, either it sho
37dd0 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e  uld be.** made N
37de0 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20 70  ULL or made to p
37df0 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f  oint to memory o
37e00 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
37e10 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a  lite3_malloc].**
37e20 20 6f 72 20 65 6c 73 65 20 74 68 65 20 75 73 65   or else the use
37e30 20 6f 66 20 74 68 65 20 5b 64 61 74 61 5f 73 74   of the [data_st
37e40 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
37e50 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65 20  agma] should be 
37e60 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49  avoided..*/.SQLI
37e70 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a  TE_EXTERN char *
37e80 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 64 69 72  sqlite3_data_dir
37e90 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ectory;../*.** C
37ea0 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 46 6f  API3REF: Test Fo
37eb0 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f  r Auto-Commit Mo
37ec0 64 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  de.** KEYWORDS: 
37ed0 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65  {autocommit mode
37ee0 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  }.**.** ^The sql
37ef0 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d  ite3_get_autocom
37f00 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 65 20  mit() interface 
37f10 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
37f20 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74   or.** zero if t
37f30 68 65 20 67 69 76 65 6e 20 64 61 74 61 62 61 73  he given databas
37f40 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
37f50 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74  or is not in aut
37f60 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a  ocommit mode,.**
37f70 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20   respectively.  
37f80 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65  ^Autocommit mode
37f90 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c   is on by defaul
37fa0 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69  t..** ^Autocommi
37fb0 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c  t mode is disabl
37fc0 65 64 20 62 79 20 61 20 5b 42 45 47 49 4e 5d 20  ed by a [BEGIN] 
37fd0 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 41  statement..** ^A
37fe0 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69  utocommit mode i
37ff0 73 20 72 65 2d 65 6e 61 62 6c 65 64 20 62 79 20  s re-enabled by 
38000 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52  a [COMMIT] or [R
38010 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  OLLBACK]..**.** 
38020 49 66 20 63 65 72 74 61 69 6e 20 6b 69 6e 64 73  If certain kinds
38030 20 6f 66 20 65 72 72 6f 72 73 20 6f 63 63 75 72   of errors occur
38040 20 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e 74 20   on a statement 
38050 77 69 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73  within a multi-s
38060 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e  tatement.** tran
38070 73 61 63 74 69 6f 6e 20 28 65 72 72 6f 72 73 20  saction (errors 
38080 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54  including [SQLIT
38090 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45  E_FULL], [SQLITE
380a0 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c  _IOERR],.** [SQL
380b0 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c  ITE_NOMEM], [SQL
380c0 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b  ITE_BUSY], and [
380d0 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
380e0 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74  ]) then the.** t
380f0 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68 74  ransaction might
38100 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   be rolled back 
38110 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
38120 54 68 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a  The only way to.
38130 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77 68 65 74  ** find out whet
38140 68 65 72 20 53 51 4c 69 74 65 20 61 75 74 6f 6d  her SQLite autom
38150 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
38160 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63  back the transac
38170 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e  tion after.** an
38180 20 65 72 72 6f 72 20 69 73 20 74 6f 20 75 73 65   error is to use
38190 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a   this function..
381a0 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72  **.** If another
381b0 20 74 68 72 65 61 64 20 63 68 61 6e 67 65 73 20   thread changes 
381c0 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73  the autocommit s
381d0 74 61 74 75 73 20 6f 66 20 74 68 65 20 64 61 74  tatus of the dat
381e0 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
381f0 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 20 72  ion while this r
38200 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e  outine is runnin
38210 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 74 75  g, then the retu
38220 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 75  rn value.** is u
38230 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74  ndefined..*/.int
38240 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74   sqlite3_get_aut
38250 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a  ocommit(sqlite3*
38260 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
38270 45 46 3a 20 46 69 6e 64 20 54 68 65 20 44 61 74  EF: Find The Dat
38280 61 62 61 73 65 20 48 61 6e 64 6c 65 20 4f 66 20  abase Handle Of 
38290 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
382a0 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ment.**.** ^The 
382b0 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c  sqlite3_db_handl
382c0 65 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  e interface retu
382d0 72 6e 73 20 74 68 65 20 5b 64 61 74 61 62 61 73  rns the [databas
382e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
382f0 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 63 68  ndle.** to which
38300 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
38310 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e  tement] belongs.
38320 20 20 5e 54 68 65 20 5b 64 61 74 61 62 61 73 65    ^The [database
38330 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20   connection].** 
38340 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
38350 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 73  te3_db_handle is
38360 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62   the same [datab
38370 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a  ase connection].
38380 2a 2a 20 74 68 61 74 20 77 61 73 20 74 68 65 20  ** that was the 
38390 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a  first argument.*
383a0 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  * to the [sqlite
383b0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
383c0 63 61 6c 6c 20 28 6f 72 20 69 74 73 20 76 61 72  call (or its var
383d0 69 61 6e 74 73 29 20 74 68 61 74 20 77 61 73 20  iants) that was 
383e0 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72 65 61 74  used to.** creat
383f0 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  e the statement 
38400 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c 61  in the first pla
38410 63 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a  ce..*/.sqlite3 *
38420 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c  sqlite3_db_handl
38430 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  e(sqlite3_stmt*)
38440 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
38450 46 3a 20 52 65 74 75 72 6e 20 54 68 65 20 46 69  F: Return The Fi
38460 6c 65 6e 61 6d 65 20 46 6f 72 20 41 20 44 61 74  lename For A Dat
38470 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
38480 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
38490 74 65 33 5f 64 62 5f 66 69 6c 65 6e 61 6d 65 28  te3_db_filename(
384a0 44 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72  D,N) interface r
384b0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
384c0 20 74 6f 20 61 20 66 69 6c 65 6e 61 6d 65 0a 2a   to a filename.*
384d0 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
384e0 68 20 64 61 74 61 62 61 73 65 20 4e 20 6f 66 20  h database N of 
384f0 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 5e  connection D.  ^
38500 54 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73  The main databas
38510 65 20 66 69 6c 65 0a 2a 2a 20 68 61 73 20 74 68  e file.** has th
38520 65 20 6e 61 6d 65 20 22 6d 61 69 6e 22 2e 20 20  e name "main".  
38530 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 61  If there is no a
38540 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
38550 20 4e 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61   N on the databa
38560 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
38570 20 44 2c 20 6f 72 20 69 66 20 64 61 74 61 62 61   D, or if databa
38580 73 65 20 4e 20 69 73 20 61 20 74 65 6d 70 6f 72  se N is a tempor
38590 61 72 79 20 6f 72 20 69 6e 2d 6d 65 6d 6f 72 79  ary or in-memory
385a0 20 64 61 74 61 62 61 73 65 2c 20 74 68 65 6e 0a   database, then.
385b0 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
385c0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
385d0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 6c 65 6e 61  *.** ^The filena
385e0 6d 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  me returned by t
385f0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  his function is 
38600 74 68 65 20 6f 75 74 70 75 74 20 6f 66 20 74 68  the output of th
38610 65 0a 2a 2a 20 78 46 75 6c 6c 50 61 74 68 6e 61  e.** xFullPathna
38620 6d 65 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  me method of the
38630 20 5b 56 46 53 5d 2e 20 20 5e 49 6e 20 6f 74 68   [VFS].  ^In oth
38640 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 66 69  er words, the fi
38650 6c 65 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 62  lename.** will b
38660 65 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61  e an absolute pa
38670 74 68 6e 61 6d 65 2c 20 65 76 65 6e 20 69 66 20  thname, even if 
38680 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 75 73 65  the filename use
38690 64 0a 2a 2a 20 74 6f 20 6f 70 65 6e 20 74 68 65  d.** to open the
386a0 20 64 61 74 61 62 61 73 65 20 6f 72 69 67 69 6e   database origin
386b0 61 6c 6c 79 20 77 61 73 20 61 20 55 52 49 20 6f  ally was a URI o
386c0 72 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 6e  r relative pathn
386d0 61 6d 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ame..*/.const ch
386e0 61 72 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 66  ar *sqlite3_db_f
386f0 69 6c 65 6e 61 6d 65 28 73 71 6c 69 74 65 33 20  ilename(sqlite3 
38700 2a 64 62 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  *db, const char 
38710 2a 7a 44 62 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a  *zDbName);../*.*
38720 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65  * CAPI3REF: Dete
38730 72 6d 69 6e 65 20 69 66 20 61 20 64 61 74 61 62  rmine if a datab
38740 61 73 65 20 69 73 20 72 65 61 64 2d 6f 6e 6c 79  ase is read-only
38750 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
38760 74 65 33 5f 64 62 5f 72 65 61 64 6f 6e 6c 79 28  te3_db_readonly(
38770 44 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72  D,N) interface r
38780 65 74 75 72 6e 73 20 31 20 69 66 20 74 68 65 20  eturns 1 if the 
38790 64 61 74 61 62 61 73 65 20 4e 0a 2a 2a 20 6f 66  database N.** of
387a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 20 69 73   connection D is
387b0 20 72 65 61 64 2d 6f 6e 6c 79 2c 20 30 20 69 66   read-only, 0 if
387c0 20 69 74 20 69 73 20 72 65 61 64 2f 77 72 69 74   it is read/writ
387d0 65 2c 20 6f 72 20 2d 31 20 69 66 20 4e 20 69 73  e, or -1 if N is
387e0 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 6e 61 6d 65   not.** the name
387f0 20 6f 66 20 61 20 64 61 74 61 62 61 73 65 20 6f   of a database o
38800 6e 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a  n connection D..
38810 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64  */.int sqlite3_d
38820 62 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74  b_readonly(sqlit
38830 65 33 20 2a 64 62 2c 20 63 6f 6e 73 74 20 63 68  e3 *db, const ch
38840 61 72 20 2a 7a 44 62 4e 61 6d 65 29 3b 0a 0a 2f  ar *zDbName);../
38850 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
38860 69 6e 64 20 74 68 65 20 6e 65 78 74 20 70 72 65  ind the ne