/ Hex Artifact Content
Login

Artifact 49c501f66e0d6591ebe7588edddf0c4b06c8b9e9:


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 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
2ad0: 4b 5d 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71  K] if.** the [sq
2ae0: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73  lite3] object is
2af0: 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65   successfully de
2b00: 73 74 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20  stroyed and all 
2b10: 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65  associated.** re
2b20: 73 6f 75 72 63 65 73 20 61 72 65 20 64 65 61 6c  sources are deal
2b30: 6c 6f 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  located..**.** ^
2b40: 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
2b50: 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73  connection is as
2b60: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 75 6e  sociated with un
2b70: 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72  finalized prepar
2b80: 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73  ed.** statements
2b90: 20 6f 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73   or unfinished s
2ba0: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62  qlite3_backup ob
2bb0: 6a 65 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74  jects then sqlit
2bc0: 65 33 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69  e3_close().** wi
2bd0: 6c 6c 20 6c 65 61 76 65 20 74 68 65 20 64 61 74  ll leave the dat
2be0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2bf0: 20 6f 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e   open and return
2c00: 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a   [SQLITE_BUSY]..
2c10: 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63  ** ^If sqlite3_c
2c20: 6c 6f 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c  lose_v2() is cal
2c30: 6c 65 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c  led with unfinal
2c40: 69 7a 65 64 20 70 72 65 70 61 72 65 64 20 73 74  ized prepared st
2c50: 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 2f  atements.** and/
2c60: 6f 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71  or unfinished sq
2c70: 6c 69 74 65 33 5f 62 61 63 6b 75 70 73 2c 20 74  lite3_backups, t
2c80: 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
2c90: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 63 6f   connection beco
2ca0: 6d 65 73 0a 2a 2a 20 61 6e 20 75 6e 75 73 61 62  mes.** an unusab
2cb0: 6c 65 20 22 7a 6f 6d 62 69 65 22 20 77 68 69 63  le "zombie" whic
2cc0: 68 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63  h will automatic
2cd0: 61 6c 6c 79 20 62 65 20 64 65 61 6c 6c 6f 63 61  ally be dealloca
2ce0: 74 65 64 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20  ted when the.** 
2cf0: 6c 61 73 74 20 70 72 65 70 61 72 65 64 20 73 74  last prepared st
2d00: 61 74 65 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c  atement is final
2d10: 69 7a 65 64 20 6f 72 20 74 68 65 20 6c 61 73 74  ized or the last
2d20: 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20   sqlite3_backup 
2d30: 69 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 2e 20  is.** finished. 
2d40: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f   The sqlite3_clo
2d50: 73 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  se_v2() interfac
2d60: 65 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f  e is intended fo
2d70: 72 20 75 73 65 20 77 69 74 68 0a 2a 2a 20 68 6f  r use with.** ho
2d80: 73 74 20 6c 61 6e 67 75 61 67 65 73 20 74 68 61  st languages tha
2d90: 74 20 61 72 65 20 67 61 72 62 61 67 65 20 63 6f  t are garbage co
2da0: 6c 6c 65 63 74 65 64 2c 20 61 6e 64 20 77 68 65  llected, and whe
2db0: 72 65 20 74 68 65 20 6f 72 64 65 72 20 69 6e 20  re the order in 
2dc0: 77 68 69 63 68 0a 2a 2a 20 64 65 73 74 72 75 63  which.** destruc
2dd0: 74 6f 72 73 20 61 72 65 20 63 61 6c 6c 65 64 20  tors are called 
2de0: 69 73 20 61 72 62 69 74 72 61 72 79 2e 0a 2a 2a  is arbitrary..**
2df0: 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
2e00: 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65 33   should [sqlite3
2e10: 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61  _finalize | fina
2e20: 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70 61  lize] all [prepa
2e30: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c  red statements],
2e40: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
2e50: 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f 73 65 5d  b_close | close]
2e60: 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c   all [BLOB handl
2e70: 65 73 5d 2c 20 61 6e 64 20 0a 2a 2a 20 5b 73 71  es], and .** [sq
2e80: 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e  lite3_backup_fin
2e90: 69 73 68 20 7c 20 66 69 6e 69 73 68 5d 20 61 6c  ish | finish] al
2ea0: 6c 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  l [sqlite3_backu
2eb0: 70 5d 20 6f 62 6a 65 63 74 73 20 61 73 73 6f 63  p] objects assoc
2ec0: 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68  iated.** with th
2ed0: 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
2ee0: 63 74 20 70 72 69 6f 72 20 74 6f 20 61 74 74 65  ct prior to atte
2ef0: 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20  mpting to close 
2f00: 74 68 65 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66  the object.  ^If
2f10: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  .** sqlite3_clos
2f20: 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64  e_v2() is called
2f30: 20 6f 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20   on a [database 
2f40: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74  connection] that
2f50: 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75   still has.** ou
2f60: 74 73 74 61 6e 64 69 6e 67 20 5b 70 72 65 70 61  tstanding [prepa
2f70: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c  red statements],
2f80: 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c   [BLOB handles],
2f90: 20 61 6e 64 2f 6f 72 0a 2a 2a 20 5b 73 71 6c 69   and/or.** [sqli
2fa0: 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65  te3_backup] obje
2fb0: 63 74 73 20 74 68 65 6e 20 69 74 20 72 65 74 75  cts then it retu
2fc0: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  rns [SQLITE_OK] 
2fd0: 61 6e 64 20 74 68 65 20 64 65 61 6c 6c 6f 63 61  and the dealloca
2fe0: 74 69 6f 6e 0a 2a 2a 20 6f 66 20 72 65 73 6f 75  tion.** of resou
2ff0: 72 63 65 73 20 69 73 20 64 65 66 65 72 72 65 64  rces is deferred
3000: 20 75 6e 74 69 6c 20 61 6c 6c 20 5b 70 72 65 70   until all [prep
3010: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
3020: 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d  , [BLOB handles]
3030: 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ,.** and [sqlite
3040: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
3050: 73 20 61 72 65 20 61 6c 73 6f 20 64 65 73 74 72  s are also destr
3060: 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  oyed..**.** ^If 
3070: 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  an [sqlite3] obj
3080: 65 63 74 20 69 73 20 64 65 73 74 72 6f 79 65 64  ect is destroyed
3090: 20 77 68 69 6c 65 20 61 20 74 72 61 6e 73 61 63   while a transac
30a0: 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a  tion is open,.**
30b0: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
30c0: 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   is automaticall
30d0: 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a  y rolled back..*
30e0: 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61 72 61 6d  *.** The C param
30f0: 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
3100: 5f 63 6c 6f 73 65 28 43 29 5d 20 61 6e 64 20 5b  _close(C)] and [
3110: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
3120: 28 43 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20  (C)].** must be 
3130: 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a  either a NULL.**
3140: 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b   pointer or an [
3150: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
3160: 70 6f 69 6e 74 65 72 20 6f 62 74 61 69 6e 65 64  pointer obtained
3170: 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
3180: 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
3190: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f  te3_open16()], o
31a0: 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r.** [sqlite3_op
31b0: 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f  en_v2()], and no
31c0: 74 20 70 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f  t previously clo
31d0: 73 65 64 2e 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  sed..** ^Calling
31e0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
31f0: 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73   or sqlite3_clos
3200: 65 5f 76 32 28 29 20 77 69 74 68 20 61 20 4e 55  e_v2() with a NU
3210: 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 61 72  LL pointer.** ar
3220: 67 75 6d 65 6e 74 20 69 73 20 61 20 68 61 72 6d  gument is a harm
3230: 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 69  less no-op..*/.i
3240: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nt sqlite3_close
3250: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 69 6e 74 20  (sqlite3*);.int 
3260: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
3270: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
3280: 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72 20  ** The type for 
3290: 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
32a0: 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20  ion..** This is 
32b0: 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70 72 65  legacy and depre
32c0: 63 61 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e  cated.  It is in
32d0: 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f  cluded for histo
32e0: 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69  rical.** compati
32f0: 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f  bility and is no
3300: 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f  t documented..*/
3310: 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73  .typedef int (*s
3320: 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29  qlite3_callback)
3330: 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a  (void*,int,char*
3340: 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a  *, char**);../*.
3350: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65  ** CAPI3REF: One
3360: 2d 53 74 65 70 20 51 75 65 72 79 20 45 78 65 63  -Step Query Exec
3370: 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a  ution Interface.
3380: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
3390: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61  3_exec() interfa
33a0: 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e 69 65  ce is a convenie
33b0: 6e 63 65 20 77 72 61 70 70 65 72 20 61 72 6f 75  nce wrapper arou
33c0: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  nd.** [sqlite3_p
33d0: 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73  repare_v2()], [s
33e0: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20  qlite3_step()], 
33f0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  and [sqlite3_fin
3400: 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74 68 61  alize()],.** tha
3410: 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70 70 6c  t allows an appl
3420: 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e 20 6d  ication to run m
3430: 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d 65 6e  ultiple statemen
3440: 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77 69 74  ts of SQL.** wit
3450: 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f 20 75  hout having to u
3460: 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f  se a lot of C co
3470: 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  de. .**.** ^The 
3480: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3490: 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20 7a 65  nterface runs ze
34a0: 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46 2d 38  ro or more UTF-8
34b0: 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73 65 6d   encoded,.** sem
34c0: 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 20  icolon-separate 
34d0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70  SQL statements p
34e0: 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73 20 32  assed into its 2
34f0: 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a 2a 20  nd argument,.** 
3500: 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74 20 6f  in the context o
3510: 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  f the [database 
3520: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61 73 73  connection] pass
3530: 65 64 20 69 6e 20 61 73 20 69 74 73 20 31 73 74  ed in as its 1st
3540: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e  .** argument.  ^
3550: 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
3560: 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68 65 20  function of the 
3570: 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  3rd argument to.
3580: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
3590: 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74  ) is not NULL, t
35a0: 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f 6b 65  hen it is invoke
35b0: 64 20 66 6f 72 20 65 61 63 68 20 72 65 73 75 6c  d for each resul
35c0: 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e 67 20  t row.** coming 
35d0: 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61 6c 75  out of the evalu
35e0: 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  ated SQL stateme
35f0: 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68 20 61  nts.  ^The 4th a
3600: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71  rgument to.** sq
3610: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3620: 72 65 6c 61 79 65 64 20 74 68 72 6f 75 67 68 20  relayed through 
3630: 74 6f 20 74 68 65 20 31 73 74 20 61 72 67 75 6d  to the 1st argum
3640: 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20 63  ent of each.** c
3650: 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63 61 74 69  allback invocati
3660: 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c  on.  ^If the cal
3670: 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72 20 74 6f  lback pointer to
3680: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3690: 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  ** is NULL, then
36a0: 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20 69 73 20   no callback is 
36b0: 65 76 65 72 20 69 6e 76 6f 6b 65 64 20 61 6e 64  ever invoked and
36c0: 20 72 65 73 75 6c 74 20 72 6f 77 73 20 61 72 65   result rows are
36d0: 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a  .** ignored..**.
36e0: 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f 72 20  ** ^If an error 
36f0: 6f 63 63 75 72 73 20 77 68 69 6c 65 20 65 76 61  occurs while eva
3700: 6c 75 61 74 69 6e 67 20 74 68 65 20 53 51 4c 20  luating the SQL 
3710: 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65  statements passe
3720: 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  d into.** sqlite
3730: 33 5f 65 78 65 63 28 29 2c 20 74 68 65 6e 20 65  3_exec(), then e
3740: 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20  xecution of the 
3750: 63 75 72 72 65 6e 74 20 73 74 61 74 65 6d 65 6e  current statemen
3760: 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a 2a 20 73  t stops and.** s
3770: 75 62 73 65 71 75 65 6e 74 20 73 74 61 74 65 6d  ubsequent statem
3780: 65 6e 74 73 20 61 72 65 20 73 6b 69 70 70 65 64  ents are skipped
3790: 2e 20 20 5e 49 66 20 74 68 65 20 35 74 68 20 70  .  ^If the 5th p
37a0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
37b0: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73  te3_exec().** is
37c0: 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 61   not NULL then a
37d0: 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  ny error message
37e0: 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   is written into
37f0: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
3800: 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
3810: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20  3_malloc()] and 
3820: 70 61 73 73 65 64 20 62 61 63 6b 20 74 68 72 6f  passed back thro
3830: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61  ugh the 5th para
3840: 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20 61 76 6f  meter..** To avo
3850: 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 73 2c  id memory leaks,
3860: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
3870: 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b 65 20 5b   should invoke [
3880: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 0a  sqlite3_free()].
3890: 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d 65 73 73  ** on error mess
38a0: 61 67 65 20 73 74 72 69 6e 67 73 20 72 65 74 75  age strings retu
38b0: 72 6e 65 64 20 74 68 72 6f 75 67 68 20 74 68 65  rned through the
38c0: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f   5th parameter o
38d0: 66 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  f.** of sqlite3_
38e0: 65 78 65 63 28 29 20 61 66 74 65 72 20 74 68 65  exec() after the
38f0: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
3900: 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e 67  tring is no long
3910: 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e 49  er needed..** ^I
3920: 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  f the 5th parame
3930: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3940: 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c  xec() is not NUL
3950: 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f 72 73 0a  L and no errors.
3960: 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65 6e 20 73  ** occur, then s
3970: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 73 65  qlite3_exec() se
3980: 74 73 20 74 68 65 20 70 6f 69 6e 74 65 72 20 69  ts the pointer i
3990: 6e 20 69 74 73 20 35 74 68 20 70 61 72 61 6d 65  n its 5th parame
39a0: 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62  ter to.** NULL b
39b0: 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e  efore returning.
39c0: 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 73 71  .**.** ^If an sq
39d0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
39e0: 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
39f0: 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73 71 6c 69  n-zero, the sqli
3a00: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 72 6f  te3_exec().** ro
3a10: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 53 51  utine returns SQ
3a20: 4c 49 54 45 5f 41 42 4f 52 54 20 77 69 74 68 6f  LITE_ABORT witho
3a30: 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  ut invoking the 
3a40: 63 61 6c 6c 62 61 63 6b 20 61 67 61 69 6e 20 61  callback again a
3a50: 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74 20 72 75  nd.** without ru
3a60: 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62 73 65 71  nning any subseq
3a70: 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65  uent SQL stateme
3a80: 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
3a90: 32 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  2nd argument to 
3aa0: 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  the sqlite3_exec
3ab0: 28 29 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  () callback func
3ac0: 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a 2a 20 6e  tion is the.** n
3ad0: 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
3ae0: 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 2e 20   in the result. 
3af0: 20 5e 54 68 65 20 33 72 64 20 61 72 67 75 6d 65   ^The 3rd argume
3b00: 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
3b10: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63 61 6c 6c  3_exec().** call
3b20: 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79  back is an array
3b30: 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20   of pointers to 
3b40: 73 74 72 69 6e 67 73 20 6f 62 74 61 69 6e 65 64  strings obtained
3b50: 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b   as if from.** [
3b60: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
3b70: 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66 6f 72 20  ext()], one for 
3b80: 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49  each column.  ^I
3b90: 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20 6f 66 20  f an element of 
3ba0: 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20  a.** result row 
3bb0: 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65  is NULL then the
3bc0: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 73   corresponding s
3bd0: 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 66 6f  tring pointer fo
3be0: 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33  r the.** sqlite3
3bf0: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3c00: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
3c10: 65 72 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72  er.  ^The 4th ar
3c20: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a  gument to the.**
3c30: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3c40: 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61  callback is an a
3c50: 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
3c60: 20 74 6f 20 73 74 72 69 6e 67 73 20 77 68 65 72   to strings wher
3c70: 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74 72 79 20  e each.** entry 
3c80: 72 65 70 72 65 73 65 6e 74 73 20 74 68 65 20 6e  represents the n
3c90: 61 6d 65 20 6f 66 20 63 6f 72 72 65 73 70 6f 6e  ame of correspon
3ca0: 64 69 6e 67 20 72 65 73 75 6c 74 20 63 6f 6c 75  ding result colu
3cb0: 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65 64 0a 2a  mn as obtained.*
3cc0: 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
3cd0: 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a  column_name()]..
3ce0: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 32 6e  **.** ^If the 2n
3cf0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
3d00: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3d10: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
3d20: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
3d30: 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
3d40: 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74  , or a pointer t
3d50: 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c  hat contains onl
3d60: 79 20 77 68 69 74 65 73 70 61 63 65 20 61 6e 64  y whitespace and
3d70: 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d  /or .** SQL comm
3d80: 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51  ents, then no SQ
3d90: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
3da0: 20 65 76 61 6c 75 61 74 65 64 20 61 6e 64 20 74   evaluated and t
3db0: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69  he database.** i
3dc0: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a  s not changed..*
3dd0: 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74 69 6f 6e  *.** Restriction
3de0: 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
3df0: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63   <li> The applic
3e00: 61 74 69 6f 6e 20 6d 75 73 74 20 69 6e 73 75 72  ation must insur
3e10: 65 20 74 68 61 74 20 74 68 65 20 31 73 74 20 70  e that the 1st p
3e20: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
3e30: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 20 20  te3_exec().**   
3e40: 20 20 20 69 73 20 61 20 76 61 6c 69 64 20 61 6e     is a valid an
3e50: 64 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65  d open [database
3e60: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
3e70: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63   <li> The applic
3e80: 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 63  ation must not c
3e90: 6c 6f 73 65 20 74 68 65 20 5b 64 61 74 61 62 61  lose the [databa
3ea0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73  se connection] s
3eb0: 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20  pecified by.**  
3ec0: 20 20 20 20 74 68 65 20 31 73 74 20 70 61 72 61      the 1st para
3ed0: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
3ee0: 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71  _exec() while sq
3ef0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3f00: 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e  running..** <li>
3f10: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
3f20: 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66 79   must not modify
3f30: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
3f40: 6e 74 20 74 65 78 74 20 70 61 73 73 65 64 20 69  nt text passed i
3f50: 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65 20  nto.**      the 
3f60: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66  2nd parameter of
3f70: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3f80: 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78  while sqlite3_ex
3f90: 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e  ec() is running.
3fa0: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e 74  .** </ul>.*/.int
3fb0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20   sqlite3_exec(. 
3fc0: 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20   sqlite3*,      
3fd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fe0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41              /* A
3ff0: 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20  n open database 
4000: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
4010: 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20  *sql,           
4020: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4030: 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61  /* SQL to be eva
4040: 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20  luated */.  int 
4050: 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64  (*callback)(void
4060: 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61  *,int,char**,cha
4070: 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61  r**),  /* Callba
4080: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20  ck function */. 
4090: 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20   void *,        
40a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40b0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 31              /* 1
40c0: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63  st argument to c
40d0: 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61  allback */.  cha
40e0: 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20  r **errmsg      
40f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4100: 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72          /* Error
4110: 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72   msg written her
4120: 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.);../*.** C
4130: 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20  API3REF: Result 
4140: 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  Codes.** KEYWORD
4150: 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 20  S: {result code 
4160: 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a  definitions}.**.
4170: 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66  ** Many SQLite f
4180: 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
4190: 61 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c  an integer resul
41a0: 74 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20  t code from the 
41b0: 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72  set shown.** her
41c0: 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e  e in order to in
41d0: 64 69 63 61 74 65 20 73 75 63 63 65 73 73 20 6f  dicate success o
41e0: 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a  r failure..**.**
41f0: 20 4e 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73   New error codes
4200: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
4210: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
4220: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
4230: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 65 78 74  * See also: [ext
4240: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
4250: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 5d 0a 2a  e definitions].*
4260: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4270: 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20  _OK           0 
4280: 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20    /* Successful 
4290: 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67  result */./* beg
42a0: 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d  inning-of-error-
42b0: 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65  codes */.#define
42c0: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20   SQLITE_ERROR   
42d0: 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20       1   /* SQL 
42e0: 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67  error or missing
42f0: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65   database */.#de
4300: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
4310: 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20  RNAL     2   /* 
4320: 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65  Internal logic e
4330: 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a  rror in SQLite *
4340: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4350: 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20  _PERM         3 
4360: 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d    /* Access perm
4370: 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  ission denied */
4380: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4390: 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20  ABORT        4  
43a0: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75   /* Callback rou
43b0: 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61  tine requested a
43c0: 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69  n abort */.#defi
43d0: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20  ne SQLITE_BUSY  
43e0: 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68         5   /* Th
43f0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
4400: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
4410: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
4420: 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20  ED       6   /* 
4430: 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64  A table in the d
4440: 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65  atabase is locke
4450: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4460: 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ITE_NOMEM       
4470: 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63   7   /* A malloc
4480: 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65  () failed */.#de
4490: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
44a0: 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20  ONLY     8   /* 
44b0: 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65  Attempt to write
44c0: 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61   a readonly data
44d0: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  base */.#define 
44e0: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
44f0: 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61      9   /* Opera
4500: 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20  tion terminated 
4510: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  by sqlite3_inter
4520: 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65  rupt()*/.#define
4530: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20   SQLITE_IOERR   
4540: 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65      10   /* Some
4550: 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f   kind of disk I/
4560: 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64  O error occurred
4570: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4580: 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31  TE_CORRUPT     1
4590: 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  1   /* The datab
45a0: 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69  ase disk image i
45b0: 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23  s malformed */.#
45c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
45d0: 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f  TFOUND    12   /
45e0: 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65  * Unknown opcode
45f0: 20 69 6e 20 73 71 6c 69 74 65 33 5f 66 69 6c 65   in sqlite3_file
4600: 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64  _control() */.#d
4610: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c  efine SQLITE_FUL
4620: 4c 20 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a  L        13   /*
4630: 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65   Insertion faile
4640: 64 20 62 65 63 61 75 73 65 20 64 61 74 61 62 61  d because databa
4650: 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64  se is full */.#d
4660: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
4670: 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a  TOPEN    14   /*
4680: 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20   Unable to open 
4690: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
46a0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
46b0: 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20  ITE_PROTOCOL    
46c0: 31 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  15   /* Database
46d0: 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65   lock protocol e
46e0: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
46f0: 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20  SQLITE_EMPTY    
4700: 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62     16   /* Datab
4710: 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a  ase is empty */.
4720: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
4730: 43 48 45 4d 41 20 20 20 20 20 20 31 37 20 20 20  CHEMA      17   
4740: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20  /* The database 
4750: 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a  schema changed *
4760: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4770: 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20  _TOOBIG      18 
4780: 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42    /* String or B
4790: 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a 65  LOB exceeds size
47a0: 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e   limit */.#defin
47b0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
47c0: 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f  INT  19   /* Abo
47d0: 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72  rt due to constr
47e0: 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a  aint violation *
47f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4800: 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20  _MISMATCH    20 
4810: 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d    /* Data type m
4820: 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69  ismatch */.#defi
4830: 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  ne SQLITE_MISUSE
4840: 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69        21   /* Li
4850: 62 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72  brary used incor
4860: 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  rectly */.#defin
4870: 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20  e SQLITE_NOLFS  
4880: 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65       22   /* Use
4890: 73 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f  s OS features no
48a0: 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68  t supported on h
48b0: 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ost */.#define S
48c0: 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20  QLITE_AUTH      
48d0: 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72    23   /* Author
48e0: 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a  ization denied *
48f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4900: 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20  _FORMAT      24 
4910: 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64    /* Auxiliary d
4920: 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65  atabase format e
4930: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
4940: 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20  SQLITE_RANGE    
4950: 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70     25   /* 2nd p
4960: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
4970: 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20  te3_bind out of 
4980: 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65  range */.#define
4990: 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20   SQLITE_NOTADB  
49a0: 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65      26   /* File
49b0: 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20   opened that is 
49c0: 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
49d0: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
49e0: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 20 20 20  QLITE_NOTICE    
49f0: 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66 69    27   /* Notifi
4a00: 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71 6c  cations from sql
4a10: 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64  ite3_log() */.#d
4a20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52  efine SQLITE_WAR
4a30: 4e 49 4e 47 20 20 20 20 20 32 38 20 20 20 2f 2a  NING     28   /*
4a40: 20 57 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20 73   Warnings from s
4a50: 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a  qlite3_log() */.
4a60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
4a70: 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20  OW         100  
4a80: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  /* sqlite3_step(
4a90: 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f  ) has another ro
4aa0: 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69  w ready */.#defi
4ab0: 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20  ne SQLITE_DONE  
4ac0: 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71        101  /* sq
4ad0: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
4ae0: 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
4af0: 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66  ing */./* end-of
4b00: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
4b10: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
4b20: 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74   Extended Result
4b30: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
4b40: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65  DS: {extended re
4b50: 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69  sult code defini
4b60: 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  tions}.**.** In 
4b70: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
4b80: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
4b90: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
4ba0: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30 20  eturn one of 30 
4bb0: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73 75  integer.** [resu
4bc0: 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65  lt codes].  Howe
4bd0: 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20  ver, experience 
4be0: 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d  has shown that m
4bf0: 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20  any of.** these 
4c00: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4c10: 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69   too coarse-grai
4c20: 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f  ned.  They do no
4c30: 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20  t provide as.** 
4c40: 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  much information
4c50: 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20   about problems 
4c60: 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d  as programmers m
4c70: 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61  ight like.  In a
4c80: 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61  n effort to.** a
4c90: 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77  ddress this, new
4ca0: 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  er versions of S
4cb0: 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33  QLite (version 3
4cc0: 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 20  .3.8 and later) 
4cd0: 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f  include.** suppo
4ce0: 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  rt for additiona
4cf0: 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74  l result codes t
4d00: 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65  hat provide more
4d10: 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d   detailed inform
4d20: 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65  ation.** about e
4d30: 72 72 6f 72 73 2e 20 54 68 65 73 65 20 5b 65 78  rrors. These [ex
4d40: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
4d50: 64 65 73 5d 20 61 72 65 20 65 6e 61 62 6c 65 64  des] are enabled
4d60: 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20   or disabled.** 
4d70: 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73  on a per databas
4d80: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  e connection bas
4d90: 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  is using the.** 
4da0: 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65  [sqlite3_extende
4db0: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
4dc0: 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74 68 65 20  ] API.  Or, the 
4dd0: 65 78 74 65 6e 64 65 64 20 63 6f 64 65 20 66 6f  extended code fo
4de0: 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72 65  r.** the most re
4df0: 63 65 6e 74 20 65 72 72 6f 72 20 63 61 6e 20 62  cent error can b
4e00: 65 20 6f 62 74 61 69 6e 65 64 20 75 73 69 6e 67  e obtained using
4e10: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74  .** [sqlite3_ext
4e20: 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 5d  ended_errcode()]
4e30: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
4e40: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20  ITE_IOERR_READ  
4e50: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4e60: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c  ITE_IOERR | (1<<
4e70: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4e80: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
4e90: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  EAD        (SQLI
4ea0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38  TE_IOERR | (2<<8
4eb0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4ec0: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20  E_IOERR_WRITE   
4ed0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
4ee0: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29  E_IOERR | (3<<8)
4ef0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4f00: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20  _IOERR_FSYNC    
4f10: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4f20: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29  _IOERR | (4<<8))
4f30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4f40: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20  IOERR_DIR_FSYNC 
4f50: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4f60: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a  IOERR | (5<<8)).
4f70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4f80: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20  OERR_TRUNCATE   
4f90: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4fa0: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23  OERR | (6<<8)).#
4fb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4fc0: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20  ERR_FSTAT       
4fd0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4fe0: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  ERR | (7<<8)).#d
4ff0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5000: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  RR_UNLOCK       
5010: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5020: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  RR | (8<<8)).#de
5030: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5040: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_RDLOCK        
5050: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5060: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  R | (9<<8)).#def
5070: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5080: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
5090: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
50a0: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66   | (10<<8)).#def
50b0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
50c0: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20  _BLOCKED        
50d0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
50e0: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66   | (11<<8)).#def
50f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5100: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20  _NOMEM          
5110: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5120: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66   | (12<<8)).#def
5130: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5140: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20  _ACCESS         
5150: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5160: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66   | (13<<8)).#def
5170: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5180: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f  _CHECKRESERVEDLO
5190: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52  CK (SQLITE_IOERR
51a0: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66   | (14<<8)).#def
51b0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
51c0: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  _LOCK           
51d0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
51e0: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66   | (15<<8)).#def
51f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5200: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20  _CLOSE          
5210: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5220: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66   | (16<<8)).#def
5230: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5240: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20  _DIR_CLOSE      
5250: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5260: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66   | (17<<8)).#def
5270: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5280: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20  _SHMOPEN        
5290: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
52a0: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66   | (18<<8)).#def
52b0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
52c0: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20  _SHMSIZE        
52d0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
52e0: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66   | (19<<8)).#def
52f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5300: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20  _SHMLOCK        
5310: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5320: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66   | (20<<8)).#def
5330: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5340: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20  _SHMMAP         
5350: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5360: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66   | (21<<8)).#def
5370: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5380: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20  _SEEK           
5390: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
53a0: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66   | (22<<8)).#def
53b0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
53c0: 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20  _DELETE_NOENT   
53d0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
53e0: 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66   | (23<<8)).#def
53f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5400: 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20  _MMAP           
5410: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5420: 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66   | (24<<8)).#def
5430: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5440: 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20  _GETTEMPPATH    
5450: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5460: 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66   | (25<<8)).#def
5470: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5480: 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20  _CONVPATH       
5490: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
54a0: 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66   | (26<<8)).#def
54b0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
54c0: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  D_SHAREDCACHE   
54d0: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
54e0: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65  D |  (1<<8)).#de
54f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
5500: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
5510: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
5520: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64     |  (1<<8)).#d
5530: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
5540: 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20  Y_SNAPSHOT      
5550: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
5560: 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23  Y   |  (2<<8)).#
5570: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
5580: 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52  NTOPEN_NOTEMPDIR
5590: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
55a0: 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29  NTOPEN | (1<<8))
55b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
55c0: 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20  CANTOPEN_ISDIR  
55d0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
55e0: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38  CANTOPEN | (2<<8
55f0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5600: 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50  E_CANTOPEN_FULLP
5610: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54  ATH       (SQLIT
5620: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c  E_CANTOPEN | (3<
5630: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5640: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e  ITE_CANTOPEN_CON
5650: 56 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  VPATH       (SQL
5660: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
5670: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
5680: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54  QLITE_CORRUPT_VT
5690: 41 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53  AB            (S
56a0: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20  QLITE_CORRUPT | 
56b0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
56c0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
56d0: 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28  RECOVERY       (
56e0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
56f0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5700: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
5710: 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20  Y_CANTLOCK      
5720: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
5730: 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  Y | (2<<8)).#def
5740: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
5750: 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20  NLY_ROLLBACK    
5760: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
5770: 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  NLY | (3<<8)).#d
5780: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
5790: 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20  DONLY_DBMOVED   
57a0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
57b0: 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a  DONLY | (4<<8)).
57c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
57d0: 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20  BORT_ROLLBACK   
57e0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41         (SQLITE_A
57f0: 42 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23  BORT | (2<<8)).#
5800: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5810: 4e 53 54 52 41 49 4e 54 5f 43 48 45 43 4b 20 20  NSTRAINT_CHECK  
5820: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5830: 4e 53 54 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38  NSTRAINT | (1<<8
5840: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5850: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d  E_CONSTRAINT_COM
5860: 4d 49 54 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54  MITHOOK   (SQLIT
5870: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5880: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
5890: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
58a0: 5f 46 4f 52 45 49 47 4e 4b 45 59 20 20 20 28 53  _FOREIGNKEY   (S
58b0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
58c0: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
58d0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
58e0: 41 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20  AINT_FUNCTION   
58f0: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5900: 41 49 4e 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23  AINT | (4<<8)).#
5910: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5920: 4e 53 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c  NSTRAINT_NOTNULL
5930: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5940: 4e 53 54 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38  NSTRAINT | (5<<8
5950: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5960: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49  E_CONSTRAINT_PRI
5970: 4d 41 52 59 4b 45 59 20 20 20 28 53 51 4c 49 54  MARYKEY   (SQLIT
5980: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5990: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
59a0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
59b0: 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 28 53  _TRIGGER      (S
59c0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
59d0: 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69   | (7<<8)).#defi
59e0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
59f0: 41 49 4e 54 5f 55 4e 49 51 55 45 20 20 20 20 20  AINT_UNIQUE     
5a00: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5a10: 41 49 4e 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23  AINT | (8<<8)).#
5a20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5a30: 4e 53 54 52 41 49 4e 54 5f 56 54 41 42 20 20 20  NSTRAINT_VTAB   
5a40: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5a50: 4e 53 54 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38  NSTRAINT | (9<<8
5a60: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5a70: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57  E_CONSTRAINT_ROW
5a80: 49 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  ID        (SQLIT
5a90: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31  E_CONSTRAINT |(1
5aa0: 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  0<<8)).#define S
5ab0: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43  QLITE_NOTICE_REC
5ac0: 4f 56 45 52 5f 57 41 4c 20 20 20 20 20 20 28 53  OVER_WAL      (S
5ad0: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28  QLITE_NOTICE | (
5ae0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5af0: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43  QLITE_NOTICE_REC
5b00: 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 4b 20 28 53  OVER_ROLLBACK (S
5b10: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28  QLITE_NOTICE | (
5b20: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
5b30: 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55  QLITE_WARNING_AU
5b40: 54 4f 49 4e 44 45 58 20 20 20 20 20 20 20 28 53  TOINDEX       (S
5b50: 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20  QLITE_WARNING | 
5b60: 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43  (1<<8))../*.** C
5b70: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46  API3REF: Flags F
5b80: 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65  or File Open Ope
5b90: 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  rations.**.** Th
5ba0: 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61  ese bit values a
5bb0: 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
5bc0: 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72  use in the.** 3r
5bd0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
5be0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
5bf0: 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
5c00: 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34   and.** in the 4
5c10: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
5c20: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
5c30: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a  .xOpen] method..
5c40: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5c50: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20  E_OPEN_READONLY 
5c60: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5c70: 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  01  /* Ok for sq
5c80: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5c90: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5ca0: 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
5cb0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5cc0: 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  02  /* Ok for sq
5cd0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5ce0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5cf0: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20  E_OPEN_CREATE   
5d00: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5d10: 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  04  /* Ok for sq
5d20: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5d30: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5d40: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
5d50: 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 30  LOSE    0x000000
5d60: 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  08  /* VFS only 
5d70: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5d80: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
5d90: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5da0: 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  10  /* VFS only 
5db0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5dc0: 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59  E_OPEN_AUTOPROXY
5dd0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5de0: 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  20  /* VFS only 
5df0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5e00: 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20  E_OPEN_URI      
5e10: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5e20: 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  40  /* Ok for sq
5e30: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5e40: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5e50: 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20  E_OPEN_MEMORY   
5e60: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5e70: 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  80  /* Ok for sq
5e80: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5e90: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5ea0: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20  E_OPEN_MAIN_DB  
5eb0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31          0x000001
5ec0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5ed0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5ee0: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20  E_OPEN_TEMP_DB  
5ef0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32          0x000002
5f00: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5f10: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5f20: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
5f30: 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30 34  _DB     0x000004
5f40: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5f50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5f60: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52  E_OPEN_MAIN_JOUR
5f70: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 38  NAL     0x000008
5f80: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5f90: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5fa0: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52  E_OPEN_TEMP_JOUR
5fb0: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 30  NAL     0x000010
5fc0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5fd0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5fe0: 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41  E_OPEN_SUBJOURNA
5ff0: 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30  L       0x000020
6000: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6010: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6020: 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f  E_OPEN_MASTER_JO
6030: 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30  URNAL   0x000040
6040: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6050: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6060: 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20  E_OPEN_NOMUTEX  
6070: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38 30          0x000080
6080: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
6090: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
60a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
60b0: 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
60c0: 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30 30          0x000100
60d0: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
60e0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
60f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6100: 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
6110: 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30 30  HE      0x000200
6120: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
6130: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6140: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6150: 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
6160: 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30 30  CHE     0x000400
6170: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
6180: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6190: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
61a0: 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20  E_OPEN_WAL      
61b0: 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30 30          0x000800
61c0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
61d0: 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a  */../* Reserved:
61e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
61f0: 20 20 20 20 20 20 20 20 20 30 78 30 30 46 30 30           0x00F00
6200: 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  000 */../*.** CA
6210: 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43  PI3REF: Device C
6220: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a  haracteristics.*
6230: 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65  *.** The xDevice
6240: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
6250: 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73  method of the [s
6260: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
6270: 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74  s].** object ret
6280: 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20  urns an integer 
6290: 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f  which is a vecto
62a0: 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69  r of these.** bi
62b0: 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 73  t values express
62c0: 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65  ing I/O characte
62d0: 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d  ristics of the m
62e0: 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64  ass storage.** d
62f0: 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73  evice that holds
6300: 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 74   the file that t
6310: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
6320: 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72  ethods].** refer
6330: 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  s to..**.** The 
6340: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6350: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
6360: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74  ns that all writ
6370: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a  es of.** any siz
6380: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  e are atomic.  T
6390: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
63a0: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73  ATOMICnnn values
63b0: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72  .** mean that wr
63c0: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74  ites of blocks t
63d0: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65  hat are nnn byte
63e0: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a  s in size and.**
63f0: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20   are aligned to 
6400: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68  an address which
6410: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d   is an integer m
6420: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e  ultiple of.** nn
6430: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  n are atomic.  T
6440: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
6450: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75  SAFE_APPEND valu
6460: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  e means.** that 
6470: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70  when data is app
6480: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c  ended to a file,
6490: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70   the data is app
64a0: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74  ended.** first t
64b0: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  hen the size of 
64c0: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65  the file is exte
64d0: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20  nded, never the 
64e0: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f  other.** way aro
64f0: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  und.  The SQLITE
6500: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
6510: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  L property means
6520: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61   that.** informa
6530: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20  tion is written 
6540: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73  to disk in the s
6550: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c  ame order as cal
6560: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28  ls.** to xWrite(
6570: 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  ).  The SQLITE_I
6580: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
6590: 56 45 52 57 52 49 54 45 20 70 72 6f 70 65 72 74  VERWRITE propert
65a0: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20  y means that.** 
65b0: 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c  after reboot fol
65c0: 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f  lowing a crash o
65d0: 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68  r power loss, th
65e0: 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20  e only bytes in 
65f0: 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77  a.** file that w
6600: 65 72 65 20 77 72 69 74 74 65 6e 20 61 74 20 74  ere written at t
6610: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c  he application l
6620: 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20  evel might have 
6630: 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74  changed.** and t
6640: 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74  hat adjacent byt
6650: 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77  es, even bytes w
6660: 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73  ithin the same s
6670: 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61  ector are.** gua
6680: 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e  ranteed to be un
6690: 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 53 51  changed.  The SQ
66a0: 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c  LITE_IOCAP_UNDEL
66b0: 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e  ETABLE_WHEN_OPEN
66c0: 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63 61 74  .** flag indicat
66d0: 65 20 74 68 61 74 20 61 20 66 69 6c 65 20 63 61  e that a file ca
66e0: 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74 65 64 20  nnot be deleted 
66f0: 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68 65 0a  when open.  The.
6700: 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ** SQLITE_IOCAP_
6710: 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67 20 69  IMMUTABLE flag i
6720: 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74 68  ndicates that th
6730: 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a 20  e file is on.** 
6740: 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 20  read-only media 
6750: 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20 63 68  and cannot be ch
6760: 61 6e 67 65 64 20 65 76 65 6e 20 62 79 20 70 72  anged even by pr
6770: 6f 63 65 73 73 65 73 20 77 69 74 68 0a 2a 2a 20  ocesses with.** 
6780: 65 6c 65 76 61 74 65 64 20 70 72 69 76 69 6c 65  elevated privile
6790: 67 65 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ges..*/.#define 
67a0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
67b0: 4d 49 43 20 20 20 20 20 20 20 20 20 20 20 20 20  MIC             
67c0: 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23      0x00000001.#
67d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
67e0: 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20  CAP_ATOMIC512   
67f0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6800: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
6810: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6820: 43 31 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C1K             
6830: 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65    0x00000004.#de
6840: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6850: 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20  P_ATOMIC2K      
6860: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6870: 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  008.#define SQLI
6880: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34  TE_IOCAP_ATOMIC4
6890: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
68a0: 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69  0x00000010.#defi
68b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
68c0: 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20  ATOMIC8K        
68d0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32         0x0000002
68e0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
68f0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b  _IOCAP_ATOMIC16K
6900: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6910: 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65  00000040.#define
6920: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6930: 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20 20  OMIC32K         
6940: 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a       0x00000080.
6950: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6960: 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20  OCAP_ATOMIC64K  
6970: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6980: 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53  000100.#define S
6990: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
69a0: 5f 41 50 50 45 4e 44 20 20 20 20 20 20 20 20 20  _APPEND         
69b0: 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64     0x00000200.#d
69c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
69d0: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20  AP_SEQUENTIAL   
69e0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
69f0: 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0400.#define SQL
6a00: 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45  ITE_IOCAP_UNDELE
6a10: 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20  TABLE_WHEN_OPEN 
6a20: 20 30 78 30 30 30 30 30 38 30 30 0a 23 64 65 66   0x00000800.#def
6a30: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6a40: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
6a50: 52 49 54 45 20 20 20 20 30 78 30 30 30 30 31 30  RITE    0x000010
6a60: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
6a70: 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c  E_IOCAP_IMMUTABL
6a80: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  E              0
6a90: 78 30 30 30 30 32 30 30 30 0a 0a 2f 2a 0a 2a 2a  x00002000../*.**
6aa0: 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20   CAPI3REF: File 
6ab0: 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a  Locking Levels.*
6ac0: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
6ad0: 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e   one of these in
6ae0: 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20  teger values as 
6af0: 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72  the second.** ar
6b00: 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20  gument to calls 
6b10: 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20  it makes to the 
6b20: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c  xLock() and xUnl
6b30: 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a  ock() methods.**
6b40: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
6b50: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
6b60: 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ct..*/.#define S
6b70: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20  QLITE_LOCK_NONE 
6b80: 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69           0.#defi
6b90: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  ne SQLITE_LOCK_S
6ba0: 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23  HARED        1.#
6bb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
6bc0: 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20  CK_RESERVED     
6bd0: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
6be0: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20  E_LOCK_PENDING  
6bf0: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
6c00: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
6c10: 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a  SIVE     4../*.*
6c20: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63  * CAPI3REF: Sync
6c30: 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65  hronization Type
6c40: 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65   Flags.**.** Whe
6c50: 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73  n SQLite invokes
6c60: 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74   the xSync() met
6c70: 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71  hod of an.** [sq
6c80: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
6c90: 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73  ] object it uses
6ca0: 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f   a combination o
6cb0: 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67  f.** these integ
6cc0: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65  er values as the
6cd0: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
6ce0: 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
6cf0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54   SQLITE_SYNC_DAT
6d00: 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73  AONLY flag is us
6d10: 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61  ed, it means tha
6d20: 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70  t the.** sync op
6d30: 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65  eration only nee
6d40: 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61  ds to flush data
6d50: 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65   to mass storage
6d60: 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f  .  Inode.** info
6d70: 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74  rmation need not
6d80: 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20   be flushed. If 
6d90: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62  the lower four b
6da0: 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a  its of the flag.
6db0: 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f  ** equal SQLITE_
6dc0: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61  SYNC_NORMAL, tha
6dd0: 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e  t means to use n
6de0: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65  ormal fsync() se
6df0: 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74  mantics..** If t
6e00: 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69  he lower four bi
6e10: 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f  ts equal SQLITE_
6e20: 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20  SYNC_FULL, that 
6e30: 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20  means.** to use 
6e40: 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66  Mac OS X style f
6e50: 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20  ullsync instead 
6e60: 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a  of fsync()..**.*
6e70: 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65  * Do not confuse
6e80: 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   the SQLITE_SYNC
6e90: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49  _NORMAL and SQLI
6ea0: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61  TE_SYNC_FULL fla
6eb0: 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  gs.** with the [
6ec0: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
6ed0: 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b  us]=NORMAL and [
6ee0: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
6ef0: 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74  us]=FULL.** sett
6f00: 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63  ings.  The [sync
6f10: 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20  hronous pragma] 
6f20: 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20  determines when 
6f30: 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20  calls to the.** 
6f40: 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64  xSync VFS method
6f50: 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69   occur and appli
6f60: 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72  es uniformly acr
6f70: 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d  oss all platform
6f80: 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  s..** The SQLITE
6f90: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64  _SYNC_NORMAL and
6fa0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
6fb0: 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e  L flags determin
6fc0: 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74  e how.** energet
6fd0: 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f  ic or rigorous o
6fe0: 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73  r forceful the s
6ff0: 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61  ync operations a
7000: 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d  re and.** only m
7010: 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63 65  ake a difference
7020: 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20   on Mac OSX for 
7030: 74 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69  the default SQLi
7040: 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69  te code..** (Thi
7050: 72 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70  rd-party VFS imp
7060: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67  lementations mig
7070: 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65  ht also make the
7080: 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20   distinction.** 
7090: 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53  between SQLITE_S
70a0: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
70b0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c  QLITE_SYNC_FULL,
70c0: 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a   but among the.*
70d0: 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  * operating syst
70e0: 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70  ems natively sup
70f0: 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65  ported by SQLite
7100: 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a  , only Mac OSX.*
7110: 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20 74 68  * cares about th
7120: 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a  e difference.).*
7130: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
7140: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20  _SYNC_NORMAL    
7150: 20 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 66      0x00002.#def
7160: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
7170: 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78  FULL          0x
7180: 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51  00003.#define SQ
7190: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
71a0: 4c 59 20 20 20 20 20 20 30 78 30 30 30 31 30 0a  LY      0x00010.
71b0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
71c0: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70   OS Interface Op
71d0: 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a  en File Handle.*
71e0: 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33  *.** An [sqlite3
71f0: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65  _file] object re
7200: 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e  presents an open
7210: 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a   file in the .**
7220: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20   [sqlite3_vfs | 
7230: 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79  OS interface lay
7240: 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c  er].  Individual
7250: 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a   OS interface.**
7260: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
7270: 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f   will.** want to
7280: 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f   subclass this o
7290: 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69  bject by appendi
72a0: 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69  ng additional fi
72b0: 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69  elds.** for thei
72c0: 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20  r own use.  The 
72d0: 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69  pMethods entry i
72e0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
72f0: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f  n.** [sqlite3_io
7300: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
7310: 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65   that defines me
7320: 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72  thods for perfor
7330: 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72  ming.** I/O oper
7340: 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70  ations on the op
7350: 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65  en file..*/.type
7360: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
7370: 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f  e3_file sqlite3_
7380: 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c  file;.struct sql
7390: 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f  ite3_file {.  co
73a0: 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74  nst struct sqlit
73b0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70  e3_io_methods *p
73c0: 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74  Methods;  /* Met
73d0: 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e  hods for an open
73e0: 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a   file */.};../*.
73f0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
7400: 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56  Interface File V
7410: 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f  irtual Methods O
7420: 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72  bject.**.** Ever
7430: 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79  y file opened by
7440: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
7450: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20  s.xOpen] method 
7460: 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20  populates an.** 
7470: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
7480: 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20  bject (or, more 
7490: 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63  commonly, a subc
74a0: 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  lass of the.** [
74b0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
74c0: 6a 65 63 74 29 20 77 69 74 68 20 61 20 70 6f 69  ject) with a poi
74d0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
74e0: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
74f0: 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65  ct..** This obje
7500: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d  ct defines the m
7510: 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70  ethods used to p
7520: 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f  erform various o
7530: 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61  perations.** aga
7540: 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69  inst the open fi
7550: 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 62  le represented b
7560: 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  y the [sqlite3_f
7570: 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a  ile] object..**.
7580: 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74  ** If the [sqlit
7590: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65  e3_vfs.xOpen] me
75a0: 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71  thod sets the sq
75b0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
75c0: 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20  ods element .** 
75d0: 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  to a non-NULL po
75e0: 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  inter, then the 
75f0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7600: 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64  ds.xClose method
7610: 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b  .** may be invok
7620: 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b  ed even if the [
7630: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
7640: 6e 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61 74  n] reported that
7650: 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65   it failed.  The
7660: 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20  .** only way to 
7670: 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74  prevent a call t
7680: 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69  o xClose followi
7690: 6e 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c  ng a failed [sql
76a0: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a  ite3_vfs.xOpen].
76b0: 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73  ** is for the [s
76c0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
76d0: 5d 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c  ] to set the sql
76e0: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
76f0: 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f  ds element.** to
7700: 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   NULL..**.** The
7710: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
7720: 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20  to xSync may be 
7730: 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53  one of [SQLITE_S
7740: 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a  YNC_NORMAL] or.*
7750: 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  * [SQLITE_SYNC_F
7760: 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74  ULL].  The first
7770: 20 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e   choice is the n
7780: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a  ormal fsync()..*
7790: 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f  * The second cho
77a0: 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20  ice is a Mac OS 
77b0: 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63  X style fullsync
77c0: 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53  .  The [SQLITE_S
77d0: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a  YNC_DATAONLY].**
77e0: 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65   flag may be ORe
77f0: 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65  d in to indicate
7800: 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64   that only the d
7810: 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a  ata of the file.
7820: 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69  ** and not its i
7830: 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65  node needs to be
7840: 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   synced..**.** T
7850: 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  he integer value
7860: 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64  s to xLock() and
7870: 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f   xUnlock() are o
7880: 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  ne of.** <ul>.**
7890: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
78a0: 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69  CK_NONE],.** <li
78b0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  > [SQLITE_LOCK_S
78c0: 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  HARED],.** <li> 
78d0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53  [SQLITE_LOCK_RES
78e0: 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  ERVED],.** <li> 
78f0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e  [SQLITE_LOCK_PEN
7900: 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69  DING], or.** <li
7910: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  > [SQLITE_LOCK_E
7920: 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f  XCLUSIVE]..** </
7930: 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69  ul>.** xLock() i
7940: 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63  ncreases the loc
7950: 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63  k. xUnlock() dec
7960: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e  reases the lock.
7970: 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65  .** The xCheckRe
7980: 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74  servedLock() met
7990: 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68  hod checks wheth
79a0: 65 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20  er any database 
79b0: 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65  connection,.** e
79c0: 69 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72  ither in this pr
79d0: 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65  ocess or in some
79e0: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20   other process, 
79f0: 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53  is holding a RES
7a00: 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e  ERVED,.** PENDIN
7a10: 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20  G, or EXCLUSIVE 
7a20: 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65  lock on the file
7a30: 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72  .  It returns tr
7a40: 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20  ue.** if such a 
7a50: 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20  lock exists and 
7a60: 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e  false otherwise.
7a70: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65  .**.** The xFile
7a80: 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64  Control() method
7a90: 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e   is a generic in
7aa0: 74 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c  terface that all
7ab0: 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46  ows custom.** VF
7ac0: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
7ad0: 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f  s to directly co
7ae0: 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69  ntrol an open fi
7af0: 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  le using the.** 
7b00: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
7b10: 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61  ntrol()] interfa
7b20: 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ce.  The second 
7b30: 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73  "op" argument is
7b40: 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f   an.** integer o
7b50: 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72  pcode.  The thir
7b60: 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  d argument is a 
7b70: 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20  generic pointer 
7b80: 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70  intended to.** p
7b90: 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74  oint to a struct
7ba0: 75 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e  ure that may con
7bb0: 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f  tain arguments o
7bc0: 72 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68  r space in which
7bd0: 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74   to.** write ret
7be0: 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74  urn values.  Pot
7bf0: 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20  ential uses for 
7c00: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d  xFileControl() m
7c10: 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74  ight be.** funct
7c20: 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62  ions to enable b
7c30: 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69  locking locks wi
7c40: 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20  th timeouts, to 
7c50: 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f  change the.** lo
7c60: 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28  cking strategy (
7c70: 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75  for example to u
7c80: 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b  se dot-file lock
7c90: 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a  s), to inquire.*
7ca0: 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74  * about the stat
7cb0: 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72  us of a lock, or
7cc0: 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20   to break stale 
7cd0: 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69  locks.  The SQLi
7ce0: 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72  te.** core reser
7cf0: 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20  ves all opcodes 
7d00: 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f  less than 100 fo
7d10: 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a  r its own use..*
7d20: 2a 20 41 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f  * A [file contro
7d30: 6c 20 6f 70 63 6f 64 65 73 20 7c 20 6c 69 73 74  l opcodes | list
7d40: 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73   of opcodes] les
7d50: 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76  s than 100 is av
7d60: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c  ailable..** Appl
7d70: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65  ications that de
7d80: 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46  fine a custom xF
7d90: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
7da0: 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63  d should use opc
7db0: 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20  odes.** greater 
7dc0: 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69  than 100 to avoi
7dd0: 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46  d conflicts.  VF
7de0: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
7df0: 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  s should.** retu
7e00: 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  rn [SQLITE_NOTFO
7e10: 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f  UND] for file co
7e20: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68  ntrol opcodes th
7e30: 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a  at they do not.*
7e40: 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a  * recognize..**.
7e50: 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69  ** The xSectorSi
7e60: 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75  ze() method retu
7e70: 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73  rns the sector s
7e80: 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65  ize of the.** de
7e90: 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c  vice that underl
7ea0: 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54  ies the file.  T
7eb0: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69  he sector size i
7ec0: 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d  s the.** minimum
7ed0: 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20   write that can 
7ee0: 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74  be performed wit
7ef0: 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a  hout disturbing.
7f00: 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69  ** other bytes i
7f10: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65  n the file.  The
7f20: 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65   xDeviceCharacte
7f30: 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74  ristics().** met
7f40: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69  hod returns a bi
7f50: 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62  t vector describ
7f60: 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66  ing behaviors of
7f70: 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69   the.** underlyi
7f80: 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a  ng device:.**.**
7f90: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
7fa0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7fb0: 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  IC].** <li> [SQL
7fc0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7fd0: 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  512].** <li> [SQ
7fe0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7ff0: 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C1K].** <li> [SQ
8000: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8010: 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C2K].** <li> [SQ
8020: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8030: 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C4K].** <li> [SQ
8040: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8050: 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C8K].** <li> [SQ
8060: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8070: 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C16K].** <li> [S
8080: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
8090: 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC32K].** <li> [
80a0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
80b0: 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC64K].** <li> 
80c0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41  [SQLITE_IOCAP_SA
80d0: 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c  FE_APPEND].** <l
80e0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
80f0: 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20  _SEQUENTIAL].** 
8100: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
8110: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8120: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
8130: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74  ns that all writ
8140: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a  es of.** any siz
8150: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  e are atomic.  T
8160: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
8170: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73  ATOMICnnn values
8180: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72  .** mean that wr
8190: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74  ites of blocks t
81a0: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65  hat are nnn byte
81b0: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a  s in size and.**
81c0: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20   are aligned to 
81d0: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68  an address which
81e0: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d   is an integer m
81f0: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e  ultiple of.** nn
8200: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  n are atomic.  T
8210: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
8220: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75  SAFE_APPEND valu
8230: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  e means.** that 
8240: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70  when data is app
8250: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c  ended to a file,
8260: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70   the data is app
8270: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74  ended.** first t
8280: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  hen the size of 
8290: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65  the file is exte
82a0: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20  nded, never the 
82b0: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f  other.** way aro
82c0: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  und.  The SQLITE
82d0: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
82e0: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  L property means
82f0: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61   that.** informa
8300: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20  tion is written 
8310: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73  to disk in the s
8320: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c  ame order as cal
8330: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28  ls.** to xWrite(
8340: 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61  )..**.** If xRea
8350: 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49  d() returns SQLI
8360: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
8370: 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f  EAD it must also
8380: 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20   fill.** in the 
8390: 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20  unread portions 
83a0: 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 77 69  of the buffer wi
83b0: 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53  th zeros.  A VFS
83c0: 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74   that.** fails t
83d0: 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72  o zero-fill shor
83e0: 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 73 65  t reads might se
83f0: 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77  em to work.  How
8400: 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65  ever,.** failure
8410: 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68   to zero-fill sh
8420: 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65  ort reads will e
8430: 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74  ventually lead t
8440: 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  o.** database co
8450: 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70  rruption..*/.typ
8460: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
8470: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73  te3_io_methods s
8480: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
8490: 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  s;.struct sqlite
84a0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20  3_io_methods {. 
84b0: 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20   int iVersion;. 
84c0: 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73   int (*xClose)(s
84d0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
84e0: 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71   int (*xRead)(sq
84f0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69  lite3_file*, voi
8500: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
8510: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
8520: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69  t);.  int (*xWri
8530: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  te)(sqlite3_file
8540: 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const 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 54 72 75 6e 63 61 74    int (*xTruncat
8580: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
8590: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
85a0: 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78  size);.  int (*x
85b0: 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69  Sync)(sqlite3_fi
85c0: 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b  le*, int flags);
85d0: 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69  .  int (*xFileSi
85e0: 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ze)(sqlite3_file
85f0: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
8600: 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20   *pSize);.  int 
8610: 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33  (*xLock)(sqlite3
8620: 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20  _file*, int);.  
8630: 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73  int (*xUnlock)(s
8640: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8650: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65  t);.  int (*xChe
8660: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28  ckReservedLock)(
8670: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8680: 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20  nt *pResOut);.  
8690: 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72  int (*xFileContr
86a0: 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ol)(sqlite3_file
86b0: 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20  *, int op, void 
86c0: 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a  *pArg);.  int (*
86d0: 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c  xSectorSize)(sql
86e0: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69  ite3_file*);.  i
86f0: 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72  nt (*xDeviceChar
8700: 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c  acteristics)(sql
8710: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f  ite3_file*);.  /
8720: 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  * Methods above 
8730: 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65  are valid for ve
8740: 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74  rsion 1 */.  int
8750: 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c 69   (*xShmMap)(sqli
8760: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69  te3_file*, int i
8770: 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e  Pg, int pgsz, in
8780: 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65  t, void volatile
8790: 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68  **);.  int (*xSh
87a0: 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  mLock)(sqlite3_f
87b0: 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74  ile*, int offset
87c0: 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61  , int n, int fla
87d0: 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53  gs);.  void (*xS
87e0: 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69 74  hmBarrier)(sqlit
87f0: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
8800: 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 71   (*xShmUnmap)(sq
8810: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8820: 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20   deleteFlag);.  
8830: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65  /* Methods above
8840: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76   are valid for v
8850: 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e  ersion 2 */.  in
8860: 74 20 28 2a 78 46 65 74 63 68 29 28 73 71 6c 69  t (*xFetch)(sqli
8870: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
8880: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20  e3_int64 iOfst, 
8890: 69 6e 74 20 69 41 6d 74 2c 20 76 6f 69 64 20 2a  int iAmt, void *
88a0: 2a 70 70 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55  *pp);.  int (*xU
88b0: 6e 66 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f  nfetch)(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 76 6f 69 64  nt64 iOfst, void
88e0: 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f   *p);.  /* Metho
88f0: 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c  ds above are val
8900: 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33  id for version 3
8910: 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f   */.  /* Additio
8920: 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20  nal methods may 
8930: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
8940: 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d  re releases */.}
8950: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
8960: 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65  F: Standard File
8970: 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73   Control Opcodes
8980: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66  .** KEYWORDS: {f
8990: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f  ile control opco
89a0: 64 65 73 7d 20 7b 66 69 6c 65 20 63 6f 6e 74 72  des} {file contr
89b0: 6f 6c 20 6f 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a  ol opcode}.**.**
89c0: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
89d0: 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63  onstants are opc
89e0: 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69  odes for the xFi
89f0: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
8a00: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
8a10: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
8a20: 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74  object and for t
8a30: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
8a40: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69  _control()].** i
8a50: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
8a60: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
8a70: 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63  L_LOCKSTATE] opc
8a80: 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20  ode is used for 
8a90: 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73  debugging.  This
8aa0: 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65  .** opcode cause
8ab0: 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  s the xFileContr
8ac0: 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69  ol method to wri
8ad0: 74 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 73  te the current s
8ae0: 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c  tate of.** the l
8af0: 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c  ock (one of [SQL
8b00: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20  ITE_LOCK_NONE], 
8b10: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41  [SQLITE_LOCK_SHA
8b20: 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  RED],.** [SQLITE
8b30: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c  _LOCK_RESERVED],
8b40: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45   [SQLITE_LOCK_PE
8b50: 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49  NDING], or [SQLI
8b60: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
8b70: 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69  E]).** into an i
8b80: 6e 74 65 67 65 72 20 74 68 61 74 20 74 68 65 20  nteger that the 
8b90: 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f  pArg argument po
8ba0: 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61  ints to. This ca
8bb0: 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75  pability.** is u
8bc0: 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69  sed during testi
8bd0: 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64  ng and only need
8be0: 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  s to be supporte
8bf0: 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45  d when SQLITE_TE
8c00: 53 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64  ST.** is defined
8c10: 2e 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  ..** <ul>.** <li
8c20: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
8c30: 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54  SIZE_HINT]].** T
8c40: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
8c50: 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f  _SIZE_HINT] opco
8c60: 64 65 20 69 73 20 75 73 65 64 20 62 79 20 53 51  de is used by SQ
8c70: 4c 69 74 65 20 74 6f 20 67 69 76 65 20 74 68 65  Lite to give the
8c80: 20 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20   VFS.** layer a 
8c90: 68 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67  hint of how larg
8ca0: 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  e the database f
8cb0: 69 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f  ile will grow to
8cc0: 20 62 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a   be during the.*
8cd0: 2a 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61  * current transa
8ce0: 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e  ction.  This hin
8cf0: 74 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74  t is not guarant
8d00: 65 65 64 20 74 6f 20 62 65 20 61 63 63 75 72 61  eed to be accura
8d10: 74 65 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20  te but it.** is 
8d20: 6f 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68  often close.  Th
8d30: 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53  e underlying VFS
8d40: 20 6d 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f   might choose to
8d50: 20 70 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74   preallocate dat
8d60: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70  abase.** file sp
8d70: 61 63 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69  ace based on thi
8d80: 73 20 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20  s hint in order 
8d90: 74 6f 20 68 65 6c 70 20 77 72 69 74 65 73 20 74  to help writes t
8da0: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  o the database.*
8db0: 2a 20 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65  * file run faste
8dc0: 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  r..**.** <li>[[S
8dd0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e  QLITE_FCNTL_CHUN
8de0: 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20  K_SIZE]].** The 
8df0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48  [SQLITE_FCNTL_CH
8e00: 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65  UNK_SIZE] opcode
8e10: 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 71 75   is used to requ
8e20: 65 73 74 20 74 68 61 74 20 74 68 65 20 56 46 53  est that the VFS
8e30: 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 20  .** extends and 
8e40: 74 72 75 6e 63 61 74 65 73 20 74 68 65 20 64 61  truncates the da
8e50: 74 61 62 61 73 65 20 66 69 6c 65 20 69 6e 20 63  tabase file in c
8e60: 68 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 20  hunks of a size 
8e70: 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20  specified.** by 
8e80: 74 68 65 20 75 73 65 72 2e 20 54 68 65 20 66 6f  the user. The fo
8e90: 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  urth argument to
8ea0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
8eb0: 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64  ontrol()] should
8ec0: 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e   .** point to an
8ed0: 20 69 6e 74 65 67 65 72 20 28 74 79 70 65 20 69   integer (type i
8ee0: 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  nt) containing t
8ef0: 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a  he new chunk-siz
8f00: 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20  e to use.** for 
8f10: 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61  the nominated da
8f20: 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69  tabase. Allocati
8f30: 6e 67 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  ng database file
8f40: 20 73 70 61 63 65 20 69 6e 20 6c 61 72 67 65 0a   space in large.
8f50: 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61 79 20 31  ** chunks (say 1
8f60: 4d 42 20 61 74 20 61 20 74 69 6d 65 29 2c 20 6d  MB at a time), m
8f70: 61 79 20 72 65 64 75 63 65 20 66 69 6c 65 2d 73  ay reduce file-s
8f80: 79 73 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 74  ystem fragmentat
8f90: 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f  ion and.** impro
8fa0: 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f  ve performance o
8fb0: 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a  n some systems..
8fc0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
8fd0: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f  TE_FCNTL_FILE_PO
8fe0: 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b  INTER]].** The [
8ff0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c  SQLITE_FCNTL_FIL
9000: 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64  E_POINTER] opcod
9010: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74  e is used to obt
9020: 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  ain a pointer.**
9030: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
9040: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73  _file] object as
9050: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
9060: 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62  particular datab
9070: 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
9080: 6e 2e 20 20 53 65 65 20 74 68 65 20 5b 73 71 6c  n.  See the [sql
9090: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
90a0: 6c 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69  l()] documentati
90b0: 6f 6e 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69  on for.** additi
90c0: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
90d0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
90e0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f  LITE_FCNTL_SYNC_
90f0: 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20  OMITTED]].** No 
9100: 6c 6f 6e 67 65 72 20 69 6e 20 75 73 65 2e 0a 2a  longer in use..*
9110: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9120: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a  E_FCNTL_SYNC]].*
9130: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
9140: 4e 54 4c 5f 53 59 4e 43 5d 20 6f 70 63 6f 64 65  NTL_SYNC] opcode
9150: 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e   is generated in
9160: 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69  ternally by SQLi
9170: 74 65 20 61 6e 64 0a 2a 2a 20 73 65 6e 74 20 74  te and.** sent t
9180: 6f 20 74 68 65 20 56 46 53 20 69 6d 6d 65 64 69  o the VFS immedi
9190: 61 74 65 6c 79 20 62 65 66 6f 72 65 20 74 68 65  ately before the
91a0: 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73   xSync method is
91b0: 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a   invoked on a.**
91c0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 64   database file d
91d0: 65 73 63 72 69 70 74 6f 72 2e 20 4f 72 2c 20 69  escriptor. Or, i
91e0: 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  f the xSync meth
91f0: 6f 64 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  od is not invoke
9200: 64 20 0a 2a 2a 20 62 65 63 61 75 73 65 20 74 68  d .** because th
9210: 65 20 75 73 65 72 20 68 61 73 20 63 6f 6e 66 69  e user has confi
9220: 67 75 72 65 64 20 53 51 4c 69 74 65 20 77 69 74  gured SQLite wit
9230: 68 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 73 79  h .** [PRAGMA sy
9240: 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47  nchronous | PRAG
9250: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f  MA synchronous=O
9260: 46 46 5d 20 69 74 20 69 73 20 69 6e 76 6f 6b 65  FF] it is invoke
9270: 64 20 69 6e 20 70 6c 61 63 65 20 0a 2a 2a 20 6f  d in place .** o
9280: 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  f the xSync meth
9290: 6f 64 2e 20 49 6e 20 6d 6f 73 74 20 63 61 73 65  od. In most case
92a0: 73 2c 20 74 68 65 20 70 6f 69 6e 74 65 72 20 61  s, the pointer a
92b0: 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 77  rgument passed w
92c0: 69 74 68 0a 2a 2a 20 74 68 69 73 20 66 69 6c 65  ith.** this file
92d0: 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 4e 55 4c 4c  -control is NULL
92e0: 2e 20 48 6f 77 65 76 65 72 2c 20 69 66 20 74 68  . However, if th
92f0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
9300: 69 73 20 62 65 69 6e 67 20 73 79 6e 63 65 64 0a  is being synced.
9310: 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 61 20  ** as part of a 
9320: 6d 75 6c 74 69 2d 64 61 74 61 62 61 73 65 20 63  multi-database c
9330: 6f 6d 6d 69 74 2c 20 74 68 65 20 61 72 67 75 6d  ommit, the argum
9340: 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20  ent points to a 
9350: 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  nul-terminated.*
9360: 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e  * string contain
9370: 69 6e 67 20 74 68 65 20 74 72 61 6e 73 61 63 74  ing the transact
9380: 69 6f 6e 73 20 6d 61 73 74 65 72 2d 6a 6f 75 72  ions master-jour
9390: 6e 61 6c 20 66 69 6c 65 20 6e 61 6d 65 2e 20 56  nal file name. V
93a0: 46 53 65 73 20 74 68 61 74 20 0a 2a 2a 20 64 6f  FSes that .** do
93b0: 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73   not need this s
93c0: 69 67 6e 61 6c 20 73 68 6f 75 6c 64 20 73 69 6c  ignal should sil
93d0: 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69  ently ignore thi
93e0: 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63  s opcode. Applic
93f0: 61 74 69 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c  ations .** shoul
9400: 64 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69  d not call [sqli
9410: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
9420: 28 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70  ()] with this op
9430: 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f  code as doing so
9440: 20 6d 61 79 20 0a 2a 2a 20 64 69 73 72 75 70 74   may .** disrupt
9450: 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f   the operation o
9460: 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65  f the specialize
9470: 64 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20  d VFSes that do 
9480: 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a  require it.  .**
9490: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
94a0: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48  _FCNTL_COMMIT_PH
94b0: 41 53 45 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20  ASETWO]].** The 
94c0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f  [SQLITE_FCNTL_CO
94d0: 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 20 6f  MMIT_PHASETWO] o
94e0: 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74  pcode is generat
94f0: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79  ed internally by
9500: 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 73   SQLite.** and s
9510: 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 61  ent to the VFS a
9520: 66 74 65 72 20 61 20 74 72 61 6e 73 61 63 74 69  fter a transacti
9530: 6f 6e 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 6d  on has been comm
9540: 69 74 74 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  itted immediatel
9550: 79 0a 2a 2a 20 62 75 74 20 62 65 66 6f 72 65 20  y.** but before 
9560: 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
9570: 75 6e 6c 6f 63 6b 65 64 2e 20 56 46 53 65 73 20  unlocked. VFSes 
9580: 74 68 61 74 20 64 6f 20 6e 6f 74 20 6e 65 65 64  that do not need
9590: 20 74 68 69 73 20 73 69 67 6e 61 6c 0a 2a 2a 20   this signal.** 
95a0: 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20  should silently 
95b0: 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f  ignore this opco
95c0: 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  de. Applications
95d0: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c   should not call
95e0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
95f0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74  e_control()] wit
9600: 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73  h this opcode as
9610: 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 69   doing so may di
9620: 73 72 75 70 74 20 74 68 65 20 0a 2a 2a 20 6f 70  srupt the .** op
9630: 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73  eration of the s
9640: 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73  pecialized VFSes
9650: 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65   that do require
9660: 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69   it.  .**.** <li
9670: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9680: 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d  WIN32_AV_RETRY]]
9690: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
96a0: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f  _FCNTL_WIN32_AV_
96b0: 52 45 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73  RETRY] opcode is
96c0: 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75   used to configu
96d0: 72 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20  re automatic.** 
96e0: 72 65 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64  retry counts and
96f0: 20 69 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63   intervals for c
9700: 65 72 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20  ertain disk I/O 
9710: 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74  operations for t
9720: 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56  he.** windows [V
9730: 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  FS] in order to 
9740: 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65  provide robustne
9750: 73 73 20 69 6e 20 74 68 65 20 70 72 65 73 65 6e  ss in the presen
9760: 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69  ce of.** anti-vi
9770: 72 75 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 42  rus programs.  B
9780: 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 77  y default, the w
9790: 69 6e 64 6f 77 73 20 56 46 53 20 77 69 6c 6c 20  indows VFS will 
97a0: 72 65 74 72 79 20 66 69 6c 65 20 72 65 61 64 2c  retry file read,
97b0: 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74 65 2c 20  .** file write, 
97c0: 61 6e 64 20 66 69 6c 65 20 64 65 6c 65 74 65 20  and file delete 
97d0: 6f 70 65 72 61 74 69 6f 6e 73 20 75 70 20 74 6f  operations up to
97e0: 20 31 30 20 74 69 6d 65 73 2c 20 77 69 74 68 20   10 times, with 
97f0: 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35  a delay.** of 25
9800: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65   milliseconds be
9810: 66 6f 72 65 20 74 68 65 20 66 69 72 73 74 20 72  fore the first r
9820: 65 74 72 79 20 61 6e 64 20 77 69 74 68 20 74 68  etry and with th
9830: 65 20 64 65 6c 61 79 20 69 6e 63 72 65 61 73 69  e delay increasi
9840: 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 69  ng.** by an addi
9850: 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73  tional 25 millis
9860: 65 63 6f 6e 64 73 20 77 69 74 68 20 65 61 63 68  econds with each
9870: 20 73 75 62 73 65 71 75 65 6e 74 20 72 65 74 72   subsequent retr
9880: 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f  y.  This.** opco
9890: 64 65 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 20  de allows these 
98a0: 74 77 6f 20 76 61 6c 75 65 73 20 28 31 30 20 72  two values (10 r
98b0: 65 74 72 69 65 73 20 61 6e 64 20 32 35 20 6d 69  etries and 25 mi
98c0: 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 65  lliseconds of de
98d0: 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64  lay).** to be ad
98e0: 6a 75 73 74 65 64 2e 20 20 54 68 65 20 76 61 6c  justed.  The val
98f0: 75 65 73 20 61 72 65 20 63 68 61 6e 67 65 64 20  ues are changed 
9900: 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 73 65  for all database
9910: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20   connections.** 
9920: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
9930: 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20 61 72  process.  The ar
9940: 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
9950: 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20  ter to an array 
9960: 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65  of two.** intege
9970: 72 73 20 77 68 65 72 65 20 74 68 65 20 66 69 72  rs where the fir
9980: 73 74 20 69 6e 74 65 67 65 72 20 69 20 74 68 65  st integer i the
9990: 20 6e 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74   new retry count
99a0: 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a   and the second.
99b0: 2a 2a 20 69 6e 74 65 67 65 72 20 69 73 20 74 68  ** integer is th
99c0: 65 20 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74  e delay.  If eit
99d0: 68 65 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e  her integer is n
99e0: 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68  egative, then th
99f0: 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20  e setting.** is 
9a00: 6e 6f 74 20 63 68 61 6e 67 65 64 20 62 75 74 20  not changed but 
9a10: 69 6e 73 74 65 61 64 20 74 68 65 20 70 72 69 6f  instead the prio
9a20: 72 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20  r value of that 
9a30: 73 65 74 74 69 6e 67 20 69 73 20 77 72 69 74 74  setting is writt
9a40: 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61  en.** into the a
9a50: 72 72 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f  rray entry, allo
9a60: 77 69 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74  wing the current
9a70: 20 72 65 74 72 79 20 73 65 74 74 69 6e 67 73 20   retry settings 
9a80: 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f  to be.** interro
9a90: 67 61 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e  gated.  The zDbN
9aa0: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  ame parameter is
9ab0: 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20   ignored..**.** 
9ac0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
9ad0: 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d  TL_PERSIST_WAL]]
9ae0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
9af0: 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57  _FCNTL_PERSIST_W
9b00: 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  AL] opcode is us
9b10: 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65  ed to set or que
9b20: 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73  ry the.** persis
9b30: 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74  tent [WAL | Writ
9b40: 65 20 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 74  e Ahead Log] set
9b50: 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c  ting.  By defaul
9b60: 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61 72 79  t, the auxiliary
9b70: 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61 64 20  .** write ahead 
9b80: 6c 6f 67 20 61 6e 64 20 73 68 61 72 65 64 20 6d  log and shared m
9b90: 65 6d 6f 72 79 20 66 69 6c 65 73 20 75 73 65 64  emory files used
9ba0: 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e   for transaction
9bb0: 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20   control.** are 
9bc0: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65  automatically de
9bd0: 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c  leted when the l
9be0: 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e  atest connection
9bf0: 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   to the database
9c00: 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74  .** closes.  Set
9c10: 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20  ting persistent 
9c20: 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20  WAL mode causes 
9c30: 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70  those files to p
9c40: 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20  ersist after.** 
9c50: 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69  close.  Persisti
9c60: 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69 73 20  ng the files is 
9c70: 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65  useful when othe
9c80: 72 20 70 72 6f 63 65 73 73 65 73 20 74 68 61 74  r processes that
9c90: 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20   do not.** have 
9ca0: 77 72 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e  write permission
9cb0: 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72   on the director
9cc0: 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  y containing the
9cd0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
9ce0: 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74  ant.** to read t
9cf0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
9d00: 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64  , as the WAL and
9d10: 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66   shared memory f
9d20: 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a  iles must exist.
9d30: 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20  ** in order for 
9d40: 74 68 65 20 64 61 74 61 62 61 73 65 20 74 6f 20  the database to 
9d50: 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68  be readable.  Th
9d60: 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
9d70: 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  er to.** [sqlite
9d80: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
9d90: 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64  ] for this opcod
9da0: 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f  e should be a po
9db0: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
9dc0: 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74  ger..** That int
9dd0: 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73  eger is 0 to dis
9de0: 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20  able persistent 
9df0: 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f  WAL mode or 1 to
9e00: 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65   enable persiste
9e10: 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20  nt.** WAL mode. 
9e20: 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20   If the integer 
9e30: 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69  is -1, then it i
9e40: 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69  s overwritten wi
9e50: 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  th the current.*
9e60: 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63  * WAL persistenc
9e70: 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a  e setting..**.**
9e80: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9e90: 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  NTL_POWERSAFE_OV
9ea0: 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68  ERWRITE]].** ^Th
9eb0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
9ec0: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
9ed0: 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  ITE] opcode is u
9ee0: 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75  sed to set or qu
9ef0: 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69  ery the.** persi
9f00: 73 74 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65  stent "powersafe
9f10: 2d 6f 76 65 72 77 72 69 74 65 22 20 6f 72 20 22  -overwrite" or "
9f20: 50 53 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20  PSOW" setting.  
9f30: 54 68 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67  The PSOW setting
9f40: 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74  .** determines t
9f50: 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  he [SQLITE_IOCAP
9f60: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
9f70: 52 49 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65  RITE] bit of the
9f80: 0a 2a 2a 20 78 44 65 76 69 63 65 43 68 61 72 61  .** xDeviceChara
9f90: 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f  cteristics metho
9fa0: 64 73 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70  ds. The fourth p
9fb0: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b  arameter to.** [
9fc0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
9fd0: 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73  trol()] for this
9fe0: 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62   opcode should b
9ff0: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
a000: 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68  n integer..** Th
a010: 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20  at integer is 0 
a020: 74 6f 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d  to disable zero-
a030: 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31  damage mode or 1
a040: 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d   to enable zero-
a050: 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20  damage.** mode. 
a060: 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20   If the integer 
a070: 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69  is -1, then it i
a080: 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69  s overwritten wi
a090: 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  th the current.*
a0a0: 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f  * zero-damage mo
a0b0: 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a  de setting..**.*
a0c0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
a0d0: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d  CNTL_OVERWRITE]]
a0e0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
a0f0: 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45  _FCNTL_OVERWRITE
a100: 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f  ] opcode is invo
a110: 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 66  ked by SQLite af
a120: 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61  ter opening.** a
a130: 20 77 72 69 74 65 20 74 72 61 6e 73 61 63 74 69   write transacti
a140: 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  on to indicate t
a150: 68 61 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69  hat, unless it i
a160: 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f  s rolled back fo
a170: 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e  r some.** reason
a180: 2c 20 74 68 65 20 65 6e 74 69 72 65 20 64 61 74  , the entire dat
a190: 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20  abase file will 
a1a0: 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62  be overwritten b
a1b0: 79 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a  y the current .*
a1c0: 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54  * transaction. T
a1d0: 68 69 73 20 69 73 20 75 73 65 64 20 62 79 20 56  his is used by V
a1e0: 41 43 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73  ACUUM operations
a1f0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
a200: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41  LITE_FCNTL_VFSNA
a210: 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ME]].** ^The [SQ
a220: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41  LITE_FCNTL_VFSNA
a230: 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62  ME] opcode can b
a240: 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
a250: 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a   the names of.**
a260: 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20   all [VFSes] in 
a270: 74 68 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20  the VFS stack.  
a280: 54 68 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66  The names are of
a290: 20 61 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61   all VFS shims a
a2a0: 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20  nd the.** final 
a2b0: 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53  bottom-level VFS
a2c0: 20 61 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74   are written int
a2d0: 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
a2e0: 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69  d from .** [sqli
a2f0: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e  te3_malloc()] an
a300: 64 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  d the result is 
a310: 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68  stored in the ch
a320: 61 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20  ar* variable.** 
a330: 74 68 61 74 20 74 68 65 20 66 6f 75 72 74 68 20  that the fourth 
a340: 70 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71  parameter of [sq
a350: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
a360: 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e  ol()] points to.
a370: 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69  .** The caller i
a380: 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
a390: 72 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65  r freeing the me
a3a0: 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20  mory when done. 
a3b0: 20 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20   As with.** all 
a3c0: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74  file-control act
a3d0: 69 6f 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e  ions, there is n
a3e0: 6f 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74  o guarantee that
a3f0: 20 74 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61   this will actua
a400: 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69  lly.** do anythi
a410: 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f  ng.  Callers sho
a420: 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74  uld initialize t
a430: 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c  he char* variabl
a440: 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70  e to a NULL.** p
a450: 6f 69 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74  ointer in case t
a460: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  his file-control
a470: 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e   is not implemen
a480: 74 65 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d  ted.  This file-
a490: 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e  control.** is in
a4a0: 74 65 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e  tended for diagn
a4b0: 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a  ostic use only..
a4c0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
a4d0: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
a4e0: 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61  ].** ^Whenever a
a4f0: 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d   [PRAGMA] statem
a500: 65 6e 74 20 69 73 20 70 61 72 73 65 64 2c 20 61  ent is parsed, a
a510: 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  n [SQLITE_FCNTL_
a520: 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65  PRAGMA] .** file
a530: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74   control is sent
a540: 20 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71   to the open [sq
a550: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
a560: 63 74 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  ct corresponding
a570: 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62  .** to the datab
a580: 61 73 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63  ase file to whic
a590: 68 20 74 68 65 20 70 72 61 67 6d 61 20 73 74 61  h the pragma sta
a5a0: 74 65 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e  tement refers. ^
a5b0: 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  The argument.** 
a5c0: 74 6f 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46  to the [SQLITE_F
a5d0: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c  CNTL_PRAGMA] fil
a5e0: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20  e control is an 
a5f0: 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e  array of.** poin
a600: 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20  ters to strings 
a610: 28 63 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63  (char**) in whic
a620: 68 20 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65  h the second ele
a630: 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61  ment of the arra
a640: 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65  y.** is the name
a650: 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 61   of the pragma a
a660: 6e 64 20 74 68 65 20 74 68 69 72 64 20 65 6c 65  nd the third ele
a670: 6d 65 6e 74 20 69 73 20 74 68 65 20 61 72 67 75  ment is the argu
a680: 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70  ment to the.** p
a690: 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66  ragma or NULL if
a6a0: 20 74 68 65 20 70 72 61 67 6d 61 20 68 61 73 20   the pragma has 
a6b0: 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54  no argument.  ^T
a6c0: 68 65 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61  he handler for a
a6d0: 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e  n.** [SQLITE_FCN
a6e0: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20  TL_PRAGMA] file 
a6f0: 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69  control can opti
a700: 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20  onally make the 
a710: 66 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a  first element.**
a720: 20 6f 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61   of the char** a
a730: 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f  rgument point to
a740: 20 61 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e   a string obtain
a750: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
a760: 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f  _mprintf()].** o
a770: 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74  r the equivalent
a780: 20 61 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67   and that string
a790: 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65   will become the
a7a0: 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70   result of the p
a7b0: 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20  ragma or.** the 
a7c0: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66  error message if
a7d0: 20 74 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c   the pragma fail
a7e0: 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53  s. ^If the.** [S
a7f0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
a800: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  MA] file control
a810: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
a820: 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e  _NOTFOUND], then
a830: 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41   normal .** [PRA
a840: 47 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20  GMA] processing 
a850: 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20  continues.  ^If 
a860: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  the [SQLITE_FCNT
a870: 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c  L_PRAGMA].** fil
a880: 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e  e control return
a890: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74  s [SQLITE_OK], t
a8a0: 68 65 6e 20 74 68 65 20 70 61 72 73 65 72 20 61  hen the parser a
a8b0: 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a  ssumes that the.
a8c0: 2a 2a 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c  ** VFS has handl
a8d0: 65 64 20 74 68 65 20 50 52 41 47 4d 41 20 69 74  ed the PRAGMA it
a8e0: 73 65 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72  self and the par
a8f0: 73 65 72 20 67 65 6e 65 72 61 74 65 73 20 61 20  ser generates a 
a900: 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65  no-op.** prepare
a910: 64 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 49  d statement.  ^I
a920: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  f the [SQLITE_FC
a930: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
a940: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73   control returns
a950: 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74 20 63  .** any result c
a960: 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ode other than [
a970: 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53  SQLITE_OK] or [S
a980: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c  QLITE_NOTFOUND],
a990: 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74   that means.** t
a9a0: 68 61 74 20 74 68 65 20 56 46 53 20 65 6e 63 6f  hat the VFS enco
a9b0: 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72 6f 72  untered an error
a9c0: 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20   while handling 
a9d0: 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64  the [PRAGMA] and
a9e0: 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74   the.** compilat
a9f0: 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41 47 4d  ion of the PRAGM
aa00: 41 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 20  A fails with an 
aa10: 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51  error.  ^The [SQ
aa20: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
aa30: 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72  A].** file contr
aa40: 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74 68 65  ol occurs at the
aa50: 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72   beginning of pr
aa60: 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 61  agma statement a
aa70: 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a  nalysis and so.*
aa80: 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74 6f 20  * it is able to 
aa90: 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74 2d 69  override built-i
aaa0: 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65  n [PRAGMA] state
aab0: 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ments..**.** <li
aac0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
aad0: 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a  BUSYHANDLER]].**
aae0: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
aaf0: 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d  NTL_BUSYHANDLER]
ab00: 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  .** file-control
ab10: 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20   may be invoked 
ab20: 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 74 68 65  by SQLite on the
ab30: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 68   database file h
ab40: 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79  andle.** shortly
ab50: 20 61 66 74 65 72 20 69 74 20 69 73 20 6f 70 65   after it is ope
ab60: 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ned in order to 
ab70: 70 72 6f 76 69 64 65 20 61 20 63 75 73 74 6f 6d  provide a custom
ab80: 20 56 46 53 20 77 69 74 68 20 61 63 63 65 73 73   VFS with access
ab90: 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65  .** to the conne
aba0: 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64  ctions busy-hand
abb0: 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68  ler callback. Th
abc0: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 66  e argument is of
abd0: 20 74 79 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a   type (void **).
abe0: 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 20 6f 66  ** - an array of
abf0: 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 20 76 61   two (void *) va
ac00: 6c 75 65 73 2e 20 54 68 65 20 66 69 72 73 74 20  lues. The first 
ac10: 28 76 6f 69 64 20 2a 29 20 61 63 74 75 61 6c 6c  (void *) actuall
ac20: 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61  y points.** to a
ac30: 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70   function of typ
ac40: 65 20 28 69 6e 74 20 28 2a 29 28 76 6f 69 64 20  e (int (*)(void 
ac50: 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f  *)). In order to
ac60: 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e   invoke the conn
ac70: 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d  ections.** busy-
ac80: 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 20 66 75  handler, this fu
ac90: 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65  nction should be
aca0: 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 68   invoked with th
acb0: 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a  e second (void *
acc0: 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61  ) in.** the arra
acd0: 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 61 72  y as the only ar
ace0: 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20 72 65  gument. If it re
acf0: 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
ad00: 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61 74 69  then the operati
ad10: 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20  on.** should be 
ad20: 72 65 74 72 69 65 64 2e 20 49 66 20 69 74 20 72  retried. If it r
ad30: 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65  eturns zero, the
ad40: 20 63 75 73 74 6f 6d 20 56 46 53 20 73 68 6f 75   custom VFS shou
ad50: 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a  ld abandon the.*
ad60: 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74  * current operat
ad70: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ion..**.** <li>[
ad80: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45  [SQLITE_FCNTL_TE
ad90: 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20  MPFILENAME]].** 
ada0: 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e  ^Application can
adb0: 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b 53 51 4c   invoke the [SQL
adc0: 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49  ITE_FCNTL_TEMPFI
add0: 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 6f 6e  LENAME] file-con
ade0: 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 20  trol.** to have 
adf0: 53 51 4c 69 74 65 20 67 65 6e 65 72 61 74 65 20  SQLite generate 
ae00: 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66  a.** temporary f
ae10: 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20 74 68  ilename using th
ae20: 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d  e same algorithm
ae30: 20 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65   that is followe
ae40: 64 20 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a  d to generate.**
ae50: 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e   temporary filen
ae60: 61 6d 65 73 20 66 6f 72 20 54 45 4d 50 20 74 61  ames for TEMP ta
ae70: 62 6c 65 73 20 61 6e 64 20 6f 74 68 65 72 20 69  bles and other i
ae80: 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e 20 20 54  nternal uses.  T
ae90: 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73  he.** argument s
aea0: 68 6f 75 6c 64 20 62 65 20 61 20 63 68 61 72 2a  hould be a char*
aeb0: 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65 20  * which will be 
aec0: 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  filled with the 
aed0: 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74  filename.** writ
aee0: 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  ten into memory 
aef0: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
af00: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
af10: 2e 20 20 54 68 65 20 63 61 6c 6c 65 72 20 73 68  .  The caller sh
af20: 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b  ould.** invoke [
af30: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
af40: 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 20 74 6f  on the result to
af50: 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20   avoid a memory 
af60: 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  leak..**.** <li>
af70: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d  [[SQLITE_FCNTL_M
af80: 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68  MAP_SIZE]].** Th
af90: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
afa0: 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20  MMAP_SIZE] file 
afb0: 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20  control is used 
afc0: 74 6f 20 71 75 65 72 79 20 6f 72 20 73 65 74 20  to query or set 
afd0: 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e  the.** maximum n
afe0: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 74  umber of bytes t
aff0: 68 61 74 20 77 69 6c 6c 20 62 65 20 75 73 65 64  hat will be used
b000: 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 70   for memory-mapp
b010: 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61  ed I/O..** The a
b020: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
b030: 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 75 65 20  nter to a value 
b040: 6f 66 20 74 79 70 65 20 73 71 6c 69 74 65 33 5f  of type sqlite3_
b050: 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20 69 73  int64 that.** is
b060: 20 61 6e 20 61 64 76 69 73 6f 72 79 20 6d 61 78   an advisory max
b070: 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62  imum number of b
b080: 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65  ytes in the file
b090: 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 2e 20   to memory map. 
b0a0: 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20   The.** pointer 
b0b0: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77  is overwritten w
b0c0: 69 74 68 20 74 68 65 20 6f 6c 64 20 76 61 6c 75  ith the old valu
b0d0: 65 2e 20 20 54 68 65 20 6c 69 6d 69 74 20 69 73  e.  The limit is
b0e0: 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 69 66 0a   not changed if.
b0f0: 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 72 69  ** the value ori
b100: 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 64 20  ginally pointed 
b110: 74 6f 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  to is negative, 
b120: 61 6e 64 20 73 6f 20 74 68 65 20 63 75 72 72 65  and so the curre
b130: 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 6e  nt limit .** can
b140: 20 62 65 20 71 75 65 72 69 65 64 20 62 79 20 70   be queried by p
b150: 61 73 73 69 6e 67 20 69 6e 20 61 20 70 6f 69 6e  assing in a poin
b160: 74 65 72 20 74 6f 20 61 20 6e 65 67 61 74 69 76  ter to a negativ
b170: 65 20 6e 75 6d 62 65 72 2e 20 20 54 68 69 73 0a  e number.  This.
b180: 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20  ** file-control 
b190: 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c  is used internal
b1a0: 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ly to implement 
b1b0: 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a  [PRAGMA mmap_siz
b1c0: 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  e]..**.** <li>[[
b1d0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41  SQLITE_FCNTL_TRA
b1e0: 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  CE]].** The [SQL
b1f0: 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d  ITE_FCNTL_TRACE]
b200: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 70 72   file control pr
b210: 6f 76 69 64 65 73 20 61 64 76 69 73 6f 72 79 20  ovides advisory 
b220: 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 74  information.** t
b230: 6f 20 74 68 65 20 56 46 53 20 61 62 6f 75 74 20  o the VFS about 
b240: 77 68 61 74 20 74 68 65 20 68 69 67 68 65 72 20  what the higher 
b250: 6c 61 79 65 72 73 20 6f 66 20 74 68 65 20 53 51  layers of the SQ
b260: 4c 69 74 65 20 73 74 61 63 6b 20 61 72 65 20 64  Lite stack are d
b270: 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 73 20 66 69  oing..** This fi
b280: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73  le control is us
b290: 65 64 20 62 79 20 73 6f 6d 65 20 56 46 53 20 61  ed by some VFS a
b2a0: 63 74 69 76 69 74 79 20 74 72 61 63 69 6e 67 20  ctivity tracing 
b2b0: 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65 20  [shims]..** The 
b2c0: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 7a 65  argument is a ze
b2d0: 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
b2e0: 72 69 6e 67 2e 20 20 48 69 67 68 65 72 20 6c 61  ring.  Higher la
b2f0: 79 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20 53  yers in the.** S
b300: 51 4c 69 74 65 20 73 74 61 63 6b 20 6d 61 79 20  QLite stack may 
b310: 67 65 6e 65 72 61 74 65 20 69 6e 73 74 61 6e 63  generate instanc
b320: 65 73 20 6f 66 20 74 68 69 73 20 66 69 6c 65 20  es of this file 
b330: 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a 20 74 68  control if.** th
b340: 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 46 43  e [SQLITE_USE_FC
b350: 4e 54 4c 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69  NTL_TRACE] compi
b360: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69  le-time option i
b370: 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a  s enabled..**.**
b380: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
b390: 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d 0a  NTL_HAS_MOVED]].
b3a0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
b3b0: 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 20  CNTL_HAS_MOVED] 
b3c0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 6e 74  file control int
b3d0: 65 72 70 72 65 74 73 20 69 74 73 20 61 72 67 75  erprets its argu
b3e0: 6d 65 6e 74 20 61 73 20 61 0a 2a 2a 20 70 6f 69  ment as a.** poi
b3f0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
b400: 65 72 20 61 6e 64 20 69 74 20 77 72 69 74 65 73  er and it writes
b410: 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f 20   a boolean into 
b420: 74 68 61 74 20 69 6e 74 65 67 65 72 20 64 65 70  that integer dep
b430: 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68 65  ending.** on whe
b440: 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
b450: 66 69 6c 65 20 68 61 73 20 62 65 65 6e 20 72 65  file has been re
b460: 6e 61 6d 65 64 2c 20 6d 6f 76 65 64 2c 20 6f 72  named, moved, or
b470: 20 64 65 6c 65 74 65 64 20 73 69 6e 63 65 20 69   deleted since i
b480: 74 0a 2a 2a 20 77 61 73 20 66 69 72 73 74 20 6f  t.** was first o
b490: 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  pened..**.** <li
b4a0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
b4b0: 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45  WIN32_SET_HANDLE
b4c0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
b4d0: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45  E_FCNTL_WIN32_SE
b4e0: 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65  T_HANDLE] opcode
b4f0: 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62   is used for deb
b500: 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a  ugging.  This.**
b510: 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74   opcode causes t
b520: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
b530: 6d 65 74 68 6f 64 20 74 6f 20 73 77 61 70 20 74  method to swap t
b540: 68 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 77  he file handle w
b550: 69 74 68 20 74 68 65 20 6f 6e 65 0a 2a 2a 20 70  ith the one.** p
b560: 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65  ointed to by the
b570: 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 2e 20   pArg argument. 
b580: 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79   This capability
b590: 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20   is used during 
b5a0: 74 65 73 74 69 6e 67 0a 2a 2a 20 61 6e 64 20 6f  testing.** and o
b5b0: 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20  nly needs to be 
b5c0: 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53  supported when S
b5d0: 51 4c 49 54 45 5f 54 45 53 54 20 69 73 20 64 65  QLITE_TEST is de
b5e0: 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 2f 75  fined..**.** </u
b5f0: 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
b600: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53  LITE_FCNTL_LOCKS
b610: 54 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20  TATE            
b620: 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
b630: 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58  ITE_GET_LOCKPROX
b640: 59 46 49 4c 45 20 20 20 20 20 20 20 20 20 20 20  YFILE           
b650: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
b660: 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TE_SET_LOCKPROXY
b670: 46 49 4c 45 20 20 20 20 20 20 20 20 20 20 20 20  FILE            
b680: 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
b690: 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20  E_LAST_ERRNO    
b6a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
b6b0: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
b6c0: 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54  _FCNTL_SIZE_HINT
b6d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35                 5
b6e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b6f0: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45  FCNTL_CHUNK_SIZE
b700: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a                6.
b710: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
b720: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45  CNTL_FILE_POINTE
b730: 52 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23  R            7.#
b740: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
b750: 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44  NTL_SYNC_OMITTED
b760: 20 20 20 20 20 20 20 20 20 20 20 20 38 0a 23 64              8.#d
b770: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
b780: 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52  TL_WIN32_AV_RETR
b790: 59 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65  Y          9.#de
b7a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
b7b0: 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 20 20 20  L_PERSIST_WAL   
b7c0: 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 66           10.#def
b7d0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
b7e0: 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 20 20  _OVERWRITE      
b7f0: 20 20 20 20 20 20 20 20 31 31 0a 23 64 65 66 69          11.#defi
b800: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
b810: 56 46 53 4e 41 4d 45 20 20 20 20 20 20 20 20 20  VFSNAME         
b820: 20 20 20 20 20 20 20 31 32 0a 23 64 65 66 69 6e         12.#defin
b830: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  e SQLITE_FCNTL_P
b840: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
b850: 54 45 20 20 20 20 31 33 0a 23 64 65 66 69 6e 65  TE    13.#define
b860: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52   SQLITE_FCNTL_PR
b870: 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20  AGMA            
b880: 20 20 20 20 20 31 34 0a 23 64 65 66 69 6e 65 20       14.#define 
b890: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53  SQLITE_FCNTL_BUS
b8a0: 59 48 41 4e 44 4c 45 52 20 20 20 20 20 20 20 20  YHANDLER        
b8b0: 20 20 20 20 31 35 0a 23 64 65 66 69 6e 65 20 53      15.#define S
b8c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50  QLITE_FCNTL_TEMP
b8d0: 46 49 4c 45 4e 41 4d 45 20 20 20 20 20 20 20 20  FILENAME        
b8e0: 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51     16.#define SQ
b8f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f  LITE_FCNTL_MMAP_
b900: 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20  SIZE            
b910: 20 20 31 38 0a 23 64 65 66 69 6e 65 20 53 51 4c    18.#define SQL
b920: 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 20  ITE_FCNTL_TRACE 
b930: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
b940: 20 31 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   19.#define SQLI
b950: 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56  TE_FCNTL_HAS_MOV
b960: 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ED              
b970: 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  20.#define SQLIT
b980: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 20 20 20 20  E_FCNTL_SYNC    
b990: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
b9a0: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
b9b0: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48  _FCNTL_COMMIT_PH
b9c0: 41 53 45 54 57 4f 20 20 20 20 20 20 20 20 32 32  ASETWO        22
b9d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b9e0: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f  FCNTL_WIN32_SET_
b9f0: 48 41 4e 44 4c 45 20 20 20 20 20 20 20 32 33 0a  HANDLE       23.
ba00: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
ba10: 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a   Mutex Handle.**
ba20: 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f  .** The mutex mo
ba30: 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69  dule within SQLi
ba40: 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69  te defines [sqli
ba50: 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65  te3_mutex] to be
ba60: 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20   an.** abstract 
ba70: 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78  type for a mutex
ba80: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51   object.  The SQ
ba90: 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20  Lite core never 
baa0: 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20  looks.** at the 
bab0: 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65  internal represe
bac0: 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73  ntation of an [s
bad0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20  qlite3_mutex].  
bae0: 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73  It only.** deals
baf0: 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74   with pointers t
bb00: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  o the [sqlite3_m
bb10: 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  utex] object..**
bb20: 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20  .** Mutexes are 
bb30: 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73  created using [s
bb40: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
bb50: 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65  oc()]..*/.typede
bb60: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
bb70: 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d  _mutex sqlite3_m
bb80: 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  utex;../*.** CAP
bb90: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
bba0: 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ace Object.**.**
bbb0: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
bbc0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20  the sqlite3_vfs 
bbd0: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
bbe0: 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74  he interface bet
bbf0: 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69  ween.** the SQLi
bc00: 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20  te core and the 
bc10: 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61  underlying opera
bc20: 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68  ting system.  Th
bc30: 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68  e "vfs".** in th
bc40: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62  e name of the ob
bc50: 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20  ject stands for 
bc60: 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79  "virtual file sy
bc70: 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74  stem".  See.** t
bc80: 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f  he [VFS | VFS do
bc90: 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72  cumentation] for
bca0: 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61   further informa
bcb0: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tion..**.** The 
bcc0: 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65  value of the iVe
bcd0: 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69  rsion field is i
bce0: 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d  nitially 1 but m
bcf0: 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a  ay be larger in.
bd00: 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  ** future versio
bd10: 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41  ns of SQLite.  A
bd20: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73  dditional fields
bd30: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64   may be appended
bd40: 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65   to this.** obje
bd50: 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 72  ct when the iVer
bd60: 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e  sion value is in
bd70: 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74  creased.  Note t
bd80: 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72  hat the structur
bd90: 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69  e.** of the sqli
bda0: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63  te3_vfs object c
bdb0: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72  hanges in the tr
bdc0: 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65  ansaction betwee
bdd0: 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73  n.** SQLite vers
bde0: 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e  ion 3.5.9 and 3.
bdf0: 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 20  6.0 and yet the 
be00: 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77  iVersion field w
be10: 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69  as not.** modifi
be20: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a  ed..**.** The sz
be30: 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20  OsFile field is 
be40: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
be50: 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69  subclassed [sqli
be60: 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72  te3_file].** str
be70: 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74  ucture used by t
be80: 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68  his VFS.  mxPath
be90: 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69  name is the maxi
bea0: 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a  mum length of.**
beb0: 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74   a pathname in t
bec0: 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52  his VFS..**.** R
bed0: 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65  egistered sqlite
bee0: 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72  3_vfs objects ar
bef0: 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b  e kept on a link
bf00: 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62  ed list formed b
bf10: 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70  y.** the pNext p
bf20: 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71  ointer.  The [sq
bf30: 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74  lite3_vfs_regist
bf40: 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  er()].** and [sq
bf50: 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69  lite3_vfs_unregi
bf60: 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  ster()] interfac
bf70: 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c  es manage this l
bf80: 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65  ist.** in a thre
bf90: 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68  ad-safe way.  Th
bfa0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66  e [sqlite3_vfs_f
bfb0: 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ind()] interface
bfc0: 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65  .** searches the
bfd0: 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20   list.  Neither 
bfe0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
bff0: 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53  code nor the VFS
c000: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
c010: 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68  on should use th
c020: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e  e pNext pointer.
c030: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74  .**.** The pNext
c040: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e   field is the on
c050: 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20  ly field in the 
c060: 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73  sqlite3_vfs.** s
c070: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51  tructure that SQ
c080: 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d  Lite will ever m
c090: 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77  odify.  SQLite w
c0a0: 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a  ill only access.
c0b0: 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69  ** or modify thi
c0c0: 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f  s field while ho
c0d0: 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c  lding a particul
c0e0: 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e  ar static mutex.
c0f0: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
c100: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
c110: 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67   modify anything
c120: 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69   within the sqli
c130: 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63  te3_vfs.** objec
c140: 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63  t once the objec
c150: 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73  t has been regis
c160: 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tered..**.** The
c170: 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c   zName field hol
c180: 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ds the name of t
c190: 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20  he VFS module.  
c1a0: 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a  The name must.**
c1b0: 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73   be unique acros
c1c0: 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65  s all VFS module
c1d0: 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74  s..**.** [[sqlit
c1e0: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a  e3_vfs.xOpen]].*
c1f0: 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e  * ^SQLite guaran
c200: 74 65 65 73 20 74 68 61 74 20 74 68 65 20 7a 46  tees that the zF
c210: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
c220: 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73  r to xOpen.** is
c230: 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70   either a NULL p
c240: 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67  ointer or string
c250: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
c260: 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28  m xFullPathname(
c270: 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e  ) with an option
c280: 61 6c 20 73 75 66 66 69 78 20 61 64 64 65 64 2e  al suffix added.
c290: 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78  .** ^If a suffix
c2a0: 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68 65   is added to the
c2b0: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   zFilename param
c2c0: 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a  eter, it will.**
c2d0: 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69   consist of a si
c2e0: 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74  ngle "-" charact
c2f0: 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e  er followed by n
c300: 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31  o more than.** 1
c310: 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61  1 alphanumeric a
c320: 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63  nd/or "-" charac
c330: 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  ters..** ^SQLite
c340: 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e 74   further guarant
c350: 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ees that.** the 
c360: 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76  string will be v
c370: 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67  alid and unchang
c380: 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28  ed until xClose(
c390: 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20  ) is.** called. 
c3a0: 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 70  Because of the p
c3b0: 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65  revious sentence
c3c0: 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  ,.** the [sqlite
c3d0: 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65  3_file] can safe
c3e0: 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74  ly store a point
c3f0: 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c  er to the.** fil
c400: 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64  ename if it need
c410: 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68  s to remember th
c420: 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73  e filename for s
c430: 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49  ome reason..** I
c440: 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  f the zFilename 
c450: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70  parameter to xOp
c460: 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  en is a NULL poi
c470: 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a  nter then xOpen.
c480: 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69  ** must invent i
c490: 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79  ts own temporary
c4a0: 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69   name for the fi
c4b0: 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74  le.  ^Whenever t
c4c0: 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65  he .** xFilename
c4d0: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55   parameter is NU
c4e0: 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20  LL it will also 
c4f0: 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
c500: 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61   the.** flags pa
c510: 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63  rameter will inc
c520: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  lude [SQLITE_OPE
c530: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
c540: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67  ..**.** The flag
c550: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  s argument to xO
c560: 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61  pen() includes a
c570: 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a  ll bits set in.*
c580: 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75  * the flags argu
c590: 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
c5a0: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72  _open_v2()].  Or
c5b0: 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   if [sqlite3_ope
c5c0: 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  n()].** or [sqli
c5d0: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73  te3_open16()] is
c5e0: 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67   used, then flag
c5f0: 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65  s includes at le
c600: 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  ast.** [SQLITE_O
c610: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c  PEN_READWRITE] |
c620: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
c630: 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f  EATE]. .** If xO
c640: 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69  pen() opens a fi
c650: 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65  le read-only the
c660: 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46  n it sets *pOutF
c670: 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75  lags to.** inclu
c680: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  de [SQLITE_OPEN_
c690: 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65  READONLY].  Othe
c6a0: 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46  r bits in *pOutF
c6b0: 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e  lags may be set.
c6c0: 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20  .**.** ^(SQLite 
c6d0: 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e  will also add on
c6e0: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
c6f0: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20  ng flags to the 
c700: 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c  xOpen().** call,
c710: 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
c720: 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f  e object being o
c730: 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  pened:.**.** <ul
c740: 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  >.** <li>  [SQLI
c750: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d  TE_OPEN_MAIN_DB]
c760: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
c770: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52  E_OPEN_MAIN_JOUR
c780: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
c790: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
c7a0: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
c7b0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a  LITE_OPEN_TEMP_J
c7c0: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
c7d0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52   [SQLITE_OPEN_TR
c7e0: 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c  ANSIENT_DB].** <
c7f0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
c800: 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  N_SUBJOURNAL].**
c810: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
c820: 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e  PEN_MASTER_JOURN
c830: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
c840: 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a  LITE_OPEN_WAL].*
c850: 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  * </ul>)^.**.** 
c860: 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70  The file I/O imp
c870: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20  lementation can 
c880: 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74  use the object t
c890: 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20  ype flags to.** 
c8a0: 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 69  change the way i
c8b0: 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c  t deals with fil
c8c0: 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65  es.  For example
c8d0: 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
c8e0: 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f  .** that does no
c8f0: 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61  t care about cra
c900: 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72  sh recovery or r
c910: 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61  ollback might ma
c920: 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f  ke.** the open o
c930: 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65  f a journal file
c940: 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65   a no-op.  Write
c950: 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61  s to this journa
c960: 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20  l would.** also 
c970: 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61  be no-ops, and a
c980: 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65  ny attempt to re
c990: 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77  ad the journal w
c9a0: 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53  ould return.** S
c9b0: 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72  QLITE_IOERR.  Or
c9c0: 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
c9d0: 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e  ion might recogn
c9e0: 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62  ize that a datab
c9f0: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c  ase.** file will
ca00: 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61   be doing page-a
ca10: 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65  ligned sector re
ca20: 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69  ads and writes i
ca30: 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72  n a random.** or
ca40: 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 69  der and set up i
ca50: 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d  ts I/O subsystem
ca60: 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a   accordingly..**
ca70: 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74  .** SQLite might
ca80: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
ca90: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
caa0: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
cab0: 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20  n method:.**.** 
cac0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
cad0: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
cae0: 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e  ONCLOSE].** <li>
caf0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58   [SQLITE_OPEN_EX
cb00: 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c  CLUSIVE].** </ul
cb10: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  >.**.** The [SQL
cb20: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
cb30: 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61  NCLOSE] flag mea
cb40: 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75  ns the file shou
cb50: 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64  ld be.** deleted
cb60: 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73   when it is clos
cb70: 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54  ed.  ^The [SQLIT
cb80: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
cb90: 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65  LOSE].** will be
cba0: 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61   set for TEMP da
cbb0: 74 61 62 61 73 65 73 20 61 6e 64 20 74 68 65 69  tabases and thei
cbc0: 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e  r journals, tran
cbd0: 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73  sient.** databas
cbe0: 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e  es, and subjourn
cbf0: 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  als..**.** ^The 
cc00: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43  [SQLITE_OPEN_EXC
cc10: 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20  LUSIVE] flag is 
cc20: 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63  always used in c
cc30: 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69  onjunction.** wi
cc40: 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  th the [SQLITE_O
cc50: 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67  PEN_CREATE] flag
cc60: 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68  , which are both
cc70: 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61   directly.** ana
cc80: 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f  logous to the O_
cc90: 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54  EXCL and O_CREAT
cca0: 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f   flags of the PO
ccb0: 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50  SIX open().** AP
ccc0: 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f  I.  The SQLITE_O
ccd0: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c  PEN_EXCLUSIVE fl
cce0: 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20  ag, when paired 
ccf0: 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c  with the .** SQL
cd00: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c  ITE_OPEN_CREATE,
cd10: 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69   is used to indi
cd20: 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73  cate that file s
cd30: 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20  hould always.** 
cd40: 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20  be created, and 
cd50: 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72  that it is an er
cd60: 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64  ror if it alread
cd70: 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20  y exists..** It 
cd80: 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73  is <i>not</i> us
cd90: 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  ed to indicate t
cda0: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62  he file should b
cdb0: 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72  e opened .** for
cdc0: 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73   exclusive acces
cdd0: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61  s..**.** ^At lea
cde0: 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65  st szOsFile byte
cdf0: 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20  s of memory are 
ce00: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c  allocated by SQL
ce10: 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74  ite.** to hold t
ce20: 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  he  [sqlite3_fil
ce30: 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 73  e] structure pas
ce40: 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64  sed as the third
ce50: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  .** argument to 
ce60: 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65  xOpen.  The xOpe
ce70: 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f  n method does no
ce80: 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c  t have to.** all
ce90: 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63 74  ocate the struct
cea0: 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a  ure; it should j
ceb0: 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20  ust fill it in. 
cec0: 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68   Note that.** th
ced0: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d  e xOpen method m
cee0: 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c 69  ust set the sqli
cef0: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
cf00: 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61  s to either.** a
cf10: 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f   valid [sqlite3_
cf20: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
cf30: 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20  ct or to NULL.  
cf40: 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a  xOpen must do.**
cf50: 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74 68   this even if th
cf60: 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53  e open fails.  S
cf70: 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74 68  QLite expects th
cf80: 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  at the sqlite3_f
cf90: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20  ile.pMethods.** 
cfa0: 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20  element will be 
cfb0: 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65  valid after xOpe
cfc0: 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72 64  n returns regard
cfd0: 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 63  less of the succ
cfe0: 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72  ess.** or failur
cff0: 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63  e of the xOpen c
d000: 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c  all..**.** [[sql
d010: 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73  ite3_vfs.xAccess
d020: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73  ]].** ^The flags
d030: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63   argument to xAc
d040: 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53  cess() may be [S
d050: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
d060: 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20  STS].** to test 
d070: 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e 63  for the existenc
d080: 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20  e of a file, or 
d090: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52  [SQLITE_ACCESS_R
d0a0: 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20  EADWRITE] to.** 
d0b0: 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66  test whether a f
d0c0: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20  ile is readable 
d0d0: 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72  and writable, or
d0e0: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
d0f0: 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74  READ].** to test
d100: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20   whether a file 
d110: 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64  is at least read
d120: 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65  able.   The file
d130: 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72   can be a.** dir
d140: 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53  ectory..**.** ^S
d150: 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79  QLite will alway
d160: 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65  s allocate at le
d170: 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31  ast mxPathname+1
d180: 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a   bytes for the.*
d190: 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20  * output buffer 
d1a0: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20  xFullPathname.  
d1b0: 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f  The exact size o
d1c0: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66  f the output buf
d1d0: 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70  fer.** is also p
d1e0: 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d  assed as a param
d1f0: 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65  eter to both  me
d200: 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75  thods. If the ou
d210: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69  tput buffer.** i
d220: 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75  s not large enou
d230: 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54  gh, [SQLITE_CANT
d240: 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20  OPEN] should be 
d250: 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20  returned. Since 
d260: 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c  this is.** handl
d270: 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 72  ed as a fatal er
d280: 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76  ror by SQLite, v
d290: 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  fs implementatio
d2a0: 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76  ns should endeav
d2b0: 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74  or.** to prevent
d2c0: 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e 67   this by setting
d2d0: 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61   mxPathname to a
d2e0: 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61   sufficiently la
d2f0: 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  rge value..**.**
d300: 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   The xRandomness
d310: 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43  (), xSleep(), xC
d320: 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e  urrentTime(), an
d330: 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  d xCurrentTimeIn
d340: 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  t64().** interfa
d350: 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69  ces are not stri
d360: 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74  ctly a part of t
d370: 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62  he filesystem, b
d380: 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69  ut they are.** i
d390: 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56  ncluded in the V
d3a0: 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72  FS structure for
d3b0: 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a   completeness..*
d3c0: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
d3d0: 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74  s() function att
d3e0: 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20  empts to return 
d3f0: 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20  nBytes bytes.** 
d400: 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20  of good-quality 
d410: 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20  randomness into 
d420: 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72  zOut.  The retur
d430: 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68  n value is.** th
d440: 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20  e actual number 
d450: 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64  of bytes of rand
d460: 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e  omness obtained.
d470: 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29  .** The xSleep()
d480: 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74   method causes t
d490: 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61  he calling threa
d4a0: 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61  d to sleep for a
d4b0: 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e  t.** least the n
d4c0: 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65  umber of microse
d4d0: 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54  conds given.  ^T
d4e0: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  he xCurrentTime(
d4f0: 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75  ).** method retu
d500: 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79  rns a Julian Day
d510: 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20   Number for the 
d520: 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64  current date and
d530: 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c   time as.** a fl
d540: 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
d550: 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72  ue..** ^The xCur
d560: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20  rentTimeInt64() 
d570: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20  method returns, 
d580: 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74  as an integer, t
d590: 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79  he Julian.** Day
d5a0: 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69   Number multipli
d5b0: 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20 28  ed by 86400000 (
d5c0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69  the number of mi
d5d0: 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a  lliseconds in .*
d5e0: 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29  * a 24-hour day)
d5f0: 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  .  .** ^SQLite w
d600: 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75 72  ill use the xCur
d610: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20  rentTimeInt64() 
d620: 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68  method to get th
d630: 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74  e current.** dat
d640: 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68  e and time if th
d650: 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61  at method is ava
d660: 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72 73  ilable (if iVers
d670: 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20  ion is 2 or .** 
d680: 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65 20  greater and the 
d690: 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72  function pointer
d6a0: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e   is not NULL) an
d6b0: 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b  d will fall back
d6c0: 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54  .** to xCurrentT
d6d0: 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65 6e  ime() if xCurren
d6e0: 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20  tTimeInt64() is 
d6f0: 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a  unavailable..**.
d700: 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73 74  ** ^The xSetSyst
d710: 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79  emCall(), xGetSy
d720: 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20  stemCall(), and 
d730: 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28  xNestSystemCall(
d740: 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
d750: 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20  are not used by 
d760: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e  the SQLite core.
d770: 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c    These optional
d780: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
d790: 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73  provided.** by s
d7a0: 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61 63  ome VFSes to fac
d7b0: 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67 20  ilitate testing 
d7c0: 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e  of the VFS code.
d7d0: 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a   By overriding .
d7e0: 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20  ** system calls 
d7f0: 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75  with functions u
d800: 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c  nder its control
d810: 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d  , a test program
d820: 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65   can.** simulate
d830: 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f   faults and erro
d840: 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61  r conditions tha
d850: 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73  t would otherwis
d860: 65 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a  e be difficult.*
d870: 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20  * or impossible 
d880: 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20  to induce.  The 
d890: 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61  set of system ca
d8a0: 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  lls that can be 
d8b0: 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61  overridden.** va
d8c0: 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46  ries from one VF
d8d0: 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e  S to another, an
d8e0: 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69  d from one versi
d8f0: 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56  on of the same V
d900: 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78  FS to the.** nex
d910: 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  t.  Applications
d920: 20 74 68 61 74 20 75 73 65 20 74 68 65 73 65 20   that use these 
d930: 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74 20  interfaces must 
d940: 62 65 20 70 72 65 70 61 72 65 64 20 66 6f 72 20  be prepared for 
d950: 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66  any.** or all of
d960: 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
d970: 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20  s to be NULL or 
d980: 66 6f 72 20 74 68 65 69 72 20 62 65 68 61 76 69  for their behavi
d990: 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20  or to change.** 
d9a0: 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65  from one release
d9b0: 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41   to the next.  A
d9c0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74  pplications must
d9d0: 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20   not attempt to 
d9e0: 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66  access.** any of
d9f0: 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69   these methods i
da00: 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f  f the iVersion o
da10: 66 20 74 68 65 20 56 46 53 20 69 73 20 6c 65 73  f the VFS is les
da20: 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70  s than 3..*/.typ
da30: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
da40: 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f  te3_vfs sqlite3_
da50: 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69  vfs;.typedef voi
da60: 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63  d (*sqlite3_sysc
da70: 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a  all_ptr)(void);.
da80: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
da90: 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73  fs {.  int iVers
daa0: 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20  ion;            
dab0: 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72  /* Structure ver
dac0: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72  sion number (cur
dad0: 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69  rently 3) */.  i
dae0: 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20  nt szOsFile;    
daf0: 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20          /* Size 
db00: 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71  of subclassed sq
db10: 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20  lite3_file */.  
db20: 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20  int mxPathname; 
db30: 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
db40: 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d  mum file pathnam
db50: 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71  e length */.  sq
db60: 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74  lite3_vfs *pNext
db70: 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72  ;      /* Next r
db80: 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f  egistered VFS */
db90: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
dba0: 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e  Name;       /* N
dbb0: 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74  ame of this virt
dbc0: 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20  ual file system 
dbd0: 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44  */.  void *pAppD
dbe0: 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  ata;          /*
dbf0: 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c   Pointer to appl
dc00: 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63  ication-specific
dc10: 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28   data */.  int (
dc20: 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  *xOpen)(sqlite3_
dc30: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
dc40: 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33   *zName, sqlite3
dc50: 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20  _file*,.        
dc60: 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73         int flags
dc70: 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73  , int *pOutFlags
dc80: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65  );.  int (*xDele
dc90: 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  te)(sqlite3_vfs*
dca0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
dcb0: 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72  ame, int syncDir
dcc0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65  );.  int (*xAcce
dcd0: 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ss)(sqlite3_vfs*
dce0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
dcf0: 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20  ame, int flags, 
dd00: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20  int *pResOut);. 
dd10: 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68   int (*xFullPath
dd20: 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66  name)(sqlite3_vf
dd30: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
dd40: 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c  zName, int nOut,
dd50: 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20   char *zOut);.  
dd60: 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29  void *(*xDlOpen)
dd70: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
dd80: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
dd90: 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a  name);.  void (*
dda0: 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65  xDlError)(sqlite
ddb0: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74  3_vfs*, int nByt
ddc0: 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67  e, char *zErrMsg
ddd0: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44  );.  void (*(*xD
dde0: 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66  lSym)(sqlite3_vf
ddf0: 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20  s*,void*, const 
de00: 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28  char *zSymbol))(
de10: 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a  void);.  void (*
de20: 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  xDlClose)(sqlite
de30: 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a  3_vfs*, void*);.
de40: 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e    int (*xRandomn
de50: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ess)(sqlite3_vfs
de60: 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68  *, int nByte, ch
de70: 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74  ar *zOut);.  int
de80: 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74   (*xSleep)(sqlit
de90: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63  e3_vfs*, int mic
dea0: 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e  roseconds);.  in
deb0: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65  t (*xCurrentTime
dec0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
ded0: 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  double*);.  int 
dee0: 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29  (*xGetLastError)
def0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
df00: 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f  nt, char *);.  /
df10: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
df20: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
df30: 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65  version 1 of the
df40: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
df50: 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69  ct.  ** definiti
df60: 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20  on.  Those that 
df70: 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64  follow are added
df80: 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72   in version 2 or
df90: 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e   later.  */.  in
dfa0: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65  t (*xCurrentTime
dfb0: 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76  Int64)(sqlite3_v
dfc0: 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  fs*, sqlite3_int
dfd0: 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  64*);.  /*.  ** 
dfe0: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
dff0: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
e000: 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65  s 1 and 2 of the
e010: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
e020: 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62  ct..  ** Those b
e030: 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72  elow are for ver
e040: 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74  sion 3 and great
e050: 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28  er..  */.  int (
e060: 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29  *xSetSystemCall)
e070: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
e080: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
e090: 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c  , sqlite3_syscal
e0a0: 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65  l_ptr);.  sqlite
e0b0: 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a  3_syscall_ptr (*
e0c0: 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28  xGetSystemCall)(
e0d0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
e0e0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29  nst char *zName)
e0f0: 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ;.  const char *
e100: 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c  (*xNextSystemCal
e110: 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  l)(sqlite3_vfs*,
e120: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
e130: 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54  me);.  /*.  ** T
e140: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
e150: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73   are in versions
e160: 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20   1 through 3 of 
e170: 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f  the sqlite_vfs o
e180: 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20  bject..  ** New 
e190: 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70  fields may be ap
e1a0: 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65  pended in figure
e1b0: 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20   versions.  The 
e1c0: 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61  iVersion.  ** va
e1d0: 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65  lue will increme
e1e0: 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73  nt whenever this
e1f0: 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a   happens. .  */.
e200: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
e210: 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68  EF: Flags for th
e220: 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65  e xAccess VFS me
e230: 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  thod.**.** These
e240: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
e250: 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61  ts can be used a
e260: 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  s the third para
e270: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20  meter to.** the 
e280: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f  xAccess method o
e290: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66  f an [sqlite3_vf
e2a0: 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79  s] object.  They
e2b0: 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68   determine.** wh
e2c0: 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69  at kind of permi
e2d0: 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65  ssions the xAcce
e2e0: 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f  ss method is loo
e2f0: 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74  king for..** Wit
e300: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
e310: 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63  EXISTS, the xAcc
e320: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69  ess method.** si
e330: 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74  mply checks whet
e340: 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 69  her the file exi
e350: 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c  sts..** With SQL
e360: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
e370: 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73  RITE, the xAcces
e380: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63  s method.** chec
e390: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 6e  ks whether the n
e3a0: 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20 69  amed directory i
e3b0: 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20  s both readable 
e3c0: 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20  and writable.** 
e3d0: 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c  (in other words,
e3e0: 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65   if files can be
e3f0: 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c   added, removed,
e400: 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74   and renamed wit
e410: 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63  hin.** the direc
e420: 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51  tory)..** The SQ
e430: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
e440: 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69  WRITE constant i
e450: 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64  s currently used
e460: 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20   only by the.** 
e470: 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65  [temp_store_dire
e480: 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74  ctory pragma], t
e490: 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64  hough this could
e4a0: 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74   change in a fut
e4b0: 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f  ure.** release o
e4c0: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74  f SQLite..** Wit
e4d0: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
e4e0: 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73  READ, the xAcces
e4f0: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63  s method.** chec
e500: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
e510: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e  ile is readable.
e520: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43    The SQLITE_ACC
e530: 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e  ESS_READ constan
e540: 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c  t is.** currentl
e550: 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68  y unused, though
e560: 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 73 65   it might be use
e570: 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 65  d in a future re
e580: 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69  lease of.** SQLi
e590: 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  te..*/.#define S
e5a0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
e5b0: 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65  STS    0.#define
e5c0: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
e5d0: 45 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20  EADWRITE 1   /* 
e5e0: 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 20 74  Used by PRAGMA t
e5f0: 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
e600: 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ory */.#define S
e610: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
e620: 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e  D      2   /* Un
e630: 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  used */../*.** C
e640: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66  API3REF: Flags f
e650: 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20  or the xShmLock 
e660: 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a  VFS method.**.**
e670: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
e680: 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20  onstants define 
e690: 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b  the various lock
e6a0: 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a  ing operations.*
e6b0: 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65  * allowed by the
e6c0: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
e6d0: 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   of [sqlite3_io_
e6e0: 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a  methods].  The.*
e6f0: 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20  * following are 
e700: 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63  the only legal c
e710: 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66  ombinations of f
e720: 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78  lags to the.** x
e730: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a  ShmLock method:.
e740: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
e750: 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c  i>  SQLITE_SHM_L
e760: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
e770: 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20  _SHARED.** <li> 
e780: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b   SQLITE_SHM_LOCK
e790: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58   | SQLITE_SHM_EX
e7a0: 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20  CLUSIVE.** <li> 
e7b0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
e7c0: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
e7d0: 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20  SHARED.** <li>  
e7e0: 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43  SQLITE_SHM_UNLOC
e7f0: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  K | SQLITE_SHM_E
e800: 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c  XCLUSIVE.** </ul
e810: 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c  >.**.** When unl
e820: 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65  ocking, the same
e830: 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55   SHARED or EXCLU
e840: 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62  SIVE flag must b
e850: 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a  e supplied as.**
e860: 20 77 61 73 20 67 69 76 65 6e 20 6e 6f 20 74 68   was given no th
e870: 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
e880: 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68  lock.  .**.** Th
e890: 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  e xShmLock metho
e8a0: 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e  d can transition
e8b0: 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65   between unlocke
e8c0: 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a  d and SHARED or.
e8d0: 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63  ** between unloc
e8e0: 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56  ked and EXCLUSIV
e8f0: 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72  E.  It cannot tr
e900: 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e  ansition between
e910: 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45   SHARED.** and E
e920: 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65  XCLUSIVE..*/.#de
e930: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
e940: 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23  UNLOCK       1.#
e950: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
e960: 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32  M_LOCK         2
e970: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
e980: 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20  SHM_SHARED      
e990: 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
e9a0: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20  E_SHM_EXCLUSIVE 
e9b0: 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     8../*.** CAPI
e9c0: 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53  3REF: Maximum xS
e9d0: 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a  hmLock index.**.
e9e0: 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20  ** The xShmLock 
e9f0: 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74  method on [sqlit
ea00: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d  e3_io_methods] m
ea10: 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a  ay use values.**
ea20: 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74   between 0 and t
ea30: 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20  his upper bound 
ea40: 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 22 20  as its "offset" 
ea50: 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65  argument..** The
ea60: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c   SQLite core wil
ea70: 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20  l never attempt 
ea80: 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72 65  to acquire or re
ea90: 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20  lease a.** lock 
eaa0: 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 73 20  outside of this 
eab0: 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65  range.*/.#define
eac0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43   SQLITE_SHM_NLOC
ead0: 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a  K        8.../*.
eae0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69  ** CAPI3REF: Ini
eaf0: 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69  tialize The SQLi
eb00: 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a  te Library.**.**
eb10: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
eb20: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
eb30: 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74  ne initializes t
eb40: 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62  he.** SQLite lib
eb50: 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69  rary.  ^The sqli
eb60: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72  te3_shutdown() r
eb70: 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f  outine.** deallo
eb80: 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72  cates any resour
eb90: 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61 6c  ces that were al
eba0: 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74  located by sqlit
ebb0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e  e3_initialize().
ebc0: 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
ebd0: 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 64 20  es are designed 
ebe0: 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73  to aid in proces
ebf0: 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  s initialization
ec00: 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e   and.** shutdown
ec10: 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73   on embedded sys
ec20: 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69  tems.  Workstati
ec30: 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  on applications 
ec40: 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20  using.** SQLite 
ec50: 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20  normally do not 
ec60: 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65  need to invoke e
ec70: 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 72  ither of these r
ec80: 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41  outines..**.** A
ec90: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
eca0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
ecb0: 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20   an "effective" 
ecc0: 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a  call if it is.**
ecd0: 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   the first time 
ece0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
ecf0: 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20  ze() is invoked 
ed00: 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74  during the lifet
ed10: 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72  ime of.** the pr
ed20: 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20  ocess, or if it 
ed30: 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69 6d  is the first tim
ed40: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
ed50: 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
ed60: 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  d.** following a
ed70: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
ed80: 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28  _shutdown().  ^(
ed90: 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76  Only an effectiv
eda0: 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c  e call.** of sql
edb0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
edc0: 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69  ) does any initi
edd0: 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20  alization.  All 
ede0: 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61  other calls.** a
edf0: 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  re harmless no-o
ee00: 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61  ps.)^.**.** A ca
ee10: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
ee20: 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22  utdown() is an "
ee30: 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20  effective" call 
ee40: 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72  if it is the fir
ee50: 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71  st.** call to sq
ee60: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
ee70: 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20   since the last 
ee80: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
ee90: 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a  ze().  ^(Only.**
eea0: 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61   an effective ca
eeb0: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
eec0: 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e  utdown() does an
eed0: 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69  y deinitializati
eee0: 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72  on..** All other
eef0: 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20   valid calls to 
ef00: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
ef10: 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20  () are harmless 
ef20: 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  no-ops.)^.**.** 
ef30: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
ef40: 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61  ialize() interfa
ef50: 63 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65  ce is threadsafe
ef60: 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68  , but sqlite3_sh
ef70: 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e  utdown().** is n
ef80: 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ot.  The sqlite3
ef90: 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65  _shutdown() inte
efa0: 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20  rface must only 
efb0: 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61  be called from a
efc0: 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61  .** single threa
efd0: 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61  d.  All open [da
efe0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
eff0: 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73  ns] must be clos
f000: 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74  ed and all.** ot
f010: 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75  her SQLite resou
f020: 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 65 61  rces must be dea
f030: 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74  llocated prior t
f040: 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71  o invoking.** sq
f050: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
f060: 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74  ..**.** Among ot
f070: 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c  her things, ^sql
f080: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f090: 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a  ) will invoke.**
f0a0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
f0b0: 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20  ().  Similarly, 
f0c0: 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  ^sqlite3_shutdow
f0d0: 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f  n().** will invo
f0e0: 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  ke sqlite3_os_en
f0f0: 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  d()..**.** ^The 
f100: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
f110: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  ze() routine ret
f120: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
f130: 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20   on success..** 
f140: 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61  ^If for some rea
f150: 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69  son, sqlite3_ini
f160: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61  tialize() is una
f170: 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a  ble to initializ
f180: 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79  e.** the library
f190: 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20   (perhaps it is 
f1a0: 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
f1b0: 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f  te a needed reso
f1c0: 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20  urce such.** as 
f1d0: 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75  a mutex) it retu
f1e0: 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  rns an [error co
f1f0: 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  de] other than [
f200: 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a  SQLITE_OK]..**.*
f210: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
f220: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
f230: 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e  ine is called in
f240: 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79  ternally by many
f250: 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65   other.** SQLite
f260: 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74   interfaces so t
f270: 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69  hat an applicati
f280: 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20  on usually does 
f290: 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69  not need to.** i
f2a0: 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e  nvoke sqlite3_in
f2b0: 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63  itialize() direc
f2c0: 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  tly.  For exampl
f2d0: 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  e, [sqlite3_open
f2e0: 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c  ()].** calls sql
f2f0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f300: 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20  ) so the SQLite 
f310: 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20  library will be 
f320: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
f330: 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65   initialized whe
f340: 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  n [sqlite3_open(
f350: 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20  )] is called if 
f360: 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e  it has not be in
f370: 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72  itialized.** alr
f380: 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c  eady.  ^However,
f390: 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   if SQLite is co
f3a0: 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20  mpiled with the 
f3b0: 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54  [SQLITE_OMIT_AUT
f3c0: 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c  OINIT].** compil
f3d0: 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74  e-time option, t
f3e0: 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69  hen the automati
f3f0: 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  c calls to sqlit
f400: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a  e3_initialize().
f410: 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61  ** are omitted a
f420: 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  nd the applicati
f430: 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c  on must call sql
f440: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f450: 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72  ) directly.** pr
f460: 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79  ior to using any
f470: 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
f480: 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61  terface.  For ma
f490: 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74  ximum portabilit
f4a0: 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f  y,.** it is reco
f4b0: 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70  mmended that app
f4c0: 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73  lications always
f4d0: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
f4e0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20  initialize().** 
f4f0: 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74  directly prior t
f500: 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65  o using any othe
f510: 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
f520: 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65  ce.  Future rele
f530: 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ases.** of SQLit
f540: 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 68  e may require th
f550: 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  is.  In other wo
f560: 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f  rds, the behavio
f570: 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77  r exhibited.** w
f580: 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f  hen SQLite is co
f590: 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c  mpiled with [SQL
f5a0: 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49  ITE_OMIT_AUTOINI
f5b0: 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20  T] might become 
f5c0: 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62  the.** default b
f5d0: 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20  ehavior in some 
f5e0: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
f5f0: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
f600: 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  The sqlite3_os_i
f610: 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f  nit() routine do
f620: 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73  es operating-sys
f630: 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20  tem specific.** 
f640: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f  initialization o
f650: 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  f the SQLite lib
f660: 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74  rary.  The sqlit
f670: 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72  e3_os_end().** r
f680: 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68  outine undoes th
f690: 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69  e effect of sqli
f6a0: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20  te3_os_init().  
f6b0: 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a  Typical tasks.**
f6c0: 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68   performed by th
f6d0: 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63  ese routines inc
f6e0: 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  lude allocation 
f6f0: 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a  or deallocation.
f700: 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 73  ** of static res
f710: 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69  ources, initiali
f720: 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c  zation of global
f730: 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73   variables,.** s
f740: 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 61  etting up a defa
f750: 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
f760: 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74  ] module, or set
f770: 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66  ting up.** a def
f780: 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69  ault configurati
f790: 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  on using [sqlite
f7a0: 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a  3_config()]..**.
f7b0: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
f7c0: 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20  on should never 
f7d0: 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71  invoke either sq
f7e0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a  lite3_os_init().
f7f0: 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  ** or sqlite3_os
f800: 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e  _end() directly.
f810: 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f    The applicatio
f820: 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e  n should only in
f830: 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  voke.** sqlite3_
f840: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64  initialize() and
f850: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
f860: 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65  n().  The sqlite
f870: 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69  3_os_init().** i
f880: 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c  nterface is call
f890: 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ed automatically
f8a0: 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   by sqlite3_init
f8b0: 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20  ialize() and.** 
f8c0: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
f8d0: 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71   is called by sq
f8e0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
f8f0: 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a  .  Appropriate.*
f900: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
f910: 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  s for sqlite3_os
f920: 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69  _init() and sqli
f930: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
f940: 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53  are built into S
f950: 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 73  QLite when it is
f960: 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e   compiled for Un
f970: 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20  ix, Windows, or 
f980: 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63  OS/2..** When [c
f990: 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62  ustom builds | b
f9a0: 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70  uilt for other p
f9b0: 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73  latforms].** (us
f9c0: 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ing the [SQLITE_
f9d0: 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70  OS_OTHER=1] comp
f9e0: 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69  ile-time.** opti
f9f0: 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 74  on) the applicat
fa00: 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20  ion must supply 
fa10: 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65  a suitable imple
fa20: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a  mentation for.**
fa30: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
fa40: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
fa50: 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70  s_end().  An app
fa60: 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65  lication-supplie
fa70: 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  d.** implementat
fa80: 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f  ion of sqlite3_o
fa90: 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69  s_init() or sqli
faa0: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
fab0: 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c  must return [SQL
fac0: 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
fad0: 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65  ss and some othe
fae0: 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75  r [error code] u
faf0: 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a  pon.** failure..
fb00: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 69  */.int sqlite3_i
fb10: 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b  nitialize(void);
fb20: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75  .int sqlite3_shu
fb30: 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74  tdown(void);.int
fb40: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
fb50: 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69  (void);.int sqli
fb60: 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29  te3_os_end(void)
fb70: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
fb80: 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54  F: Configuring T
fb90: 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72  he SQLite Librar
fba0: 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  y.**.** The sqli
fbb0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  te3_config() int
fbc0: 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74  erface is used t
fbd0: 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f  o make global co
fbe0: 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63  nfiguration.** c
fbf0: 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65  hanges to SQLite
fc00: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e   in order to tun
fc10: 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20  e SQLite to the 
fc20: 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f  specific needs o
fc30: 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  f.** the applica
fc40: 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75  tion.  The defau
fc50: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
fc60: 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
fc70: 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c  for most.** appl
fc80: 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20  ications and so 
fc90: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
fca0: 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65  usually not nece
fcb0: 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a  ssary.  It is.**
fcc0: 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70   provided to sup
fcd0: 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69 63  port rare applic
fce0: 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73  ations with unus
fcf0: 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a  ual needs..**.**
fd00: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   The sqlite3_con
fd10: 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
fd20: 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66  is not threadsaf
fd30: 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  e.  The applicat
fd40: 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75  ion.** must insu
fd50: 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72  re that no other
fd60: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
fd70: 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62  es are invoked b
fd80: 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61  y other.** threa
fd90: 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33  ds while sqlite3
fda0: 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e  _config() is run
fdb0: 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72 6d 6f  ning.  Furthermo
fdc0: 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  re, sqlite3_conf
fdd0: 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79  ig().** may only
fde0: 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f   be invoked prio
fdf0: 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69  r to library ini
fe00: 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e  tialization usin
fe10: 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e  g.** [sqlite3_in
fe20: 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61  itialize()] or a
fe30: 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79  fter shutdown by
fe40: 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
fe50: 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71  wn()]..** ^If sq
fe60: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
fe70: 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b  s called after [
fe80: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
fe90: 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 65  ze()] and before
fea0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  .** [sqlite3_shu
feb0: 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 74  tdown()] then it
fec0: 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c   will return SQL
fed0: 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e  ITE_MISUSE..** N
fee0: 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68  ote, however, th
fef0: 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66  at ^sqlite3_conf
ff00: 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c  ig() can be call
ff10: 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  ed as part of th
ff20: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
ff30: 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63  ion of an applic
ff40: 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73  ation-defined [s
ff50: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
ff60: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  ]..**.** The fir
ff70: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  st argument to s
ff80: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
ff90: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  is an integer.**
ffa0: 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   [configuration 
ffb0: 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74  option] that det
ffc0: 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20  ermines.** what 
ffd0: 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69  property of SQLi
ffe0: 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66  te is to be conf
fff0: 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75  igured.  Subsequ
10000 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a  ent arguments.**
10010 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20   vary depending 
10020 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 72  on the [configur
10030 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a  ation option].**
10040 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
10050 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57  gument..**.** ^W
10060 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74  hen a configurat
10070 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  ion option is se
10080 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  t, sqlite3_confi
10090 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  g() returns [SQL
100a0 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20  ITE_OK]..** ^If 
100b0 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e  the option is un
100c0 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20  known or SQLite 
100d0 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74  is unable to set
100e0 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74   the option.** t
100f0 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65  hen this routine
10100 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a   returns a non-z
10110 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
10120 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
10130 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e  _config(int, ...
10140 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
10150 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61  EF: Configure da
10160 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
10170 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ns.**.** The sql
10180 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
10190 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
101a0 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69  ed to make confi
101b0 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e  guration.** chan
101c0 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61  ges to a [databa
101d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
101e0 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69   The interface i
101f0 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20  s similar to.** 
10200 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
10210 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74  )] except that t
10220 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79  he changes apply
10230 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20   to a single.** 
10240 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
10250 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64  tion] (specified
10260 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
10270 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54  gument)..**.** T
10280 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
10290 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62  nt to sqlite3_db
102a0 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29  _config(D,V,...)
102b0 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c    is the.** [SQL
102c0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
102d0 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75  KASIDE | configu
102e0 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61  ration verb] - a
102f0 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a  n integer code .
10300 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74 65  ** that indicate
10310 73 20 77 68 61 74 20 61 73 70 65 63 74 20 6f 66  s what aspect of
10320 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
10330 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65  onnection] is be
10340 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a  ing configured..
10350 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61 72  ** Subsequent ar
10360 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70  guments vary dep
10370 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f  ending on the co
10380 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62  nfiguration verb
10390 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74  ..**.** ^Calls t
103a0 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  o sqlite3_db_con
103b0 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c  fig() return SQL
103c0 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e  ITE_OK if and on
103d0 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c  ly if.** the cal
103e0 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  l is considered 
103f0 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69  successful..*/.i
10400 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  nt sqlite3_db_co
10410 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69  nfig(sqlite3*, i
10420 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  nt op, ...);../*
10430 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
10440 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
10450 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41  Routines.**.** A
10460 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
10470 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  is object define
10480 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  s the interface 
10490 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a  between SQLite.*
104a0 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20  * and low-level 
104b0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
104c0 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  n routines..**.*
104d0 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73  * This object is
104e0 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e   used in only on
104f0 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53  e place in the S
10500 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
10510 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  .** A pointer to
10520 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
10530 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74  this object is t
10540 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  he argument to.*
10550 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
10560 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f  g()] when the co
10570 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
10580 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  on is.** [SQLITE
10590 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20  _CONFIG_MALLOC] 
105a0 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
105b0 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a  G_GETMALLOC].  .
105c0 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20 61  ** By creating a
105d0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
105e0 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64  is object.** and
105f0 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b   passing it to [
10600 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
10610 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
10620 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e  ALLOC]).** durin
10630 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c  g configuration,
10640 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
10650 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61  can specify an a
10660 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65  lternative.** me
10670 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
10680 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51  subsystem for SQ
10690 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20  Lite to use for 
106a0 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79  all of its.** dy
106b0 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65  namic memory nee
106c0 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  ds..**.** Note t
106d0 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73  hat SQLite comes
106e0 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62   with several [b
106f0 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
10700 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68  llocators].** th
10710 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c 79  at are perfectly
10720 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 68   adequate for th
10730 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d  e overwhelming m
10740 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69  ajority of appli
10750 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74  cations.** and t
10760 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20  hat this object 
10770 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74  is only useful t
10780 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74  o a tiny minorit
10790 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
107a0 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61  s.** with specia
107b0 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  lized memory all
107c0 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d  ocation requirem
107d0 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65  ents.  This obje
107e0 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73  ct is.** also us
107f0 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
10800 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f  g of SQLite in o
10810 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 20  rder to specify 
10820 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a  an alternative.*
10830 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
10840 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65  or that simulate
10850 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d  s memory out-of-
10860 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e  memory condition
10870 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f  s in.** order to
10880 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51 4c   verify that SQL
10890 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 61  ite recovers gra
108a0 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63  cefully from suc
108b0 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e  h.** conditions.
108c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c  .**.** The xMall
108d0 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e  oc, xRealloc, an
108e0 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20  d xFree methods 
108f0 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74  must work like t
10900 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20  he.** malloc(), 
10910 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72  realloc() and fr
10920 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66  ee() functions f
10930 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64  rom the standard
10940 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e   C library..** ^
10950 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65  SQLite guarantee
10960 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e  s that the secon
10970 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
10980 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77   xRealloc is alw
10990 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74 75  ays a value retu
109a0 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72 20  rned by a prior 
109b0 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70  call to xRoundup
109c0 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68  ..**.** xSize sh
109d0 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20  ould return the 
109e0 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
109f0 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
10a00 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75  ation.** previou
10a10 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  sly obtained fro
10a20 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65  m xMalloc or xRe
10a30 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f  alloc.  The allo
10a40 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73  cated size.** is
10a50 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74   always at least
10a60 20 61 73 20 62 69 67 20 61 73 20 74 68 65 20 72   as big as the r
10a70 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 62 75  equested size bu
10a80 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e  t may be larger.
10a90 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e  .**.** The xRoun
10aa0 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72  dup method retur
10ab0 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65  ns what would be
10ac0 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   the allocated s
10ad0 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f  ize of.** a memo
10ae0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69  ry allocation gi
10af0 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72  ven a particular
10b00 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e   requested size.
10b10 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a    Most memory.**
10b20 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e   allocators roun
10b30 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  d up memory allo
10b40 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74  cations at least
10b50 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c   to the next mul
10b60 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20  tiple.** of 8.  
10b70 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20  Some allocators 
10b80 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61  round up to a la
10b90 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72  rger multiple or
10ba0 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32   to a power of 2
10bb0 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72  ..** Every memor
10bc0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71  y allocation req
10bd0 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74  uest coming in t
10be0 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f  hrough [sqlite3_
10bf0 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20  malloc()].** or 
10c00 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
10c10 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20  ()] first calls 
10c20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52  xRoundup.  If xR
10c30 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30  oundup returns 0
10c40 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65  , .** that cause
10c50 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  s the correspond
10c60 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ing memory alloc
10c70 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a  ation to fail..*
10c80 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d  *.** The xInit m
10c90 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65  ethod initialize
10ca0 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  s the memory all
10cb0 6f 63 61 74 6f 72 2e 20 20 46 6f 72 20 65 78 61  ocator.  For exa
10cc0 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68  mple,.** it migh
10cd0 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72  t allocate any r
10ce0 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f  equire mutexes o
10cf0 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74  r initialize int
10d00 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74  ernal data.** st
10d10 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78  ructures.  The x
10d20 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20  Shutdown method 
10d30 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69  is invoked (indi
10d40 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73  rectly) by.** [s
10d50 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
10d60 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65  )] and should de
10d70 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73  allocate any res
10d80 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a  ources acquired.
10d90 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68  ** by xInit.  Th
10da0 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74  e pAppData point
10db0 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68  er is used as th
10dc0 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72  e only parameter
10dd0 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64   to.** xInit and
10de0 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a   xShutdown..**.*
10df0 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74  * SQLite holds t
10e00 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58  he [SQLITE_MUTEX
10e10 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20  _STATIC_MASTER] 
10e20 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e  mutex when it in
10e30 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e  vokes.** the xIn
10e40 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68  it method, so th
10e50 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e  e xInit method n
10e60 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61  eed not be threa
10e70 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78  dsafe.  The.** x
10e80 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20  Shutdown method 
10e90 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66  is only called f
10ea0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  rom [sqlite3_shu
10eb0 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64  tdown()] so it d
10ec0 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20  oes.** not need 
10ed0 74 6f 20 62 65 20 74 68 72 65 61 64 73 61 66 65  to be threadsafe
10ee0 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c   either.  For al
10ef0 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c  l other methods,
10f00 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73   SQLite.** holds
10f10 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54   the [SQLITE_MUT
10f20 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d  EX_STATIC_MEM] m
10f30 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20  utex as long as 
10f40 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  the.** [SQLITE_C
10f50 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
10f60 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
10f70 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20  ption is turned 
10f80 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20  on (which.** it 
10f90 69 73 20 62 79 20 64 65 66 61 75 6c 74 29 20 61  is by default) a
10fa0 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64  nd so the method
10fb0 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61  s are automatica
10fc0 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a  lly serialized..
10fd0 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b  ** However, if [
10fe0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
10ff0 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69 73 61  MSTATUS] is disa
11000 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f  bled, then the o
11010 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20  ther.** methods 
11020 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61  must be threadsa
11030 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20  fe or else make 
11040 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67  their own arrang
11050 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65  ements for.** se
11060 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a  rialization..**.
11070 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e  ** SQLite will n
11080 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69  ever invoke xIni
11090 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  t() more than on
110a0 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e  ce without an in
110b0 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c  tervening.** cal
110c0 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29  l to xShutdown()
110d0 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
110e0 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  uct sqlite3_mem_
110f0 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f  methods sqlite3_
11100 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72  mem_methods;.str
11110 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  uct sqlite3_mem_
11120 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64  methods {.  void
11130 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74   *(*xMalloc)(int
11140 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65  );         /* Me
11150 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
11160 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  function */.  vo
11170 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64  id (*xFree)(void
11180 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  *);          /* 
11190 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c  Free a prior all
111a0 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  ocation */.  voi
111b0 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76  d *(*xRealloc)(v
111c0 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52  oid*,int);  /* R
111d0 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74  esize an allocat
111e0 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ion */.  int (*x
111f0 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20  Size)(void*);   
11200 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72          /* Retur
11210 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e  n the size of an
11220 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
11230 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29   int (*xRoundup)
11240 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20  (int);          
11250 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75  /* Round up requ
11260 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f  est size to allo
11270 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20  cation size */. 
11280 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f   int (*xInit)(vo
11290 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20  id*);           
112a0 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68  /* Initialize th
112b0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
112c0 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78  or */.  void (*x
112d0 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29  Shutdown)(void*)
112e0 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74  ;      /* Deinit
112f0 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  ialize the memor
11300 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20  y allocator */. 
11310 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b   void *pAppData;
11320 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
11330 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78  /* Argument to x
11340 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 74  Init() and xShut
11350 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  down() */.};../*
11360 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
11370 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69  nfiguration Opti
11380 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ons.** KEYWORDS:
11390 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   {configuration 
113a0 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68  option}.**.** Th
113b0 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
113c0 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  e the available 
113d0 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72  integer configur
113e0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68  ation options th
113f0 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73  at.** can be pas
11400 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74  sed as the first
11410 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
11420 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
11430 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
11440 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75  *.** New configu
11450 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
11460 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
11470 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
11480 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69  f SQLite..** Exi
11490 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  sting configurat
114a0 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68  ion options migh
114b0 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65  t be discontinue
114c0 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  d.  Applications
114d0 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b  .** should check
114e0 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65   the return code
114f0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63   from [sqlite3_c
11500 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65  onfig()] to make
11510 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68   sure that.** th
11520 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20  e call worked.  
11530 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  The [sqlite3_con
11540 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
11550 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a   will return a.*
11560 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  * non-zero [erro
11570 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73  r code] if a dis
11580 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73  continued or uns
11590 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75  upported configu
115a0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a  ration option.**
115b0 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
115c0 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c  ** <dl>.** [[SQL
115d0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
115e0 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51  ETHREAD]] <dt>SQ
115f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
11600 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  LETHREAD</dt>.**
11610 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
11620 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
11630 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
11640 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
11650 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
11660 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65   mode] to Single
11670 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68  -thread.  In oth
11680 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73  er words, it dis
11690 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74  ables.** all mut
116a0 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53  exing and puts S
116b0 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64  QLite into a mod
116c0 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f  e where it can o
116d0 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62  nly be used.** b
116e0 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61  y a single threa
116f0 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20  d.   ^If SQLite 
11700 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
11710 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
11720 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
11730 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
11740 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
11750 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
11760 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
11770 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b   to change the [
11780 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
11790 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74  from its default
117a0 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e  .** value of Sin
117b0 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73  gle-thread and s
117c0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
117d0 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
117e0 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52   .** [SQLITE_ERR
117f0 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
11800 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
11810 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
11820 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  D.** configurati
11830 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a  on option.</dd>.
11840 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
11850 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
11860 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
11870 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
11880 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
11890 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
118a0 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
118b0 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
118c0 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
118d0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
118e0 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e  to Multi-thread.
118f0 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
11900 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a  , it disables.**
11910 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61   mutexing on [da
11920 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11930 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  n] and [prepared
11940 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
11950 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  cts..** The appl
11960 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f  ication is respo
11970 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61  nsible for seria
11980 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f  lizing access to
11990 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
119a0 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b  nnections] and [
119b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
119c0 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72  nts].  But other
119d0 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20   mutexes.** are 
119e0 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20  enabled so that 
119f0 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73  SQLite will be s
11a00 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20  afe to use in a 
11a10 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a  multi-threaded.*
11a20 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73  * environment as
11a30 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20   long as no two 
11a40 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 20  threads attempt 
11a50 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a  to use the same.
11a60 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
11a70 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20  nection] at the 
11a80 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20  same time.  ^If 
11a90 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
11aa0 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
11ab0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
11ac0 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
11ad0 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
11ae0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
11af0 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
11b00 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74  ossible to set t
11b10 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20  he Multi-thread 
11b20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
11b30 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
11b40 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20  _config()] will 
11b50 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
11b60 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20  RROR] if called 
11b70 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49  with the.** SQLI
11b80 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
11b90 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74  HREAD configurat
11ba0 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
11bb0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
11bc0 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
11bd0 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
11be0 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
11bf0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
11c00 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
11c10 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
11c20 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
11c30 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
11c40 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
11c50 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e  o Serialized. In
11c60 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
11c70 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65  is option enable
11c80 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73  s.** all mutexes
11c90 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72   including the r
11ca0 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65  ecursive.** mute
11cb0 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  xes on [database
11cc0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
11cd0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
11ce0 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
11cf0 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28  * In this mode (
11d00 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66  which is the def
11d10 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65  ault when SQLite
11d20 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
11d30 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  h.** [SQLITE_THR
11d40 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20  EADSAFE=1]) the 
11d50 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
11d60 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61  ill itself seria
11d70 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74  lize access.** t
11d80 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  o [database conn
11d90 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72  ections] and [pr
11da0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
11db0 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a  s] so that the.*
11dc0 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  * application is
11dd0 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65   free to use the
11de0 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
11df0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74  connection] or t
11e00 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70  he.** same [prep
11e10 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
11e20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72  in different thr
11e30 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65  eads at the same
11e40 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51   time..** ^If SQ
11e50 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
11e60 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
11e70 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
11e80 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
11e90 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
11ea0 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
11eb0 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
11ec0 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  sible to set the
11ed0 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   Serialized [thr
11ee0 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64  eading mode] and
11ef0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
11f00 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  fig()] will retu
11f10 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
11f20 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68  ] if called with
11f30 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43   the.** SQLITE_C
11f40 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
11f50 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
11f60 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
11f70 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
11f80 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53  G_MALLOC]] <dt>S
11f90 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
11fa0 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOC</dt>.** <dd>
11fb0 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
11fc0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
11fd0 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
11fe0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
11ff0 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
12000 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
12010 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
12020 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e  re.  The argumen
12030 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61  t specifies.** a
12040 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c  lternative low-l
12050 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  evel memory allo
12060 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20  cation routines 
12070 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c  to be used in pl
12080 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65  ace of.** the me
12090 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
120a0 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69  routines built i
120b0 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53  nto SQLite.)^ ^S
120c0 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69  QLite makes.** i
120d0 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
120e0 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65  opy of the conte
120f0 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  nt of the [sqlit
12100 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
12110 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66  structure.** bef
12120 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ore the [sqlite3
12130 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20  _config()] call 
12140 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a  returns.</dd>.**
12150 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
12160 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20  FIG_GETMALLOC]] 
12170 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
12180 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  G_GETMALLOC</dt>
12190 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
121a0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
121b0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
121c0 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
121d0 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
121e0 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
121f0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
12200 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
12210 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
12220 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74  thods].** struct
12230 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69  ure is filled wi
12240 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79  th the currently
12250 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20   defined memory 
12260 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
12270 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f  nes.)^.** This o
12280 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
12290 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68  d to overload th
122a0 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79  e default memory
122b0 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72   allocation.** r
122c0 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77  outines with a w
122d0 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d 75  rapper that simu
122e0 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61  lations memory a
122f0 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72  llocation failur
12300 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d  e or.** tracks m
12310 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72  emory usage, for
12320 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a   example. </dd>.
12330 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
12340 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
12350 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
12360 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64  FIG_MEMSTATUS</d
12370 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
12380 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69   option takes si
12390 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66  ngle argument of
123a0 20 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 65 72   type int, inter
123b0 70 72 65 74 65 64 20 61 73 20 61 20 0a 2a 2a 20  preted as a .** 
123c0 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65  boolean, which e
123d0 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
123e0 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f  es the collectio
123f0 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  n of memory allo
12400 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69  cation .** stati
12410 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65  stics. ^(When me
12420 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12430 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64  statistics are d
12440 69 73 61 62 6c 65 64 2c 20 74 68 65 20 0a 2a 2a  isabled, the .**
12450 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74   following SQLit
12460 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 63  e interfaces bec
12470 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f  ome non-operatio
12480 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a  nal:.**   <ul>.*
12490 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
124a0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
124b0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
124c0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
124d0 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  ater()].**   <li
124e0 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  > [sqlite3_soft_
124f0 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a  heap_limit64()].
12500 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
12510 65 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20  e3_status()].** 
12520 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65    </ul>)^.** ^Me
12530 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12540 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 65  statistics are e
12550 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  nabled by defaul
12560 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20  t unless SQLite 
12570 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77  is.** compiled w
12580 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41  ith [SQLITE_DEFA
12590 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30  ULT_MEMSTATUS]=0
125a0 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d   in which case m
125b0 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
125c0 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
125d0 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  re disabled by d
125e0 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e  efault..** </dd>
125f0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
12600 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 5d  CONFIG_SCRATCH]]
12610 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
12620 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a  IG_SCRATCH</dt>.
12630 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
12640 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
12650 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62   static memory b
12660 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74  uffer that SQLit
12670 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a  e can use for.**
12680 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e   scratch memory.
12690 20 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65    There are thre
126a0 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41 20  e arguments:  A 
126b0 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74  pointer an 8-byt
126c0 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d  e.** aligned mem
126d0 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20  ory buffer from 
126e0 77 68 69 63 68 20 74 68 65 20 73 63 72 61 74 63  which the scratc
126f0 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69  h allocations wi
12700 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20  ll be.** drawn, 
12710 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68  the size of each
12720 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
12730 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64  ion (sz),.** and
12740 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
12750 62 65 72 20 6f 66 20 73 63 72 61 74 63 68 20 61  ber of scratch a
12760 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 20  llocations (N). 
12770 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d   The sz.** argum
12780 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d 75  ent must be a mu
12790 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 0a 2a 2a  ltiple of 16..**
127a0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
127b0 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f  ent must be a po
127c0 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79  inter to an 8-by
127d0 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65  te aligned buffe
127e0 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74  r.** of at least
127f0 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d   sz*N bytes of m
12800 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  emory..** ^SQLit
12810 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f  e will use no mo
12820 72 65 20 74 68 61 6e 20 74 77 6f 20 73 63 72 61  re than two scra
12830 74 63 68 20 62 75 66 66 65 72 73 20 70 65 72 20  tch buffers per 
12840 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e  thread.  So.** N
12850 20 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20 74   should be set t
12860 6f 20 74 77 69 63 65 20 74 68 65 20 65 78 70 65  o twice the expe
12870 63 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  cted maximum num
12880 62 65 72 20 6f 66 20 74 68 72 65 61 64 73 2e 0a  ber of threads..
12890 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
128a0 6e 65 76 65 72 20 72 65 71 75 69 72 65 20 61 20  never require a 
128b0 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20 74  scratch buffer t
128c0 68 61 74 20 69 73 20 6d 6f 72 65 20 74 68 61 6e  hat is more than
128d0 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65 20   6.** times the 
128e0 64 61 74 61 62 61 73 65 20 70 61 67 65 20 73 69  database page si
128f0 7a 65 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 6e  ze. ^If SQLite n
12900 65 65 64 73 20 6e 65 65 64 73 20 61 64 64 69 74  eeds needs addit
12910 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68  ional.** scratch
12920 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77   memory beyond w
12930 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20  hat is provided 
12940 62 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75 72  by this configur
12950 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68  ation option, th
12960 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  en .** [sqlite3_
12970 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62  malloc()] will b
12980 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
12990 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64   the memory need
129a0 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ed.</dd>.**.** [
129b0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
129c0 41 47 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53  AGECACHE]] <dt>S
129d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
129e0 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  ECACHE</dt>.** <
129f0 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
12a00 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
12a10 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
12a20 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61  r that SQLite ca
12a30 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65  n use for.** the
12a40 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63   database page c
12a50 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64 65  ache with the de
12a60 66 61 75 6c 74 20 70 61 67 65 20 63 61 63 68 65  fault page cache
12a70 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
12a80 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69    .** This confi
12a90 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  guration should 
12aa0 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66 20 61  not be used if a
12ab0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
12ac0 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63  fine page.** cac
12ad0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
12ae0 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e  n is loaded usin
12af0 67 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  g the SQLITE_CON
12b00 46 49 47 5f 50 43 41 43 48 45 32 20 6f 70 74 69  FIG_PCACHE2 opti
12b10 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  on..** There are
12b20 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73   three arguments
12b30 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a   to this option:
12b40 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 38 2d   A pointer to 8-
12b50 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20  byte aligned.** 
12b60 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a 65  memory, the size
12b70 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 62 75   of each page bu
12b80 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74  ffer (sz), and t
12b90 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67  he number of pag
12ba0 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73  es (N)..** The s
12bb0 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  z argument shoul
12bc0 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66  d be the size of
12bd0 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 74   the largest dat
12be0 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61  abase page.** (a
12bf0 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65   power of two be
12c00 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33 32  tween 512 and 32
12c10 37 36 38 29 20 70 6c 75 73 20 61 20 6c 69 74 74  768) plus a litt
12c20 6c 65 20 65 78 74 72 61 20 66 6f 72 20 65 61 63  le extra for eac
12c30 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72  h.** page header
12c40 2e 20 20 5e 54 68 65 20 70 61 67 65 20 68 65 61  .  ^The page hea
12c50 64 65 72 20 73 69 7a 65 20 69 73 20 32 30 20 74  der size is 20 t
12c60 6f 20 34 30 20 62 79 74 65 73 20 64 65 70 65 6e  o 40 bytes depen
12c70 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 68  ding on.** the h
12c80 6f 73 74 20 61 72 63 68 69 74 65 63 74 75 72 65  ost architecture
12c90 2e 20 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65  .  ^It is harmle
12ca0 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74  ss, apart from t
12cb0 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79  he wasted memory
12cc0 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 7a 20  ,.** to make sz 
12cd0 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20 6c 61 72  a little too lar
12ce0 67 65 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a  ge.  The first.*
12cf0 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  * argument shoul
12d00 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c  d point to an al
12d10 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c  location of at l
12d20 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20  east sz*N bytes 
12d30 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53  of memory..** ^S
12d40 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74  QLite will use t
12d50 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64  he memory provid
12d60 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
12d70 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69  argument to sati
12d80 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72  sfy its.** memor
12d90 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20  y needs for the 
12da0 66 69 72 73 74 20 4e 20 70 61 67 65 73 20 74 68  first N pages th
12db0 61 74 20 69 74 20 61 64 64 73 20 74 6f 20 63 61  at it adds to ca
12dc0 63 68 65 2e 20 20 5e 49 66 20 61 64 64 69 74 69  che.  ^If additi
12dd0 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63  onal.** page cac
12de0 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65  he memory is nee
12df0 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20  ded beyond what 
12e00 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  is provided by t
12e10 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e  his option, then
12e20 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20  .** SQLite goes 
12e30 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  to [sqlite3_mall
12e40 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64  oc()] for the ad
12e50 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65  ditional storage
12e60 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68 65 20 70   space..** The p
12e70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65 20 66 69  ointer in the fi
12e80 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73  rst argument mus
12e90 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65 64 20  t.** be aligned 
12ea0 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75  to an 8-byte bou
12eb0 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75  ndary or subsequ
12ec0 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20  ent behavior of 
12ed0 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 62  SQLite.** will b
12ee0 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64  e undefined.</dd
12ef0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
12f00 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20 3c  _CONFIG_HEAP]] <
12f10 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
12f20 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  _HEAP</dt>.** <d
12f30 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
12f40 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
12f50 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
12f60 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
12f70 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c  l use.** for all
12f80 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20   of its dynamic 
12f90 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
12fa0 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74  n needs beyond t
12fb0 68 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a  hose provided.**
12fc0 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f   for by [SQLITE_
12fd0 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20  CONFIG_SCRATCH] 
12fe0 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  and [SQLITE_CONF
12ff0 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a  IG_PAGECACHE]..*
13000 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65  * There are thre
13010 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20  e arguments: An 
13020 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70  8-byte aligned p
13030 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65  ointer to the me
13040 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d  mory,.** the num
13050 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
13060 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  the memory buffe
13070 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d  r, and the minim
13080 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  um allocation si
13090 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  ze..** ^If the f
130a0 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68  irst pointer (th
130b0 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  e memory pointer
130c0 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  ) is NULL, then 
130d0 53 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a  SQLite reverts.*
130e0 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64  * to using its d
130f0 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c  efault memory al
13100 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73  locator (the sys
13110 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70  tem malloc() imp
13120 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a  lementation),.**
13130 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69   undoing any pri
13140 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  or invocation of
13150 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
13160 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68  MALLOC].  ^If th
13170 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  e.** memory poin
13180 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  ter is not NULL 
13190 61 6e 64 20 65 69 74 68 65 72 20 5b 53 51 4c 49  and either [SQLI
131a0 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53  TE_ENABLE_MEMSYS
131b0 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  3] or.** [SQLITE
131c0 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d  _ENABLE_MEMSYS5]
131d0 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68   are defined, th
131e0 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69  en the alternati
131f0 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  ve memory.** all
13200 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65  ocator is engage
13210 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20  d to handle all 
13220 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72  of SQLites memor
13230 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
13240 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ds..** The first
13250 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65   pointer (the me
13260 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75  mory pointer) mu
13270 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f  st be aligned to
13280 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f   an 8-byte.** bo
13290 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71  undary or subseq
132a0 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66  uent behavior of
132b0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20   SQLite will be 
132c0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68  undefined..** Th
132d0 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61  e minimum alloca
132e0 74 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61 70  tion size is cap
132f0 70 65 64 20 61 74 20 32 2a 2a 31 32 2e 20 52 65  ped at 2**12. Re
13300 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a  asonable values.
13310 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d  ** for the minim
13320 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  um allocation si
13330 7a 65 20 61 72 65 20 32 2a 2a 35 20 74 68 72 6f  ze are 2**5 thro
13340 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a  ugh 2**8.</dd>.*
13350 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
13360 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74  NFIG_MUTEX]] <dt
13370 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
13380 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  UTEX</dt>.** <dd
13390 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
133a0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
133b0 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
133c0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
133d0 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
133e0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
133f0 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
13400 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75  cture.  The argu
13410 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a  ment specifies.*
13420 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f  * alternative lo
13430 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f  w-level mutex ro
13440 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65  utines to be use
13450 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68  d in place.** th
13460 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  e mutex routines
13470 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
13480 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d  te.)^  ^SQLite m
13490 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
134a0 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 6f 66  he.** content of
134b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
134c0 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
134d0 75 63 74 75 72 65 20 62 65 66 6f 72 65 20 74 68  ucture before th
134e0 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  e call to.** [sq
134f0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
13500 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c  returns. ^If SQL
13510 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
13520 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
13530 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
13540 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
13550 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
13560 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
13570 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74  * the entire mut
13580 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20  exing subsystem 
13590 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
135a0 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65  the build and he
135b0 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  nce calls to.** 
135c0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
135d0 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  )] with the SQLI
135e0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20  TE_CONFIG_MUTEX 
135f0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
13600 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74  tion will.** ret
13610 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
13620 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  R].</dd>.**.** [
13630 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
13640 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51  ETMUTEX]] <dt>SQ
13650 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
13660 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  UTEX</dt>.** <dd
13670 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
13680 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
13690 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
136a0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
136b0 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
136c0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
136d0 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
136e0 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b  cture.  The.** [
136f0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
13700 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74  thods].** struct
13710 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69  ure is filled wi
13720 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79  th the currently
13730 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72   defined mutex r
13740 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68  outines.)^.** Th
13750 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  is option can be
13760 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61   used to overloa
13770 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75  d the default mu
13780 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  tex allocation.*
13790 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20  * routines with 
137a0 61 20 77 72 61 70 70 65 72 20 75 73 65 64 20 74  a wrapper used t
137b0 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73  o track mutex us
137c0 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61  age for performa
137d0 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67  nce.** profiling
137e0 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72   or testing, for
137f0 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20   example.   ^If 
13800 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
13810 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
13820 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
13830 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
13840 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
13850 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
13860 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20  n.** the entire 
13870 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74  mutexing subsyst
13880 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  em is omitted fr
13890 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64  om the build and
138a0 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a   hence calls to.
138b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
138c0 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53  ig()] with the S
138d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
138e0 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74  MUTEX configurat
138f0 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a  ion option will.
13900 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
13910 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a  E_ERROR].</dd>.*
13920 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
13930 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d  NFIG_LOOKASIDE]]
13940 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
13950 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74  IG_LOOKASIDE</dt
13960 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
13970 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77   option takes tw
13980 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  o arguments that
13990 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64   determine the d
139a0 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79  efault.** memory
139b0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20   allocation for 
139c0 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  the lookaside me
139d0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f  mory allocator o
139e0 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62  n each.** [datab
139f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
13a00 20 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75    The first argu
13a10 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73  ment is the.** s
13a20 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b  ize of each look
13a30 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f  aside buffer slo
13a40 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  t and the second
13a50 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
13a60 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63  f.** slots alloc
13a70 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74  ated to each dat
13a80 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
13a90 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f 70 74 69  .)^  ^(This opti
13aa0 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 3c  on sets the.** <
13ab0 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f  i>default</i> lo
13ac0 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54 68  okaside size. Th
13ad0 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  e [SQLITE_DBCONF
13ae0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a  IG_LOOKASIDE].**
13af0 20 76 65 72 62 20 74 6f 20 5b 73 71 6c 69 74 65   verb to [sqlite
13b00 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63  3_db_config()] c
13b10 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 68  an be used to ch
13b20 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69  ange the lookasi
13b30 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  de.** configurat
13b40 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61  ion on individua
13b50 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e  l connections.)^
13b60 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
13b70 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
13b80 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  CHE2]] <dt>SQLIT
13b90 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
13ba0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
13bb0 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
13bc0 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
13bd0 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
13be0 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20  ointer to.** an 
13bf0 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f  [sqlite3_pcache_
13c00 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74  methods2] object
13c10 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73  .  This object s
13c20 70 65 63 69 66 69 65 73 20 74 68 65 20 69 6e 74  pecifies the int
13c30 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63  erface.** to a c
13c40 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65  ustom page cache
13c50 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
13c60 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65  )^  ^SQLite make
13c70 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  s a copy of the.
13c80 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20 75 73  ** object and us
13c90 65 73 20 69 74 20 66 6f 72 20 70 61 67 65 20 63  es it for page c
13ca0 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ache memory allo
13cb0 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a  cations.</dd>.**
13cc0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
13cd0 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 5d 5d  FIG_GETPCACHE2]]
13ce0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
13cf0 49 47 5f 47 45 54 50 43 41 43 48 45 32 3c 2f 64  IG_GETPCACHE2</d
13d00 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
13d10 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
13d20 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
13d30 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
13d40 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71  ter to an.** [sq
13d50 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
13d60 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20  hods2] object.  
13d70 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66  SQLite copies of
13d80 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
13d90 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
13da0 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74  mentation into t
13db0 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f  hat object.)^ </
13dc0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
13dd0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20  TE_CONFIG_LOG]] 
13de0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
13df0 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  G_LOG</dt>.** <d
13e00 64 3e 20 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d> The SQLITE_CO
13e10 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20  NFIG_LOG option 
13e20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69  is used to confi
13e30 67 75 72 65 20 74 68 65 20 53 51 4c 69 74 65 0a  gure the SQLite.
13e40 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 72 6f 72  ** global [error
13e50 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20   log]..** (^The 
13e60 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
13e70 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  G option takes t
13e80 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20  wo arguments: a 
13e90 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20  pointer to a.** 
13ea0 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
13eb0 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f  call signature o
13ec0 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  f void(*)(void*,
13ed0 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  int,const char*)
13ee0 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e  , .** and a poin
13ef0 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66  ter to void. ^If
13f00 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f   the function po
13f10 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c  inter is not NUL
13f20 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f  L, it is.** invo
13f30 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ked by [sqlite3_
13f40 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73  log()] to proces
13f50 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65  s each logging e
13f60 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a  vent.  ^If the.*
13f70 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74  * function point
13f80 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20  er is NULL, the 
13f90 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
13fa0 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65  interface become
13fb0 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54  s a no-op..** ^T
13fc0 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20  he void pointer 
13fd0 74 68 61 74 20 69 73 20 74 68 65 20 73 65 63 6f  that is the seco
13fe0 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53  nd argument to S
13ff0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
14000 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68   is.** passed th
14010 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72  rough as the fir
14020 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
14030 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
14040 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a  defined logger.*
14050 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65  * function whene
14060 76 65 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f  ver that functio
14070 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e  n is invoked.  ^
14080 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
14090 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c  eter to.** the l
140a0 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69  ogger function i
140b0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
140c0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
140d0 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  to the correspon
140e0 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ding.** [sqlite3
140f0 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64  _log()] call and
14100 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20   is intended to 
14110 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64  be a [result cod
14120 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74  e] or an.** [ext
14130 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
14140 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20  e].  ^The third 
14150 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64  parameter passed
14160 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69   to the logger i
14170 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65  s.** log message
14180 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e   after formattin
14190 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73  g via [sqlite3_s
141a0 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54  nprintf()]..** T
141b0 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e  he SQLite loggin
141c0 67 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  g interface is n
141d0 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68  ot reentrant; th
141e0 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f  e logger functio
141f0 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79  n.** supplied by
14200 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
14210 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65   must not invoke
14220 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65   any SQLite inte
14230 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d  rface..** In a m
14240 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61 70  ulti-threaded ap
14250 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61  plication, the a
14260 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
14270 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e  ed logger.** fun
14280 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68  ction must be th
14290 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a  readsafe. </dd>.
142a0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
142b0 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e  ONFIG_URI]] <dt>
142c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
142d0 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 69 73 20  I.** <dd>^(This 
142e0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
142f0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f  ingle argument o
14300 66 20 74 79 70 65 20 69 6e 74 2e 20 49 66 20 6e  f type int. If n
14310 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 0a 2a 2a  on-zero, then.**
14320 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73   URI handling is
14330 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65   globally enable
14340 64 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d 65  d. If the parame
14350 74 65 72 20 69 73 20 7a 65 72 6f 2c 20 74 68 65  ter is zero, the
14360 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 0a 2a  n URI handling.*
14370 2a 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69  * is globally di
14380 73 61 62 6c 65 64 2e 29 5e 20 5e 49 66 20 55 52  sabled.)^ ^If UR
14390 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
143a0 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2c 20  obally enabled, 
143b0 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a 2a  all filenames.**
143c0 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69   passed to [sqli
143d0 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
143e0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
143f0 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
14400 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69  6()] or.** speci
14410 66 69 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  fied as part of 
14420 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64  [ATTACH] command
14430 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  s are interprete
14440 64 20 61 73 20 55 52 49 73 2c 20 72 65 67 61 72  d as URIs, regar
14450 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74  dless.** of whet
14460 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b  her or not the [
14470 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
14480 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65   flag is set whe
14490 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  n the database.*
144a0 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  * connection is 
144b0 6f 70 65 6e 65 64 2e 20 5e 49 66 20 69 74 20 69  opened. ^If it i
144c0 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62  s globally disab
144d0 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61  led, filenames a
144e0 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72  re.** only inter
144f0 70 72 65 74 65 64 20 61 73 20 55 52 49 73 20 69  preted as URIs i
14500 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45  f the SQLITE_OPE
14510 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 20 73 65  N_URI flag is se
14520 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61  t when the.** da
14530 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14540 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 28 42  n is opened. ^(B
14550 79 20 64 65 66 61 75 6c 74 2c 20 55 52 49 20 68  y default, URI h
14560 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61  andling is globa
14570 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e  lly.** disabled.
14580 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c   The default val
14590 75 65 20 6d 61 79 20 62 65 20 63 68 61 6e 67 65  ue may be change
145a0 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77  d by compiling w
145b0 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
145c0 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d 62  TE_USE_URI] symb
145d0 6f 6c 20 64 65 66 69 6e 65 64 2e 29 5e 0a 2a 2a  ol defined.)^.**
145e0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
145f0 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
14600 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e 53 51  EX_SCAN]] <dt>SQ
14610 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
14620 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 0a  RING_INDEX_SCAN.
14630 2a 2a 20 3c 64 64 3e 5e 54 68 69 73 20 6f 70 74  ** <dd>^This opt
14640 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
14650 6c 65 20 69 6e 74 65 67 65 72 20 61 72 67 75 6d  le integer argum
14660 65 6e 74 20 77 68 69 63 68 20 69 73 20 69 6e 74  ent which is int
14670 65 72 70 72 65 74 65 64 20 61 73 0a 2a 2a 20 61  erpreted as.** a
14680 20 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72 64 65   boolean in orde
14690 72 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64  r to enable or d
146a0 69 73 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f  isable the use o
146b0 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63  f covering indic
146c0 65 73 20 66 6f 72 0a 2a 2a 20 66 75 6c 6c 20 74  es for.** full t
146d0 61 62 6c 65 20 73 63 61 6e 73 20 69 6e 20 74 68  able scans in th
146e0 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a 65  e query optimize
146f0 72 2e 20 20 5e 54 68 65 20 64 65 66 61 75 6c 74  r.  ^The default
14700 20 73 65 74 74 69 6e 67 20 69 73 20 64 65 74 65   setting is dete
14710 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65  rmined.** by the
14720 20 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43   [SQLITE_ALLOW_C
14730 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43  OVERING_INDEX_SC
14740 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  AN] compile-time
14750 20 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22   option, or is "
14760 6f 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74 20 63  on".** if that c
14770 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
14780 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a  on is omitted..*
14790 2a 20 54 68 65 20 61 62 69 6c 69 74 79 20 74 6f  * The ability to
147a0 20 64 69 73 61 62 6c 65 20 74 68 65 20 75 73 65   disable the use
147b0 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64   of covering ind
147c0 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61  ices for full ta
147d0 62 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20  ble scans.** is 
147e0 62 65 63 61 75 73 65 20 73 6f 6d 65 20 69 6e 63  because some inc
147f0 6f 72 72 65 63 74 6c 79 20 63 6f 64 65 64 20 6c  orrectly coded l
14800 65 67 61 63 79 20 61 70 70 6c 69 63 61 74 69 6f  egacy applicatio
14810 6e 73 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63  ns might malfunc
14820 74 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65  tion.** when the
14830 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73   optimization is
14840 20 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76 69   enabled.  Provi
14850 64 69 6e 67 20 74 68 65 20 61 62 69 6c 69 74 79  ding the ability
14860 20 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74   to.** disable t
14870 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20  he optimization 
14880 61 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65 72  allows the older
14890 2c 20 62 75 67 67 79 20 61 70 70 6c 69 63 61 74  , buggy applicat
148a0 69 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b  ion code to work
148b0 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63 68 61 6e  .** without chan
148c0 67 65 20 65 76 65 6e 20 77 69 74 68 20 6e 65 77  ge even with new
148d0 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  er versions of S
148e0 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  QLite..**.** [[S
148f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
14900 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43  CHE]] [[SQLITE_C
14910 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 5d  ONFIG_GETPCACHE]
14920 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
14930 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61 6e  CONFIG_PCACHE an
14940 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  d SQLITE_CONFIG_
14950 47 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64  GETPCACHE.** <dd
14960 3e 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 73 20  > These options 
14970 61 72 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64  are obsolete and
14980 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75   should not be u
14990 73 65 64 20 62 79 20 6e 65 77 20 63 6f 64 65 2e  sed by new code.
149a0 0a 2a 2a 20 54 68 65 79 20 61 72 65 20 72 65 74  .** They are ret
149b0 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61  ained for backwa
149c0 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
149d0 79 20 62 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f  y but are now no
149e0 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a  -ops..** </dd>.*
149f0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
14a00 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a  NFIG_SQLLOG]].**
14a10 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
14a20 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64  IG_SQLLOG.** <dd
14a30 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  >This option is 
14a40 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
14a50 66 20 73 71 6c 69 74 65 20 69 73 20 63 6f 6d 70  f sqlite is comp
14a60 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  iled with the.**
14a70 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
14a80 53 51 4c 4c 4f 47 5d 20 70 72 65 2d 70 72 6f 63  SQLLOG] pre-proc
14a90 65 73 73 6f 72 20 6d 61 63 72 6f 20 64 65 66 69  essor macro defi
14aa0 6e 65 64 2e 20 54 68 65 20 66 69 72 73 74 20 61  ned. The first a
14ab0 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a  rgument should.*
14ac0 2a 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74  * be a pointer t
14ad0 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20  o a function of 
14ae0 74 79 70 65 20 76 6f 69 64 28 2a 29 28 76 6f 69  type void(*)(voi
14af0 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73  d*,sqlite3*,cons
14b00 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a  t char*, int)..*
14b10 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 73 68 6f  * The second sho
14b20 75 6c 64 20 62 65 20 6f 66 20 74 79 70 65 20 28  uld be of type (
14b30 76 6f 69 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c  void*). The call
14b40 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
14b50 62 79 20 74 68 65 20 6c 69 62 72 61 72 79 0a 2a  by the library.*
14b60 2a 20 69 6e 20 74 68 72 65 65 20 73 65 70 61 72  * in three separ
14b70 61 74 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65  ate circumstance
14b80 73 2c 20 69 64 65 6e 74 69 66 69 65 64 20 62 79  s, identified by
14b90 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65   the value passe
14ba0 64 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72  d as the.** four
14bb0 74 68 20 70 61 72 61 6d 65 74 65 72 2e 20 49 66  th parameter. If
14bc0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
14bd0 6d 65 74 65 72 20 69 73 20 30 2c 20 74 68 65 6e  meter is 0, then
14be0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
14bf0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73  nnection.** pass
14c00 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
14c10 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 6a 75   argument has ju
14c20 73 74 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20  st been opened. 
14c30 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
14c40 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20  nt.** points to 
14c50 61 20 62 75 66 66 65 72 20 63 6f 6e 74 61 69 6e  a buffer contain
14c60 69 6e 67 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  ing the name of 
14c70 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73  the main databas
14c80 65 20 66 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a  e file. If the.*
14c90 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  * fourth paramet
14ca0 65 72 20 69 73 20 31 2c 20 74 68 65 6e 20 74 68  er is 1, then th
14cb0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
14cc0 74 68 61 74 20 74 68 65 20 74 68 69 72 64 20 70  that the third p
14cd0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e  arameter.** poin
14ce0 74 73 20 74 6f 20 68 61 73 20 6a 75 73 74 20 62  ts to has just b
14cf0 65 65 6e 20 65 78 65 63 75 74 65 64 2e 20 4f 72  een executed. Or
14d00 2c 20 69 66 20 74 68 65 20 66 6f 75 72 74 68 20  , if the fourth 
14d10 70 61 72 61 6d 65 74 65 72 20 69 73 20 32 2c 20  parameter is 2, 
14d20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e  then.** the conn
14d30 65 63 74 69 6f 6e 20 62 65 69 6e 67 20 70 61 73  ection being pas
14d40 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
14d50 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 62  d parameter is b
14d60 65 69 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68 65  eing closed. The
14d70 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65  .** third parame
14d80 74 65 72 20 69 73 20 70 61 73 73 65 64 20 4e 55  ter is passed NU
14d90 4c 4c 20 49 6e 20 74 68 69 73 20 63 61 73 65 2e  LL In this case.
14da0 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20    An example of 
14db0 75 73 69 6e 67 20 74 68 69 73 0a 2a 2a 20 63 6f  using this.** co
14dc0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
14dd0 6f 6e 20 63 61 6e 20 62 65 20 73 65 65 6e 20 69  on can be seen i
14de0 6e 20 74 68 65 20 22 74 65 73 74 5f 73 71 6c 6c  n the "test_sqll
14df0 6f 67 2e 63 22 20 73 6f 75 72 63 65 20 66 69 6c  og.c" source fil
14e00 65 20 69 6e 0a 2a 2a 20 74 68 65 20 63 61 6e 6f  e in.** the cano
14e10 6e 69 63 61 6c 20 53 51 4c 69 74 65 20 73 6f 75  nical SQLite sou
14e20 72 63 65 20 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a  rce tree.</dd>.*
14e30 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
14e40 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d  NFIG_MMAP_SIZE]]
14e50 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
14e60 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a  ONFIG_MMAP_SIZE.
14e70 2a 2a 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f 43  ** <dd>^SQLITE_C
14e80 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20  ONFIG_MMAP_SIZE 
14e90 74 61 6b 65 73 20 74 77 6f 20 36 34 2d 62 69 74  takes two 64-bit
14ea0 20 69 6e 74 65 67 65 72 20 28 73 71 6c 69 74 65   integer (sqlite
14eb0 33 5f 69 6e 74 36 34 29 20 76 61 6c 75 65 73 0a  3_int64) values.
14ec0 2a 2a 20 74 68 61 74 20 61 72 65 20 74 68 65 20  ** that are the 
14ed0 64 65 66 61 75 6c 74 20 6d 6d 61 70 20 73 69 7a  default mmap siz
14ee0 65 20 6c 69 6d 69 74 20 28 74 68 65 20 64 65 66  e limit (the def
14ef0 61 75 6c 74 20 73 65 74 74 69 6e 67 20 66 6f 72  ault setting for
14f00 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70  .** [PRAGMA mmap
14f10 5f 73 69 7a 65 5d 29 20 61 6e 64 20 74 68 65 20  _size]) and the 
14f20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20  maximum allowed 
14f30 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 2e  mmap size limit.
14f40 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74  .** ^The default
14f50 20 73 65 74 74 69 6e 67 20 63 61 6e 20 62 65 20   setting can be 
14f60 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 65 61  overridden by ea
14f70 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ch database conn
14f80 65 63 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20  ection using.** 
14f90 65 69 74 68 65 72 20 74 68 65 20 5b 50 52 41 47  either the [PRAG
14fa0 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 6f  MA mmap_size] co
14fb0 6d 6d 61 6e 64 2c 20 6f 72 20 62 79 20 75 73 69  mmand, or by usi
14fc0 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  ng the.** [SQLIT
14fd0 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a  E_FCNTL_MMAP_SIZ
14fe0 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e  E] file control.
14ff0 20 20 5e 28 54 68 65 20 6d 61 78 69 6d 75 6d 20    ^(The maximum 
15000 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a  allowed mmap siz
15010 65 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20 63  e.** cannot be c
15020 68 61 6e 67 65 64 20 61 74 20 72 75 6e 2d 74 69  hanged at run-ti
15030 6d 65 2e 20 20 4e 6f 72 20 6d 61 79 20 74 68 65  me.  Nor may the
15040 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64   maximum allowed
15050 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 65 78   mmap size.** ex
15060 63 65 65 64 20 74 68 65 20 63 6f 6d 70 69 6c 65  ceed the compile
15070 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d 6d  -time maximum mm
15080 61 70 20 73 69 7a 65 20 73 65 74 20 62 79 20 74  ap size set by t
15090 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41  he.** [SQLITE_MA
150a0 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f 6d  X_MMAP_SIZE] com
150b0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
150c0 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68 65  .)^.** ^If eithe
150d0 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  r argument to th
150e0 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67  is option is neg
150f0 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61 74  ative, then that
15100 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20   argument is.** 
15110 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20 63  changed to its c
15120 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66 61  ompile-time defa
15130 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  ult..**.** [[SQL
15140 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32  ITE_CONFIG_WIN32
15150 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20 3c  _HEAPSIZE]].** <
15160 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
15170 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 0a  _WIN32_HEAPSIZE.
15180 2a 2a 20 3c 64 64 3e 5e 54 68 69 73 20 6f 70 74  ** <dd>^This opt
15190 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  ion is only avai
151a0 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20  lable if SQLite 
151b0 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20  is compiled for 
151c0 57 69 6e 64 6f 77 73 0a 2a 2a 20 77 69 74 68 20  Windows.** with 
151d0 74 68 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33  the [SQLITE_WIN3
151e0 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72  2_MALLOC] pre-pr
151f0 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 64 65  ocessor macro de
15200 66 69 6e 65 64 2e 0a 2a 2a 20 53 51 4c 49 54 45  fined..** SQLITE
15210 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
15220 41 50 53 49 5a 45 20 74 61 6b 65 73 20 61 20 33  APSIZE takes a 3
15230 32 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69  2-bit unsigned i
15240 6e 74 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20  nteger value.** 
15250 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20 74  that specifies t
15260 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20  he maximum size 
15270 6f 66 20 74 68 65 20 63 72 65 61 74 65 64 20 68  of the created h
15280 65 61 70 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  eap..** </dl>.*/
15290 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
152a0 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
152b0 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a  EAD  1  /* nil *
152c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
152d0 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
152e0 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20  EAD   2  /* nil 
152f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
15300 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
15310 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c  ZED    3  /* nil
15320 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15330 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
15340 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71          4  /* sq
15350 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
15360 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
15370 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
15380 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20  ALLOC     5  /* 
15390 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
153a0 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
153b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
153c0 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f  RATCH       6  /
153d0 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c  * void*, int sz,
153e0 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e   int N */.#defin
153f0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15400 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20  PAGECACHE     7 
15410 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73   /* void*, int s
15420 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66  z, int N */.#def
15430 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
15440 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20  G_HEAP          
15450 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  8  /* void*, int
15460 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20   nByte, int min 
15470 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
15480 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
15490 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f  US     9  /* boo
154a0 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  lean */.#define 
154b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
154c0 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f  TEX        10  /
154d0 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
154e0 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
154f0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
15500 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31  G_GETMUTEX     1
15510 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  1  /* sqlite3_mu
15520 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
15530 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51  /* previously SQ
15540 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e  LITE_CONFIG_CHUN
15550 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20  KALLOC 12 which 
15560 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a  is now unused. *
15570 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  / .#define SQLIT
15580 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
15590 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74  DE    13  /* int
155a0 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
155b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
155c0 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f  ACHE       14  /
155d0 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69  * no-op */.#defi
155e0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
155f0 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35  _GETPCACHE    15
15600 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64    /* no-op */.#d
15610 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
15620 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20  FIG_LOG         
15630 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76   16  /* xFunc, v
15640 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  oid* */.#define 
15650 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
15660 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20 2f  I          17  /
15670 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  * int */.#define
15680 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
15690 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20 20  CACHE2      18  
156a0 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68  /* sqlite3_pcach
156b0 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23  e_methods2* */.#
156c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
156d0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20  NFIG_GETPCACHE2 
156e0 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33    19  /* sqlite3
156f0 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32  _pcache_methods2
15700 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
15710 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52  ITE_CONFIG_COVER
15720 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32  ING_INDEX_SCAN 2
15730 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65  0  /* int */.#de
15740 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
15750 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20  IG_SQLLOG       
15760 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20  21  /* xSqllog, 
15770 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  void* */.#define
15780 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
15790 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20  MAP_SIZE    22  
157a0 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  /* sqlite3_int64
157b0 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
157c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
157d0 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48  E_CONFIG_WIN32_H
157e0 45 41 50 53 49 5a 45 20 20 20 20 20 20 32 33 20  EAPSIZE      23 
157f0 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f   /* int nByte */
15800 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
15810 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
15820 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74  ction Configurat
15830 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a  ion Options.**.*
15840 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
15850 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61  s are the availa
15860 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66  ble integer conf
15870 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
15880 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65  s that.** can be
15890 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73   passed as the s
158a0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
158b0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64  o the [sqlite3_d
158c0 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  b_config()] inte
158d0 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  rface..**.** New
158e0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
158f0 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64  ptions may be ad
15900 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
15910 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
15920 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f  ..** Existing co
15930 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
15940 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73  ons might be dis
15950 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c  continued.  Appl
15960 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75  ications.** shou
15970 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74  ld check the ret
15980 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73  urn code from [s
15990 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
159a0 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ()] to make sure
159b0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c   that.** the cal
159c0 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20  l worked.  ^The 
159d0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
159e0 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ig()] interface 
159f0 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a  will return a.**
15a00 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
15a10 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63   code] if a disc
15a20 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75  ontinued or unsu
15a30 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72  pported configur
15a40 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20  ation option.** 
15a50 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  is invoked..**.*
15a60 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51  * <dl>.** <dt>SQ
15a70 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
15a80 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20  OKASIDE</dt>.** 
15a90 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
15aa0 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 61 64  n takes three ad
15ab0 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
15ac0 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  ts that determin
15ad0 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61  e the .** [looka
15ae0 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  side memory allo
15af0 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61  cator] configura
15b00 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61  tion for the [da
15b10 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
15b20 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  n]..** ^The firs
15b30 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20  t argument (the 
15b40 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
15b50 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  to [sqlite3_db_c
15b60 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a  onfig()] is a.**
15b70 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65   pointer to a me
15b80 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 75  mory buffer to u
15b90 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65  se for lookaside
15ba0 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65   memory..** ^The
15bb0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
15bc0 61 66 74 65 72 20 74 68 65 20 53 51 4c 49 54 45  after the SQLITE
15bd0 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
15be0 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20  IDE verb.** may 
15bf0 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68  be NULL in which
15c00 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c   case SQLite wil
15c10 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a  l allocate the.*
15c20 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  * lookaside buff
15c30 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20  er itself using 
15c40 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
15c50 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  )]. ^The second 
15c60 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a  argument is the.
15c70 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  ** size of each 
15c80 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
15c90 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69   slot.  ^The thi
15ca0 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  rd argument is t
15cb0 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
15cc0 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65  slots.  The size
15cd0 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69   of the buffer i
15ce0 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
15cf0 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65  ment must be gre
15d00 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20  ater than.** or 
15d10 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f  equal to the pro
15d20 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f  duct of the seco
15d30 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67  nd and third arg
15d40 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66  uments.  The buf
15d50 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61  fer.** must be a
15d60 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62  ligned to an 8-b
15d70 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e  yte boundary.  ^
15d80 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  If the second ar
15d90 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c  gument to.** SQL
15da0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
15db0 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20  KASIDE is not a 
15dc0 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69  multiple of 8, i
15dd0 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a  t is internally.
15de0 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20  ** rounded down 
15df0 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c  to the next smal
15e00 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  ler multiple of 
15e10 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73  8.  ^(The lookas
15e20 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f  ide memory.** co
15e30 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20  nfiguration for 
15e40 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
15e50 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62  ction can only b
15e60 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74  e changed when t
15e70 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  hat.** connectio
15e80 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  n is not current
15e90 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69  ly using lookasi
15ea0 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e  de memory, or in
15eb0 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20   other words.** 
15ec0 77 68 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e  when the "curren
15ed0 74 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65  t value" returne
15ee0 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
15ef0 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53  _db_status](D,[S
15f00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
15f10 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20  KASIDE],...) is 
15f20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74  zero..** Any att
15f30 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74  empt to change t
15f40 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  he lookaside mem
15f50 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ory configuratio
15f60 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65  n when lookaside
15f70 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e  .** memory is in
15f80 20 75 73 65 20 6c 65 61 76 65 73 20 74 68 65 20   use leaves the 
15f90 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e  configuration un
15fa0 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75  changed and retu
15fb0 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  rns .** [SQLITE_
15fc0 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a  BUSY].)^</dd>.**
15fd0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
15fe0 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
15ff0 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  KEY</dt>.** <dd>
16000 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73   ^This option is
16010 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20   used to enable 
16020 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 65  or disable the e
16030 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a  nforcement of.**
16040 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f   [foreign key co
16050 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65  nstraints].  The
16060 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f  re should be two
16070 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
16080 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69  ments..** The fi
16090 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
160a0 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  an integer which
160b0 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
160c0 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c   FK enforcement,
160d0 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20  .** positive to 
160e0 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63  enable FK enforc
160f0 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76  ement or negativ
16100 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e  e to leave FK en
16110 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63  forcement.** unc
16120 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63  hanged.  The sec
16130 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
16140 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
16150 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68   integer into wh
16160 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65  ich.** is writte
16170 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  n 0 or 1 to indi
16180 63 61 74 65 20 77 68 65 74 68 65 72 20 46 4b 20  cate whether FK 
16190 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f  enforcement is o
161a0 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c  ff or on.** foll
161b0 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e  owing this call.
161c0 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
161d0 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20  ameter may be a 
161e0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e  NULL pointer, in
161f0 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74  .** which case t
16200 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  he FK enforcemen
16210 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74  t setting is not
16220 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20   reported back. 
16230 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
16240 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
16250 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f  ENABLE_TRIGGER</
16260 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
16270 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  s option is used
16280 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69   to enable or di
16290 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52  sable [CREATE TR
162a0 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73  IGGER | triggers
162b0 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75  ]..** There shou
162c0 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69  ld be two additi
162d0 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a  onal arguments..
162e0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
162f0 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65  ument is an inte
16300 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74  ger which is 0 t
16310 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67 67 65  o disable trigge
16320 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20  rs,.** positive 
16330 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65  to enable trigge
16340 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  rs or negative t
16350 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74  o leave the sett
16360 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a  ing unchanged..*
16370 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * The second par
16380 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
16390 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
163a0 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20  r into which.** 
163b0 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
163c0 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
163d0 65 74 68 65 72 20 74 72 69 67 67 65 72 73 20 61  ether triggers a
163e0 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65  re disabled or e
163f0 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77  nabled.** follow
16400 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20  ing this call.  
16410 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
16420 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55  eter may be a NU
16430 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a  LL pointer, in.*
16440 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  * which case the
16450 20 74 72 69 67 67 65 72 20 73 65 74 74 69 6e 67   trigger setting
16460 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64   is not reported
16470 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a   back. </dd>.**.
16480 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
16490 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
164a0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20  FIG_LOOKASIDE   
164b0 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69      1001  /* voi
164c0 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64  d* int int */.#d
164d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
164e0 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45  ONFIG_ENABLE_FKE
164f0 59 20 20 20 20 20 31 30 30 32 20 20 2f 2a 20 69  Y     1002  /* i
16500 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69  nt int* */.#defi
16510 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
16520 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45  IG_ENABLE_TRIGGE
16530 52 20 20 31 30 30 33 20 20 2f 2a 20 69 6e 74 20  R  1003  /* int 
16540 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20  int* */.../*.** 
16550 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65  CAPI3REF: Enable
16560 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65   Or Disable Exte
16570 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65  nded Result Code
16580 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
16590 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
165a0 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75  sult_codes() rou
165b0 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20  tine enables or 
165c0 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20  disables the.** 
165d0 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
165e0 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20   codes] feature 
165f0 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20  of SQLite. ^The 
16600 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a  extended result.
16610 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69 73  ** codes are dis
16620 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
16630 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20   for historical 
16640 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
16650 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  /.int sqlite3_ex
16660 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
16670 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  des(sqlite3*, in
16680 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a  t onoff);../*.**
16690 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20   CAPI3REF: Last 
166a0 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a  Insert Rowid.**.
166b0 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69  ** ^Each entry i
166c0 6e 20 6d 6f 73 74 20 53 51 4c 69 74 65 20 74 61  n most SQLite ta
166d0 62 6c 65 73 20 28 65 78 63 65 70 74 20 66 6f 72  bles (except for
166e0 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d   [WITHOUT ROWID]
166f0 20 74 61 62 6c 65 73 29 0a 2a 2a 20 68 61 73 20   tables).** has 
16700 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20  a unique 64-bit 
16710 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65  signed.** intege
16720 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65  r key called the
16730 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64   [ROWID | "rowid
16740 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 69  "]. ^The rowid i
16750 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62  s always availab
16760 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65  le.** as an unde
16770 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61  clared column na
16780 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20  med ROWID, OID, 
16790 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f  or _ROWID_ as lo
167a0 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e  ng as those.** n
167b0 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73  ames are not als
167c0 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c 69 63  o used by explic
167d0 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f  itly declared co
167e0 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68  lumns. ^If.** th
167f0 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f  e table has a co
16800 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e  lumn of type [IN
16810 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45  TEGER PRIMARY KE
16820 59 5d 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c  Y] then that col
16830 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65  umn.** is anothe
16840 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20  r alias for the 
16850 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rowid..**.** ^Th
16860 65 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69  e sqlite3_last_i
16870 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20 69  nsert_rowid(D) i
16880 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
16890 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20   the [rowid] of 
168a0 74 68 65 20 0a 2a 2a 20 6d 6f 73 74 20 72 65 63  the .** most rec
168b0 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c 20 5b  ent successful [
168c0 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 61 20 72  INSERT] into a r
168d0 6f 77 69 64 20 74 61 62 6c 65 20 6f 72 20 5b 76  owid table or [v
168e0 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a  irtual table].**
168f0 20 6f 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e   on database con
16900 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 20 5e 49  nection D..** ^I
16910 6e 73 65 72 74 73 20 69 6e 74 6f 20 5b 57 49 54  nserts into [WIT
16920 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c  HOUT ROWID] tabl
16930 65 73 20 61 72 65 20 6e 6f 74 20 72 65 63 6f 72  es are not recor
16940 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73  ded..** ^If no s
16950 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
16960 54 5d 73 20 69 6e 74 6f 20 72 6f 77 69 64 20 74  T]s into rowid t
16970 61 62 6c 65 73 0a 2a 2a 20 68 61 76 65 20 65 76  ables.** have ev
16980 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74  er occurred on t
16990 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
169a0 65 63 74 69 6f 6e 20 44 2c 20 0a 2a 2a 20 74 68  ection D, .** th
169b0 65 6e 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  en sqlite3_last_
169c0 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20  insert_rowid(D) 
169d0 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a  returns zero..**
169e0 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53  .** ^(If an [INS
169f0 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68  ERT] occurs with
16a00 69 6e 20 61 20 74 72 69 67 67 65 72 20 6f 72 20  in a trigger or 
16a10 77 69 74 68 69 6e 20 61 20 5b 76 69 72 74 75 61  within a [virtua
16a20 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68  l table].** meth
16a30 6f 64 2c 20 74 68 65 6e 20 74 68 69 73 20 72 6f  od, then this ro
16a40 75 74 69 6e 65 20 77 69 6c 6c 20 72 65 74 75 72  utine will retur
16a50 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66  n the [rowid] of
16a60 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a   the inserted.**
16a70 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73 20   row as long as 
16a80 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76  the trigger or v
16a90 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74  irtual table met
16aa0 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  hod is running..
16ab0 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20  ** But once the 
16ac0 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75  trigger or virtu
16ad0 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20  al table method 
16ae0 65 6e 64 73 2c 20 74 68 65 20 76 61 6c 75 65 20  ends, the value 
16af0 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20  returned .** by 
16b00 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76  this routine rev
16b10 65 72 74 73 20 74 6f 20 77 68 61 74 20 69 74 20  erts to what it 
16b20 77 61 73 20 62 65 66 6f 72 65 20 74 68 65 20 74  was before the t
16b30 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61  rigger or virtua
16b40 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65 74 68 6f  l.** table metho
16b50 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a  d began.)^.**.**
16b60 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68   ^An [INSERT] th
16b70 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20  at fails due to 
16b80 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  a constraint vio
16b90 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a  lation is not a.
16ba0 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  ** successful [I
16bb0 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20  NSERT] and does 
16bc0 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76  not change the v
16bd0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
16be0 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
16bf0 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20  .  ^Thus INSERT 
16c00 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20  OR FAIL, INSERT 
16c10 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52  OR IGNORE, INSER
16c20 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a  T OR ROLLBACK,.*
16c30 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20  * and INSERT OR 
16c40 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68  ABORT make no ch
16c50 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74  anges to the ret
16c60 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
16c70 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65  s.** routine whe
16c80 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f  n their insertio
16c90 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e  n fails.  ^(When
16ca0 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41   INSERT OR REPLA
16cb0 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73  CE.** encounters
16cc0 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69   a constraint vi
16cd0 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73  olation, it does
16ce0 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a   not fail.  The.
16cf0 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e  ** INSERT contin
16d00 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  ues to completio
16d10 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67  n after deleting
16d20 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65   rows that cause
16d30 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61  d.** the constra
16d40 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49  int problem so I
16d50 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45  NSERT OR REPLACE
16d60 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61   will always cha
16d70 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72  nge.** the retur
16d80 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20  n value of this 
16d90 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a  interface.)^.**.
16da0 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70  ** ^For the purp
16db0 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75  oses of this rou
16dc0 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54  tine, an [INSERT
16dd0 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  ] is considered 
16de0 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73  to.** be success
16df0 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69  ful even if it i
16e00 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72  s subsequently r
16e10 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a  olled back..**.*
16e20 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  * This function 
16e30 69 73 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f  is accessible to
16e40 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
16e50 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74  via the.** [last
16e60 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20  _insert_rowid() 
16e70 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a  SQL function]..*
16e80 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61  *.** If a separa
16e90 74 65 20 74 68 72 65 61 64 20 70 65 72 66 6f 72  te thread perfor
16ea0 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54  ms a new [INSERT
16eb0 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a  ] on the same.**
16ec0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
16ed0 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b  tion while the [
16ee0 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
16ef0 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20  ert_rowid()].** 
16f00 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
16f10 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61  ing and thus cha
16f20 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e  nges the last in
16f30 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a  sert [rowid],.**
16f40 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20   then the value 
16f50 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
16f60 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
16f70 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20  _rowid()] is.** 
16f80 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
16f90 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61  d might not equa
16fa0 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64  l either the old
16fb0 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c   or the new.** l
16fc0 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69  ast insert [rowi
16fd0 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69  d]..*/.sqlite3_i
16fe0 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73  nt64 sqlite3_las
16ff0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73  t_insert_rowid(s
17000 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
17010 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74   CAPI3REF: Count
17020 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52   The Number Of R
17030 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a  ows Modified.**.
17040 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
17050 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
17060 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61 73 65  mber of database
17070 20 72 6f 77 73 20 74 68 61 74 20 77 65 72 65 20   rows that were 
17080 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e  changed.** or in
17090 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65  serted or delete
170a0 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65  d by the most re
170b0 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64  cently completed
170c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a   SQL statement.*
170d0 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61  * on the [databa
170e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73  se connection] s
170f0 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
17100 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e  first parameter.
17110 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61 6e 67  .** ^(Only chang
17120 65 73 20 74 68 61 74 20 61 72 65 20 64 69 72 65  es that are dire
17130 63 74 6c 79 20 73 70 65 63 69 66 69 65 64 20 62  ctly specified b
17140 79 20 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c 20  y the [INSERT], 
17150 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20  [UPDATE],.** or 
17160 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65  [DELETE] stateme
17170 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 20  nt are counted. 
17180 20 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67   Auxiliary chang
17190 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a 20  es caused by.** 
171a0 74 72 69 67 67 65 72 73 20 6f 72 20 5b 66 6f 72  triggers or [for
171b0 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73  eign key actions
171c0 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65  ] are not counte
171d0 64 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a 2a 20  d.)^ Use the.** 
171e0 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
171f0 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69  hanges()] functi
17200 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74  on to find the t
17210 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63  otal number of c
17220 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75 64  hanges.** includ
17230 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75 73  ing changes caus
17240 65 64 20 62 79 20 74 72 69 67 67 65 72 73 20 61  ed by triggers a
17250 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65 79 20 61  nd foreign key a
17260 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43  ctions..**.** ^C
17270 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77  hanges to a view
17280 20 74 68 61 74 20 61 72 65 20 73 69 6d 75 6c 61   that are simula
17290 74 65 64 20 62 79 20 61 6e 20 5b 49 4e 53 54 45  ted by an [INSTE
172a0 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 0a 2a  AD OF trigger].*
172b0 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65  * are not counte
172c0 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74 61  d.  Only real ta
172d0 62 6c 65 20 63 68 61 6e 67 65 73 20 61 72 65 20  ble changes are 
172e0 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  counted..**.** ^
172f0 28 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20  (A "row change" 
17300 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61  is a change to a
17310 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61   single row of a
17320 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a   single table.**
17330 20 63 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e   caused by an IN
17340 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72  SERT, DELETE, or
17350 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e   UPDATE statemen
17360 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a  t.  Rows that.**
17370 20 61 72 65 20 63 68 61 6e 67 65 64 20 61 73 20   are changed as 
17380 73 69 64 65 20 65 66 66 65 63 74 73 20 6f 66 20  side effects of 
17390 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72  [REPLACE] constr
173a0 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c  aint resolution,
173b0 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42  .** rollback, AB
173c0 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20  ORT processing, 
173d0 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f 72  [DROP TABLE], or
173e0 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a   by any other.**
173f0 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e   mechanisms do n
17400 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65  ot count as dire
17410 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 29  ct row changes.)
17420 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67  ^.**.** A "trigg
17430 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61  er context" is a
17440 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74   scope of execut
17450 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20  ion that begins 
17460 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68  and.** ends with
17470 20 74 68 65 20 73 63 72 69 70 74 20 6f 66 20 61   the script of a
17480 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52   [CREATE TRIGGER
17490 20 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a   | trigger]. .**
174a0 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d   Most SQL statem
174b0 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c  ents are.** eval
174c0 75 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66  uated outside of
174d0 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54   any trigger.  T
174e0 68 69 73 20 69 73 20 74 68 65 20 22 74 6f 70 20  his is the "top 
174f0 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65  level".** trigge
17500 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61  r context.  If a
17510 20 74 72 69 67 67 65 72 20 66 69 72 65 73 20 66   trigger fires f
17520 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65  rom the top leve
17530 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67  l, a.** new trig
17540 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65  ger context is e
17550 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65 20 64  ntered for the d
17560 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20  uration of that 
17570 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20  one.** trigger. 
17580 20 53 75 62 74 72 69 67 67 65 72 73 20 63 72 65   Subtriggers cre
17590 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20  ate subcontexts 
175a0 66 6f 72 20 74 68 65 69 72 20 64 75 72 61 74 69  for their durati
175b0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  on..**.** ^Calli
175c0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ng [sqlite3_exec
175d0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
175e0 73 74 65 70 28 29 5d 20 72 65 63 75 72 73 69 76  step()] recursiv
175f0 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20  ely does.** not 
17600 63 72 65 61 74 65 20 61 20 6e 65 77 20 74 72 69  create a new tri
17610 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a  gger context..**
17620 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
17630 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
17640 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74 20  umber of direct 
17650 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20 74  row changes in t
17660 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e  he.** most recen
17670 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  t INSERT, UPDATE
17680 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74  , or DELETE stat
17690 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65  ement within the
176a0 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72   same.** trigger
176b0 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20   context..**.** 
176c0 5e 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c  ^Thus, when call
176d0 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20  ed from the top 
176e0 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e 63  level, this func
176f0 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
17700 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  .** number of ch
17710 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73  anges in the mos
17720 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c  t recent INSERT,
17730 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
17740 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20  TE.** that also 
17750 6f 63 63 75 72 72 65 64 20 61 74 20 74 68 65 20  occurred at the 
17760 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28 57 69  top level.  ^(Wi
17770 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66  thin the body of
17780 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74   a trigger,.** t
17790 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  he sqlite3_chang
177a0 65 73 28 29 20 69 6e 74 65 72 66 61 63 65 20 63  es() interface c
177b0 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20  an be called to 
177c0 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20  find the number 
177d0 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e  of.** changes in
177e0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
177f0 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53  ly completed INS
17800 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
17810 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d  DELETE.** statem
17820 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 62  ent within the b
17830 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ody of the same 
17840 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65  trigger..** Howe
17850 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20  ver, the number 
17860 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f  returned does no
17870 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65  t include change
17880 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73  s.** caused by s
17890 75 62 74 72 69 67 67 65 72 73 20 73 69 6e 63 65  ubtriggers since
178a0 20 74 68 6f 73 65 20 68 61 76 65 20 74 68 65 69   those have thei
178b0 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 29 5e  r own context.)^
178c0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
178d0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  the [sqlite3_tot
178e0 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e  al_changes()] in
178f0 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20  terface, the.** 
17900 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70  [count_changes p
17910 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20  ragma], and the 
17920 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  [changes() SQL f
17930 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
17940 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
17950 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
17960 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
17970 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
17980 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c  on.** while [sql
17990 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20  ite3_changes()] 
179a0 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
179b0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
179c0 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69  ed.** is unpredi
179d0 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d  ctable and not m
179e0 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e  eaningful..*/.in
179f0 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  t sqlite3_change
17a00 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  s(sqlite3*);../*
17a10 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f  .** CAPI3REF: To
17a20 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f  tal Number Of Ro
17a30 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a  ws Modified.**.*
17a40 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
17a50 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
17a60 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e 67  ber of row chang
17a70 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 49 4e  es caused by [IN
17a80 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54  SERT],.** [UPDAT
17a90 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73  E] or [DELETE] s
17aa0 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65 20  tatements since 
17ab0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
17ac0 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70  nnection] was op
17ad0 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65 20 63  ened..** ^(The c
17ae0 6f 75 6e 74 20 72 65 74 75 72 6e 65 64 20 62 79  ount returned by
17af0 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63   sqlite3_total_c
17b00 68 61 6e 67 65 73 28 29 20 69 6e 63 6c 75 64 65  hanges() include
17b10 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a 2a 2a  s all changes.**
17b20 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41 54   from all [CREAT
17b30 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67  E TRIGGER | trig
17b40 67 65 72 5d 20 63 6f 6e 74 65 78 74 73 20 61 6e  ger] contexts an
17b50 64 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 62  d changes made b
17b60 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65  y.** [foreign ke
17b70 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f 77 65  y actions]. Howe
17b80 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e  ver,.** the coun
17b90 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  t does not inclu
17ba0 64 65 20 63 68 61 6e 67 65 73 20 75 73 65 64 20  de changes used 
17bb0 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52 45  to implement [RE
17bc0 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e  PLACE] constrain
17bd0 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61  ts,.** do rollba
17be0 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f  cks or ABORT pro
17bf0 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52 4f  cessing, or [DRO
17c00 50 20 54 41 42 4c 45 5d 20 70 72 6f 63 65 73 73  P TABLE] process
17c10 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f 75  ing.  The.** cou
17c20 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  nt does not incl
17c30 75 64 65 20 72 6f 77 73 20 6f 66 20 76 69 65 77  ude rows of view
17c40 73 20 74 68 61 74 20 66 69 72 65 20 61 6e 20 5b  s that fire an [
17c50 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
17c60 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20 69  er],.** though i
17c70 66 20 74 68 65 20 49 4e 53 54 45 41 44 20 4f 46  f the INSTEAD OF
17c80 20 74 72 69 67 67 65 72 20 6d 61 6b 65 73 20 63   trigger makes c
17c90 68 61 6e 67 65 73 20 6f 66 20 69 74 73 20 6f 77  hanges of its ow
17ca0 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e 67 65 73  n, those changes
17cb0 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65 64   .** are counted
17cc0 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .)^.** ^The sqli
17cd0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
17ce0 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 6f 75  s() function cou
17cf0 6e 74 73 20 74 68 65 20 63 68 61 6e 67 65 73 20  nts the changes 
17d00 61 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74 68  as soon as.** th
17d10 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  e statement that
17d20 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 20 63   makes them is c
17d30 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74  ompleted (when t
17d40 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e  he statement han
17d50 64 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73 65 64  dle.** is passed
17d60 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
17d70 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
17d80 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a  3_finalize()])..
17d90 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  **.** See also t
17da0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  he [sqlite3_chan
17db0 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ges()] interface
17dc0 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f  , the.** [count_
17dd0 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c  changes pragma],
17de0 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f   and the [total_
17df0 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
17e00 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
17e10 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
17e20 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ead makes change
17e30 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  s on the same da
17e40 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
17e50 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69  n.** while [sqli
17e60 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
17e70 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20  s()] is running 
17e80 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a  then the value.*
17e90 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e  * returned is un
17ea0 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
17eb0 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a  not meaningful..
17ec0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  */.int sqlite3_t
17ed0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c  otal_changes(sql
17ee0 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
17ef0 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75  API3REF: Interru
17f00 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e  pt A Long-Runnin
17f10 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54  g Query.**.** ^T
17f20 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75  his function cau
17f30 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20  ses any pending 
17f40 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
17f50 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a  on to abort and.
17f60 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73  ** return at its
17f70 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74   earliest opport
17f80 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74  unity. This rout
17f90 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79  ine is typically
17fa0 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65  .** called in re
17fb0 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72  sponse to a user
17fc0 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20   action such as 
17fd0 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c  pressing "Cancel
17fe0 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77  ".** or Ctrl-C w
17ff0 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61  here the user wa
18000 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79  nts a long query
18010 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61   operation to ha
18020 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c  lt.** immediatel
18030 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20  y..**.** ^It is 
18040 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
18050 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61  s routine from a
18060 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e   thread differen
18070 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68  t from the.** th
18080 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72  read that is cur
18090 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74  rently running t
180a0 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  he database oper
180b0 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a  ation.  But it.*
180c0 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  * is not safe to
180d0 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   call this routi
180e0 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62  ne with a [datab
180f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
18100 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65  that.** is close
18110 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65  d or might close
18120 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f   before sqlite3_
18130 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75  interrupt() retu
18140 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61  rns..**.** ^If a
18150 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  n SQL operation 
18160 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66  is very nearly f
18170 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74  inished at the t
18180 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69  ime when.** sqli
18190 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
181a0 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20  is called, then 
181b0 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76  it might not hav
181c0 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79  e an opportunity
181d0 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72  .** to be interr
181e0 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20  upted and might 
181f0 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70  continue to comp
18200 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41  letion..**.** ^A
18210 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  n SQL operation 
18220 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70  that is interrup
18230 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ted will return 
18240 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
18250 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69  T]..** ^If the i
18260 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f  nterrupted SQL o
18270 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49  peration is an I
18280 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
18290 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74  r DELETE.** that
182a0 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78   is inside an ex
182b0 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
182c0 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74  on, then the ent
182d0 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a  ire transaction.
182e0 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65  ** will be rolle
182f0 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63  d back automatic
18300 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ally..**.** ^The
18310 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
18320 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e  pt(D) call is in
18330 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c   effect until al
18340 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  l currently runn
18350 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ing.** SQL state
18360 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61  ments on [databa
18370 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
18380 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79   complete.  ^Any
18390 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65   new SQL stateme
183a0 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  nts.** that are 
183b0 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68  started after th
183c0 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
183d0 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62  upt() call and b
183e0 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75  efore the .** ru
183f0 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73  nning statements
18400 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72   reaches zero ar
18410 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 73  e interrupted as
18420 20 69 66 20 74 68 65 79 20 68 61 64 20 62 65 65   if they had bee
18430 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69  n.** running pri
18440 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  or to the sqlite
18450 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
18460 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74  ll.  ^New SQL st
18470 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
18480 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
18490 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73  er the running s
184a0 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72  tatement count r
184b0 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a  eaches zero are.
184c0 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20  ** not effected 
184d0 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  by the sqlite3_i
184e0 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e  nterrupt()..** ^
184f0 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
18500 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 74  3_interrupt(D) t
18510 68 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20  hat occurs when 
18520 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e  there are no run
18530 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ning.** SQL stat
18540 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f  ements is a no-o
18550 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66  p and has no eff
18560 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65  ect on SQL state
18570 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
18580 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
18590 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
185a0 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74  rrupt() call ret
185b0 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  urns..**.** If t
185c0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
185d0 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68  ection closes wh
185e0 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74  ile [sqlite3_int
185f0 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20  errupt()].** is 
18600 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64  running then bad
18610 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b   things will lik
18620 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76  ely happen..*/.v
18630 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  oid sqlite3_inte
18640 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b  rrupt(sqlite3*);
18650 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
18660 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
18670 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
18680 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a  Is Complete.**.*
18690 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
186a0 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69   are useful duri
186b0 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20  ng command-line 
186c0 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69  input to determi
186d0 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72  ne if the.** cur
186e0 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74  rently entered t
186f0 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72  ext seems to for
18700 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c  m a complete SQL
18710 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a   statement or.**
18720 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69   if additional i
18730 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62  nput is needed b
18740 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68  efore sending th
18750 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53  e text into.** S
18760 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e  QLite for parsin
18770 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69  g.  ^These routi
18780 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20  nes return 1 if 
18790 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
187a0 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62  .** appears to b
187b0 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c  e a complete SQL
187c0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20   statement.  ^A 
187d0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64  statement is jud
187e0 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d  ged to be.** com
187f0 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73  plete if it ends
18800 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f   with a semicolo
18810 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e  n token and is n
18820 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61  ot a prefix of a
18830 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20  .** well-formed 
18840 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73  CREATE TRIGGER s
18850 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69  tatement.  ^Semi
18860 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20  colons that are 
18870 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a  embedded within.
18880 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61  ** string litera
18890 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65  ls or quoted ide
188a0 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72  ntifier names or
188b0 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f   comments are no
188c0 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74  t.** independent
188d0 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72   tokens (they ar
188e0 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f  e part of the to
188f0 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65  ken in which the
18900 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65  y are.** embedde
18910 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e  d) and thus do n
18920 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74  ot count as a st
18930 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74  atement terminat
18940 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65  or.  ^Whitespace
18950 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73  .** and comments
18960 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65   that follow the
18970 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e   final semicolon
18980 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a   are ignored..**
18990 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
189a0 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20  nes return 0 if 
189b0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
189c0 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49   incomplete.  ^I
189d0 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  f a.** memory al
189e0 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20  location fails, 
189f0 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45  then SQLITE_NOME
18a00 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  M is returned..*
18a10 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
18a20 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73  ines do not pars
18a30 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  e the SQL statem
18a40 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c  ents thus.** wil
18a50 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e  l not detect syn
18a60 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72  tactically incor
18a70 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20  rect SQL..**.** 
18a80 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20  ^(If SQLite has 
18a90 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c  not been initial
18aa0 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ized using [sqli
18ab0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
18ac0 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69  ] prior .** to i
18ad0 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f  nvoking sqlite3_
18ae0 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65  complete16() the
18af0 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  n sqlite3_initia
18b00 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
18b10 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  d.** automatical
18b20 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ly by sqlite3_co
18b30 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20  mplete16().  If 
18b40 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74  that initializat
18b50 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68  ion fails,.** th
18b60 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  en the return va
18b70 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
18b80 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69  _complete16() wi
18b90 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a  ll be non-zero.*
18ba0 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  * regardless of 
18bb0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
18bc0 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20  he input SQL is 
18bd0 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a  complete.)^.**.*
18be0 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b  * The input to [
18bf0 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
18c00 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65  ()] must be a ze
18c10 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
18c20 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a   UTF-8 string..*
18c30 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74  *.** The input t
18c40 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  o [sqlite3_compl
18c50 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65  ete16()] must be
18c60 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
18c70 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72  ed.** UTF-16 str
18c80 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79  ing in native by
18c90 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74  te order..*/.int
18ca0 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
18cb0 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  e(const char *sq
18cc0 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
18cd0 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74  complete16(const
18ce0 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a   void *sql);../*
18cf0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
18d00 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63  gister A Callbac
18d10 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49  k To Handle SQLI
18d20 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a  TE_BUSY Errors.*
18d30 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
18d40 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 44  3_busy_handler(D
18d50 2c 58 2c 50 29 20 72 6f 75 74 69 6e 65 20 73 65  ,X,P) routine se
18d60 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  ts a callback fu
18d70 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 74 68 61 74  nction X.** that
18d80 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65   might be invoke
18d90 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20  d with argument 
18da0 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e  P whenever.** an
18db0 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65   attempt is made
18dc0 20 74 6f 20 61 63 63 65 73 73 20 61 20 64 61 74   to access a dat
18dd0 61 62 61 73 65 20 74 61 62 6c 65 20 61 73 73 6f  abase table asso
18de0 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 5b  ciated with.** [
18df0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
18e00 69 6f 6e 5d 20 44 20 77 68 65 6e 20 61 6e 6f 74  ion] D when anot
18e10 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72  her thread.** or
18e20 20 70 72 6f 63 65 73 73 20 68 61 73 20 74 68 65   process has the
18e30 20 74 61 62 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a   table locked..*
18e40 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75  * The sqlite3_bu
18e50 73 79 5f 68 61 6e 64 6c 65 72 28 29 20 69 6e 74  sy_handler() int
18e60 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74  erface is used t
18e70 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b  o implement.** [
18e80 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
18e90 65 6f 75 74 28 29 5d 20 61 6e 64 20 5b 50 52 41  eout()] and [PRA
18ea0 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74  GMA busy_timeout
18eb0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  ]..**.** ^If the
18ec0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69   busy callback i
18ed0 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51  s NULL, then [SQ
18ee0 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 69 73  LITE_BUSY].** is
18ef0 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
18f00 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75  ately upon encou
18f10 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b  ntering the lock
18f20 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 20  .  ^If the busy 
18f30 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e  callback.** is n
18f40 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68  ot NULL, then th
18f50 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74  e callback might
18f60 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   be invoked with
18f70 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a   two arguments..
18f80 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
18f90 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
18fa0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
18fb0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76   a copy of the v
18fc0 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69  oid* pointer whi
18fd0 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69  ch.** is the thi
18fe0 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  rd argument to s
18ff0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
19000 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63  ler().  ^The sec
19010 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
19020 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ** the busy hand
19030 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ler callback is 
19040 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69  the number of ti
19050 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73  mes that the bus
19060 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a  y handler has.**
19070 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f   been invoked fo
19080 72 20 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69  r the same locki
19090 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74  ng event.  ^If t
190a0 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62  he.** busy callb
190b0 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74  ack returns 0, t
190c0 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61  hen no additiona
190d0 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d  l attempts are m
190e0 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73  ade to.** access
190f0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e   the database an
19100 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  d [SQLITE_BUSY] 
19110 69 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 74  is returned.** t
19120 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
19130 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61  n..** ^If the ca
19140 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
19150 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e  on-zero, then an
19160 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a  other attempt.**
19170 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65   is made to acce
19180 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ss the database 
19190 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65  and the cycle re
191a0 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  peats..**.** The
191b0 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62   presence of a b
191c0 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73  usy handler does
191d0 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74   not guarantee t
191e0 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69  hat it will be i
191f0 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74  nvoked.** when t
19200 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e  here is lock con
19210 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c  tention. ^If SQL
19220 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74  ite determines t
19230 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65  hat invoking the
19240 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72   busy.** handler
19250 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e   could result in
19260 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20   a deadlock, it 
19270 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e  will go ahead an
19280 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  d return [SQLITE
19290 5f 42 55 53 59 5d 0a 2a 2a 20 74 6f 20 74 68 65  _BUSY].** to the
192a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e 73   application ins
192b0 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67  tead of invoking
192c0 20 74 68 65 20 0a 2a 2a 20 62 75 73 79 20 68 61   the .** busy ha
192d0 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64  ndler..** Consid
192e0 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68  er a scenario wh
192f0 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20  ere one process 
19300 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61  is holding a rea
19310 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69  d lock that.** i
19320 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70  t is trying to p
19330 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65  romote to a rese
19340 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a  rved lock and.**
19350 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73   a second proces
19360 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72  s is holding a r
19370 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61  eserved lock tha
19380 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a  t it is trying.*
19390 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20  * to promote to 
193a0 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63  an exclusive loc
193b0 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72  k.  The first pr
193c0 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f  ocess cannot pro
193d0 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20  ceed.** because 
193e0 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79  it is blocked by
193f0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20   the second and 
19400 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  the second proce
19410 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f  ss cannot.** pro
19420 63 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20  ceed because it 
19430 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
19440 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74  e first.  If bot
19450 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69  h processes.** i
19460 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68  nvoke the busy h
19470 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72  andlers, neither
19480 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70   will make any p
19490 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66  rogress.  Theref
194a0 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72  ore,.** SQLite r
194b0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42  eturns [SQLITE_B
194c0 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72  USY] for the fir
194d0 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69  st process, hopi
194e0 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20  ng that this.** 
194f0 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20  will induce the 
19500 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f  first process to
19510 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61   release its rea
19520 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77  d lock and allow
19530 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70  .** the second p
19540 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65  rocess to procee
19550 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65  d..**.** ^The de
19560 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62  fault busy callb
19570 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ack is NULL..**.
19580 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f  ** ^(There can o
19590 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20  nly be a single 
195a0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66  busy handler def
195b0 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a  ined for each.**
195c0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
195d0 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67  ction].  Setting
195e0 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64   a new busy hand
195f0 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a  ler clears any.*
19600 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74  * previously set
19610 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f   handler.)^  ^No
19620 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20  te that calling 
19630 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69  [sqlite3_busy_ti
19640 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72 20 65  meout()].** or e
19650 76 61 6c 75 61 74 69 6e 67 20 5b 50 52 41 47 4d  valuating [PRAGM
19660 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 3d 4e  A busy_timeout=N
19670 5d 20 77 69 6c 6c 20 63 68 61 6e 67 65 20 74 68  ] will change th
19680 65 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65  e.** busy handle
19690 72 20 61 6e 64 20 74 68 75 73 20 63 6c 65 61 72  r and thus clear
196a0 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20   any previously 
196b0 73 65 74 20 62 75 73 79 20 68 61 6e 64 6c 65 72  set busy handler
196c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79  ..**.** The busy
196d0 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64   callback should
196e0 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63   not take any ac
196f0 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69  tions which modi
19700 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  fy the.** databa
19710 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
19720 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62  at invoked the b
19730 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 49 6e  usy handler.  In
19740 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 0a 2a 2a   other words,.**
19750 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
19760 72 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61  r is not reentra
19770 6e 74 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63  nt.  Any such ac
19780 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20  tions.** result 
19790 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68  in undefined beh
197a0 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20  avior..** .** A 
197b0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73  busy handler mus
197c0 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20  t not close the 
197d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
197e0 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61  ion.** or [prepa
197f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
19800 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
19810 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f  busy handler..*/
19820 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73  .int sqlite3_bus
19830 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65  y_handler(sqlite
19840 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a  3*, int(*)(void*
19850 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  ,int), void*);..
19860 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
19870 53 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f  Set A Busy Timeo
19880 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  ut.**.** ^This r
19890 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73  outine sets a [s
198a0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
198b0 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c  ler | busy handl
198c0 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a  er] that sleeps.
198d0 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69  ** for a specifi
198e0 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d  ed amount of tim
198f0 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69  e when a table i
19900 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20  s locked.  ^The 
19910 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20  handler.** will 
19920 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74  sleep multiple t
19930 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65  imes until at le
19940 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65  ast "ms" millise
19950 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e  conds of sleepin
19960 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75  g.** have accumu
19970 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61  lated.  ^After a
19980 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c  t least "ms" mil
19990 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
199a0 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61  eping,.** the ha
199b0 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20  ndler returns 0 
199c0 77 68 69 63 68 20 63 61 75 73 65 73 20 5b 73 71  which causes [sq
199d0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f  lite3_step()] to
199e0 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49   return.** [SQLI
199f0 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20  TE_BUSY]..**.** 
19a00 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f  ^Calling this ro
19a10 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72  utine with an ar
19a20 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e  gument less than
19a30 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72   or equal to zer
19a40 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61  o.** turns off a
19a50 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73  ll busy handlers
19a60 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20  ..**.** ^(There 
19a70 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69  can only be a si
19a80 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65  ngle busy handle
19a90 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  r for a particul
19aa0 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ar.** [database 
19ab0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20  connection] any 
19ac0 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74  any given moment
19ad0 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75  .  If another bu
19ae0 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61  sy handler.** wa
19af0 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e  s defined  (usin
19b00 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
19b10 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f  handler()]) prio
19b20 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  r to calling.** 
19b30 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68  this routine, th
19b40 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61  at other busy ha
19b50 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64  ndler is cleared
19b60 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  .)^.**.** See al
19b70 73 6f 3a 20 20 5b 50 52 41 47 4d 41 20 62 75 73  so:  [PRAGMA bus
19b80 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 69 6e  y_timeout].*/.in
19b90 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74  t sqlite3_busy_t
19ba0 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c  imeout(sqlite3*,
19bb0 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a   int ms);../*.**
19bc0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65   CAPI3REF: Conve
19bd0 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20  nience Routines 
19be0 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72  For Running Quer
19bf0 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  ies.**.** This i
19c00 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65 72  s a legacy inter
19c10 66 61 63 65 20 74 68 61 74 20 69 73 20 70 72 65  face that is pre
19c20 73 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b 77  served for backw
19c30 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
19c40 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68  ty..** Use of th
19c50 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  is interface is 
19c60 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e  not recommended.
19c70 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f  .**.** Definitio
19c80 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74  n: A <b>result t
19c90 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f  able</b> is memo
19ca0 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75 72  ry data structur
19cb0 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68 65  e created by the
19cc0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  .** [sqlite3_get
19cd0 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66  _table()] interf
19ce0 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74  ace.  A result t
19cf0 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65  able records the
19d00 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65  .** complete que
19d10 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20  ry results from 
19d20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72  one or more quer
19d30 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ies..**.** The t
19d40 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c  able conceptuall
19d50 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f  y has a number o
19d60 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d  f rows and colum
19d70 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73  ns.  But.** thes
19d80 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f  e numbers are no
19d90 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 65  t part of the re
19da0 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c  sult table itsel
19db0 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d  f.  These.** num
19dc0 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65  bers are obtaine
19dd0 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c  d separately.  L
19de0 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62  et N be the numb
19df0 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e  er of rows.** an
19e00 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65  d M be the numbe
19e10 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a  r of columns..**
19e20 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
19e30 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  le is an array o
19e40 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65  f pointers to ze
19e50 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
19e60 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20  F-8 strings..** 
19e70 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a  There are (N+1)*
19e80 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68  M elements in th
19e90 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 69  e array.  The fi
19ea0 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70  rst M pointers p
19eb0 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d  oint.** to zero-
19ec0 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
19ed0 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e  gs that  contain
19ee0 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68   the names of th
19ef0 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68  e columns..** Th
19f00 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72  e remaining entr
19f10 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f  ies all point to
19f20 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20   query results. 
19f30 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73   NULL values res
19f40 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70  ult.** in NULL p
19f50 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74  ointers.  All ot
19f60 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 69  her values are i
19f70 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65  n their UTF-8 ze
19f80 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
19f90 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e   string represen
19fa0 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e  tation as return
19fb0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
19fc0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a  olumn_text()]..*
19fd0 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  *.** A result ta
19fe0 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73  ble might consis
19ff0 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  t of one or more
1a000 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1a010 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f  ons..** It is no
1a020 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 61  t safe to pass a
1a030 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69   result table di
1a040 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74  rectly to [sqlit
1a050 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41  e3_free()]..** A
1a060 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68   result table sh
1a070 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61  ould be dealloca
1a080 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
1a090 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d  e3_free_table()]
1a0a0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20  ..**.** ^(As an 
1a0b0 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72  example of the r
1a0c0 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d  esult table form
1a0d0 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75  at, suppose a qu
1a0e0 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73  ery result.** is
1a0f0 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
1a100 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1a110 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e  pre>.**        N
1a120 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 65  ame        | Age
1a130 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d  .**        -----
1a140 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1a150 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69  --.**        Ali
1a160 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a  ce       | 43.**
1a170 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20          Bob     
1a180 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20      | 28.**     
1a190 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c     Cindy       |
1a1a0 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62   21.** </pre></b
1a1b0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1a1c0 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 63   There are two c
1a1d0 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64  olumn (M==2) and
1a1e0 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d   three rows (N==
1a1f0 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a  3).  Thus the.**
1a200 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61   result table ha
1a210 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75  s 8 entries.  Su
1a220 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74  ppose the result
1a230 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64   table is stored
1a240 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20  .** in an array 
1a250 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20  names azResult. 
1a260 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68   Then azResult h
1a270 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e  olds this conten
1a280 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  t:.**.** <blockq
1a290 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
1a2a0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1a2b0 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a  1;0] = "Name";.*
1a2c0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1a2d0 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22  t&#91;1] = "Age"
1a2e0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1a2f0 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41  sult&#91;2] = "A
1a300 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  lice";.**       
1a310 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d   azResult&#91;3]
1a320 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20   = "43";.**     
1a330 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1a340 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20  4] = "Bob";.**  
1a350 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1a360 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a  91;5] = "28";.**
1a370 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1a380 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79  &#91;6] = "Cindy
1a390 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1a3a0 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22  esult&#91;7] = "
1a3b0 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  21";.** </pre></
1a3c0 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
1a3d0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1a3e0 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e  _get_table() fun
1a3f0 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20  ction evaluates 
1a400 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73  one or more.** s
1a410 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
1a420 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
1a430 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65  s in the zero-te
1a440 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a  rminated UTF-8.*
1a450 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20  * string of its 
1a460 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e  2nd parameter an
1a470 64 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75  d returns a resu
1a480 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a  lt table to the.
1a490 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e  ** pointer given
1a4a0 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 61   in its 3rd para
1a4b0 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74  meter..**.** Aft
1a4c0 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  er the applicati
1a4d0 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  on has finished 
1a4e0 77 69 74 68 20 74 68 65 20 72 65 73 75 6c 74 20  with the result 
1a4f0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74  from sqlite3_get
1a500 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20  _table(),.** it 
1a510 6d 75 73 74 20 70 61 73 73 20 74 68 65 20 72 65  must pass the re
1a520 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e 74  sult table point
1a530 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72  er to sqlite3_fr
1a540 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72  ee_table() in or
1a550 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73  der to.** releas
1a560 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61  e the memory tha
1a570 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20  t was malloced. 
1a580 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20   Because of the 
1a590 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  way the.** [sqli
1a5a0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61  te3_malloc()] ha
1a5b0 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c  ppens within sql
1a5c0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1a5d0 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a  , the calling.**
1a5e0 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e   function must n
1a5f0 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b  ot try to call [
1a600 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
1a610 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a  directly.  Only.
1a620 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
1a630 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c  _table()] is abl
1a640 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65  e to release the
1a650 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79   memory properly
1a660 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a   and safely..**.
1a670 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  ** The sqlite3_g
1a680 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72  et_table() inter
1a690 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e  face is implemen
1a6a0 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65 72  ted as a wrapper
1a6b0 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69   around.** [sqli
1a6c0 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68  te3_exec()].  Th
1a6d0 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
1a6e0 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f  ble() routine do
1a6f0 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65  es not have acce
1a700 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74  ss.** to any int
1a710 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63  ernal data struc
1a720 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  tures of SQLite.
1a730 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74    It uses only t
1a740 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74  he public.** int
1a750 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 68  erface defined h
1a760 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65  ere.  As a conse
1a770 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74  quence, errors t
1a780 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65  hat occur in the
1a790 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65  .** wrapper laye
1a7a0 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65  r outside of the
1a7b0 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74   internal [sqlit
1a7c0 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20  e3_exec()] call 
1a7d0 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65  are not.** refle
1a7e0 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 65  cted in subseque
1a7f0 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  nt calls to [sql
1a800 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20  ite3_errcode()] 
1a810 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  or.** [sqlite3_e
1a820 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  rrmsg()]..*/.int
1a830 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1a840 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  le(.  sqlite3 *d
1a850 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41  b,          /* A
1a860 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20  n open database 
1a870 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
1a880 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51  *zSql,     /* SQ
1a890 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65  L to be evaluate
1a8a0 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70  d */.  char ***p
1a8b0 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20  azResult,    /* 
1a8c0 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71  Results of the q
1a8d0 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  uery */.  int *p
1a8e0 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20  nRow,           
1a8f0 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73  /* Number of res
1a900 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e  ult rows written
1a910 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a   here */.  int *
1a920 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20  pnColumn,       
1a930 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65   /* Number of re
1a940 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69  sult columns wri
1a950 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63  tten here */.  c
1a960 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20  har **pzErrmsg  
1a970 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73       /* Error ms
1a980 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  g written here *
1a990 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  /.);.void sqlite
1a9a0 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61  3_free_table(cha
1a9b0 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a  r **result);../*
1a9c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f  .** CAPI3REF: Fo
1a9d0 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20 50  rmatted String P
1a9e0 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e  rinting Function
1a9f0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  s.**.** These ro
1aa00 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d  utines are work-
1aa10 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70  alikes of the "p
1aa20 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20  rintf()" family 
1aa30 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  of functions.** 
1aa40 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72  from the standar
1aa50 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a  d C library..**.
1aa60 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1aa70 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71  mprintf() and sq
1aa80 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29  lite3_vmprintf()
1aa90 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20   routines write 
1aaa0 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73  their.** results
1aab0 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
1aac0 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
1aad0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  te3_malloc()]..*
1aae0 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65  * The strings re
1aaf0 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20  turned by these 
1ab00 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f  two routines sho
1ab10 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73  uld be.** releas
1ab20 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
1ab30 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72  ree()].  ^Both r
1ab40 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61  outines return a
1ab50 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
1ab60 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   if [sqlite3_mal
1ab70 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65  loc()] is unable
1ab80 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f   to allocate eno
1ab90 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f  ugh.** memory to
1aba0 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74   hold the result
1abb0 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  ing string..**.*
1abc0 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f  * ^(The sqlite3_
1abd0 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  snprintf() routi
1abe0 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f  ne is similar to
1abf0 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72   "snprintf()" fr
1ac00 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61  om.** the standa
1ac10 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54  rd C library.  T
1ac20 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69  he result is wri
1ac30 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  tten into the.**
1ac40 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64   buffer supplied
1ac50 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
1ac60 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73  arameter whose s
1ac70 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a  ize is given by.
1ac80 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72  ** the first par
1ac90 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61  ameter. Note tha
1aca0 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74  t the order of t
1acb0 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20  he.** first two 
1acc0 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65  parameters is re
1acd0 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72  versed from snpr
1ace0 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20  intf().)^  This 
1acf0 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69  is an.** histori
1ad00 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61  cal accident tha
1ad10 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65  t cannot be fixe
1ad20 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  d without breaki
1ad30 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20  ng.** backwards 
1ad40 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20  compatibility.  
1ad50 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74  ^(Note also that
1ad60 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1ad70 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61  f().** returns a
1ad80 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20   pointer to its 
1ad90 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f  buffer instead o
1ada0 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  f the number of.
1adb0 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63  ** characters ac
1adc0 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69  tually written i
1add0 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29  nto the buffer.)
1ade0 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  ^  We admit that
1adf0 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
1ae00 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69  f characters wri
1ae10 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20  tten would be a 
1ae20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75  more useful retu
1ae30 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20  rn.** value but 
1ae40 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65  we cannot change
1ae50 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
1ae60 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73  ion of sqlite3_s
1ae70 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77  nprintf().** now
1ae80 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
1ae90 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  g compatibility.
1aea0 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20  .**.** ^As long 
1aeb0 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69  as the buffer si
1aec0 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68  ze is greater th
1aed0 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33  an zero, sqlite3
1aee0 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67  _snprintf().** g
1aef0 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74  uarantees that t
1af00 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77  he buffer is alw
1af10 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  ays zero-termina
1af20 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74  ted.  ^The first
1af30 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e  .** parameter "n
1af40 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73  " is the total s
1af50 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65  ize of the buffe
1af60 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61  r, including spa
1af70 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65  ce for.** the ze
1af80 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  ro terminator.  
1af90 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73  So the longest s
1afa0 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62  tring that can b
1afb0 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20  e completely.** 
1afc0 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20  written will be 
1afd0 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a  n-1 characters..
1afe0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1aff0 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 72  e3_vsnprintf() r
1b000 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61 72 61  outine is a vara
1b010 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 73  rgs version of s
1b020 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1b030 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  )..**.** These r
1b040 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c  outines all impl
1b050 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74  ement some addit
1b060 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67  ional formatting
1b070 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  .** options that
1b080 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20   are useful for 
1b090 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c  constructing SQL
1b0a0 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20   statements..** 
1b0b0 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c  All of the usual
1b0c0 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74   printf() format
1b0d0 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70  ting options app
1b0e0 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e  ly.  In addition
1b0f0 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72  , there.** is ar
1b100 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61 6e  e "%q", "%Q", an
1b110 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a  d "%z" options..
1b120 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f  **.** ^(The %q o
1b130 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
1b140 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 73   %s in that it s
1b150 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c  ubstitutes a nul
1b160 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73  -terminated.** s
1b170 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61  tring from the a
1b180 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42  rgument list.  B
1b190 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c  ut %q also doubl
1b1a0 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 68  es every '\'' ch
1b1b0 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69  aracter..** %q i
1b1c0 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75  s designed for u
1b1d0 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 69  se inside a stri
1b1e0 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42  ng literal.)^  B
1b1f0 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20  y doubling each 
1b200 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65  '\''.** characte
1b210 72 20 69 74 20 65 73 63 61 70 65 73 20 74 68 61  r it escapes tha
1b220 74 20 63 68 61 72 61 63 74 65 72 20 61 6e 64 20  t character and 
1b230 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20  allows it to be 
1b240 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a  inserted into.**
1b250 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a   the string..**.
1b260 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  ** For example, 
1b270 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e  assume the strin
1b280 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74  g variable zText
1b290 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61   contains text a
1b2a0 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
1b2b0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1b2c0 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65  e>.**  char *zTe
1b2d0 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 61 70  xt = "It's a hap
1b2e0 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70  py day!";.** </p
1b2f0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1b300 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75  .**.** One can u
1b310 73 65 20 74 68 69 73 20 74 65 78 74 20 69 6e 20  se this text in 
1b320 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
1b330 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
1b340 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1b350 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
1b360 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70  SQL = sqlite3_mp
1b370 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e  rintf("INSERT IN
1b380 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28  TO table VALUES(
1b390 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a  '%q')", zText);.
1b3a0 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63  **  sqlite3_exec
1b3b0 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c  (db, zSQL, 0, 0,
1b3c0 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33   0);.**  sqlite3
1b3d0 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20  _free(zSQL);.** 
1b3e0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1b3f0 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73  te>.**.** Becaus
1b400 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20  e the %q format 
1b410 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20  string is used, 
1b420 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 63 74  the '\'' charact
1b430 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69  er in zText.** i
1b440 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 74 68  s escaped and th
1b450 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20  e SQL generated 
1b460 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  is as follows:.*
1b470 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1b480 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52  ><pre>.**  INSER
1b490 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41  T INTO table1 VA
1b4a0 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 68 61  LUES('It''s a ha
1b4b0 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f  ppy day!').** </
1b4c0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1b4d0 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20  >.**.** This is 
1b4e0 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77 65  correct.  Had we
1b4f0 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 61 64   used %s instead
1b500 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65   of %q, the gene
1b510 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75  rated SQL.** wou
1b520 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c  ld have looked l
1b530 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20  ike this:.**.** 
1b540 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1b550 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54  >.**  INSERT INT
1b560 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28  O table1 VALUES(
1b570 27 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61  'It's a happy da
1b580 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  y!');.** </pre><
1b590 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1b5a0 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65  ** This second e
1b5b0 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c  xample is an SQL
1b5c0 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20   syntax error.  
1b5d0 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c  As a general rul
1b5e0 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20  e you should.** 
1b5f0 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 69 6e  always use %q in
1b600 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e  stead of %s when
1b610 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20   inserting text 
1b620 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69  into a string li
1b630 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  teral..**.** ^(T
1b640 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72  he %Q option wor
1b650 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70  ks like %q excep
1b660 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73  t it also adds s
1b670 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f  ingle quotes aro
1b680 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69  und.** the outsi
1b690 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20  de of the total 
1b6a0 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f  string.  Additio
1b6b0 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61  nally, if the pa
1b6c0 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a  rameter in the.*
1b6d0 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20  * argument list 
1b6e0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
1b6f0 72 2c 20 25 51 20 73 75 62 73 74 69 74 75 74 65  r, %Q substitute
1b700 73 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c  s the text "NULL
1b710 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69  " (without.** si
1b720 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e 20  ngle quotes).)^ 
1b730 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65   So, for example
1b740 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a  , one could say:
1b750 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1b760 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
1b770 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65  r *zSQL = sqlite
1b780 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52  3_mprintf("INSER
1b790 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c  T INTO table VAL
1b7a0 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29  UES(%Q)", zText)
1b7b0 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78  ;.**  sqlite3_ex
1b7c0 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20  ec(db, zSQL, 0, 
1b7d0 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  0, 0);.**  sqlit
1b7e0 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a  e3_free(zSQL);.*
1b7f0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1b800 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  uote>.**.** The 
1b810 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20  code above will 
1b820 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74  render a correct
1b830 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
1b840 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61  n the zSQL.** va
1b850 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74  riable even if t
1b860 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c  he zText variabl
1b870 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  e is a NULL poin
1b880 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ter..**.** ^(The
1b890 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67   "%z" formatting
1b8a0 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
1b8b0 6b 65 20 22 25 73 22 20 62 75 74 20 77 69 74 68  ke "%s" but with
1b8c0 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   the.** addition
1b8d0 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65 20   that after the 
1b8e0 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20  string has been 
1b8f0 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20  read and copied 
1b900 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75  into.** the resu
1b910 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  lt, [sqlite3_fre
1b920 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f  e()] is called o
1b930 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  n the input stri
1b940 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73  ng.)^.*/.char *s
1b950 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63  qlite3_mprintf(c
1b960 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b  onst char*,...);
1b970 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76  .char *sqlite3_v
1b980 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
1b990 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63  ar*, va_list);.c
1b9a0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70  har *sqlite3_snp
1b9b0 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c  rintf(int,char*,
1b9c0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e  const char*, ...
1b9d0 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
1b9e0 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63  _vsnprintf(int,c
1b9f0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
1ba00 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a  , va_list);../*.
1ba10 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
1ba20 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53  ory Allocation S
1ba30 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54  ubsystem.**.** T
1ba40 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75  he SQLite core u
1ba50 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65 20  ses these three 
1ba60 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c  routines for all
1ba70 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69   of its own.** i
1ba80 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61  nternal memory a
1ba90 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
1baa0 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70   "Core" in the p
1bab0 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65  revious sentence
1bac0 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  .** does not inc
1bad0 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73  lude operating-s
1bae0 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 56  ystem specific V
1baf0 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
1bb00 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f  n.  The.** Windo
1bb10 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 69  ws VFS uses nati
1bb20 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  ve malloc() and 
1bb30 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20  free() for some 
1bb40 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  operations..**.*
1bb50 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  * ^The sqlite3_m
1bb60 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20  alloc() routine 
1bb70 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
1bb80 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20  r to a block.** 
1bb90 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61  of memory at lea
1bba0 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65  st N bytes in le
1bbb0 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73  ngth, where N is
1bbc0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
1bbd0 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d  ** ^If sqlite3_m
1bbe0 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c  alloc() is unabl
1bbf0 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66  e to obtain suff
1bc00 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d  icient free.** m
1bc10 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e  emory, it return
1bc20 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1bc30 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d  .  ^If the param
1bc40 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c  eter N to.** sql
1bc50 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73  ite3_malloc() is
1bc60 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76   zero or negativ
1bc70 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d  e then sqlite3_m
1bc80 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a  alloc() returns.
1bc90 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
1bca0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  r..**.** ^Callin
1bcb0 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  g sqlite3_free()
1bcc0 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20   with a pointer 
1bcd0 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72  previously retur
1bce0 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  ned.** by sqlite
1bcf0 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71  3_malloc() or sq
1bd00 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
1bd10 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65  releases that me
1bd20 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20  mory so.** that 
1bd30 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73  it might be reus
1bd40 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ed.  ^The sqlite
1bd50 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65  3_free() routine
1bd60 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69   is.** a no-op i
1bd70 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  f is called with
1bd80 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
1bd90 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c    Passing a NULL
1bda0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73   pointer.** to s
1bdb0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73  qlite3_free() is
1bdc0 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65   harmless.  Afte
1bdd0 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d  r being freed, m
1bde0 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20  emory.** should 
1bdf0 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64 20  neither be read 
1be00 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76  nor written.  Ev
1be10 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 69  en reading previ
1be20 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d  ously freed.** m
1be30 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75  emory might resu
1be40 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61  lt in a segmenta
1be50 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74  tion fault or ot
1be60 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72  her severe error
1be70 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72  ..** Memory corr
1be80 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e  uption, a segmen
1be90 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72  tation fault, or
1bea0 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72   other severe er
1beb0 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73  ror.** might res
1bec0 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66  ult if sqlite3_f
1bed0 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20  ree() is called 
1bee0 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  with a non-NULL 
1bef0 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20  pointer that.** 
1bf00 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64  was not obtained
1bf10 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61   from sqlite3_ma
1bf20 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65  lloc() or sqlite
1bf30 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a  3_realloc()..**.
1bf40 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33  ** ^(The sqlite3
1bf50 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72  _realloc() inter
1bf60 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
1bf70 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69   resize a.** pri
1bf80 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  or memory alloca
1bf90 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65  tion to be at le
1bfa0 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65  ast N bytes, whe
1bfb0 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73  re N is the.** s
1bfc0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  econd parameter.
1bfd0 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c    The memory all
1bfe0 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65  ocation to be re
1bff0 73 69 7a 65 64 20 69 73 20 74 68 65 20 66 69 72  sized is the fir
1c000 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e  st.** parameter.
1c010 29 5e 20 5e 20 49 66 20 74 68 65 20 66 69 72 73  )^ ^ If the firs
1c020 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
1c030 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1c040 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  .** is a NULL po
1c050 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62  inter then its b
1c060 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74  ehavior is ident
1c070 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a  ical to calling.
1c080 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
1c090 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69 73 20  c(N) where N is 
1c0a0 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
1c0b0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
1c0c0 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 49  realloc()..** ^I
1c0d0 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  f the second par
1c0e0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1c0f0 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a  3_realloc() is z
1c100 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69  ero or.** negati
1c110 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ve then the beha
1c120 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20  vior is exactly 
1c130 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c  the same as call
1c140 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66  ing.** sqlite3_f
1c150 72 65 65 28 50 29 20 77 68 65 72 65 20 50 20 69  ree(P) where P i
1c160 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  s the first para
1c170 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
1c180 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e  _realloc()..** ^
1c190 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1c1a0 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  ) returns a poin
1c1b0 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20  ter to a memory 
1c1c0 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66  allocation.** of
1c1d0 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
1c1e0 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c  s in size or NUL
1c1f0 4c 20 69 66 20 73 75 66 66 69 63 69 65 6e 74 20  L if sufficient 
1c200 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 61 69  memory is unavai
1c210 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20  lable..** ^If M 
1c220 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  is the size of t
1c230 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
1c240 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c  ion, then min(N,
1c250 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74  M) bytes.** of t
1c260 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
1c270 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69  ion are copied i
1c280 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e  nto the beginnin
1c290 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75  g of buffer retu
1c2a0 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
1c2b0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64  e3_realloc() and
1c2c0 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
1c2d0 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a  ation is freed..
1c2e0 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72  ** ^If sqlite3_r
1c2f0 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73  ealloc() returns
1c300 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20   NULL, then the 
1c310 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
1c320 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 65 64  .** is not freed
1c330 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d  ..**.** ^The mem
1c340 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 20  ory returned by 
1c350 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1c360 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61   and sqlite3_rea
1c370 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77  lloc().** is alw
1c380 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  ays aligned to a
1c390 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74  t least an 8 byt
1c3a0 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74  e boundary, or t
1c3b0 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f  o a.** 4 byte bo
1c3c0 75 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b 53  undary if the [S
1c3d0 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49  QLITE_4_BYTE_ALI
1c3e0 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d  GNED_MALLOC] com
1c3f0 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74  pile-time.** opt
1c400 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  ion is used..**.
1c410 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72  ** In SQLite ver
1c420 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33  sion 3.5.0 and 3
1c430 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73  .5.1, it was pos
1c440 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a  sible to define.
1c450 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d  ** the SQLITE_OM
1c460 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41  IT_MEMORY_ALLOCA
1c470 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64  TION which would
1c480 20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74   cause the built
1c490 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  -in.** implement
1c4a0 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72  ation of these r
1c4b0 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d  outines to be om
1c4c0 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70  itted.  That cap
1c4d0 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f  ability.** is no
1c4e0 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64   longer provided
1c4f0 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e  .  Only built-in
1c500 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
1c510 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a  rs can be used..
1c520 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53  **.** Prior to S
1c530 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
1c540 37 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 6f 77  7.10, the Window
1c550 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c  s OS interface l
1c560 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74  ayer called.** t
1c570 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63  he system malloc
1c580 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69  () and free() di
1c590 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76  rectly when conv
1c5a0 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61  erting.** filena
1c5b0 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20  mes between the 
1c5c0 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75  UTF-8 encoding u
1c5d0 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a  sed by SQLite.**
1c5e0 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69   and whatever fi
1c5f0 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20  lename encoding 
1c600 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70  is used by the p
1c610 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77  articular Window
1c620 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f  s.** installatio
1c630 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63  n.  Memory alloc
1c640 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 65 72  ation errors wer
1c650 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a  e detected, but.
1c660 2a 2a 20 74 68 65 79 20 77 65 72 65 20 72 65 70  ** they were rep
1c670 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53  orted back as [S
1c680 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20  QLITE_CANTOPEN] 
1c690 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f  or.** [SQLITE_IO
1c6a0 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e  ERR] rather than
1c6b0 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e   [SQLITE_NOMEM].
1c6c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74  .**.** The point
1c6d0 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  er arguments to 
1c6e0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1c6f0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
1c700 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74  alloc()].** must
1c710 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20   be either NULL 
1c720 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73  or else pointers
1c730 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61   obtained from a
1c740 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61   prior.** invoca
1c750 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
1c760 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73  _malloc()] or [s
1c770 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1c780 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e  ] that have.** n
1c790 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65  ot yet been rele
1c7a0 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ased..**.** The 
1c7b0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
1c7c0 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69   not read or wri
1c7d0 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a  te any part of.*
1c7e0 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d  * a block of mem
1c7f0 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73  ory after it has
1c800 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75   been released u
1c810 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
1c820 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c  _free()] or [sql
1c830 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e  ite3_realloc()].
1c840 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
1c850 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76  3_malloc(int);.v
1c860 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61  oid *sqlite3_rea
1c870 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29  lloc(void*, int)
1c880 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66  ;.void sqlite3_f
1c890 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  ree(void*);../*.
1c8a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
1c8b0 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74  ory Allocator St
1c8c0 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53  atistics.**.** S
1c8d0 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74  QLite provides t
1c8e0 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61  hese two interfa
1c8f0 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e  ces for reportin
1c900 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a  g on the status.
1c910 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
1c920 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73  e3_malloc()], [s
1c930 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20  qlite3_free()], 
1c940 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
1c950 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69  lloc()].** routi
1c960 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20  nes, which form 
1c970 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  the built-in mem
1c980 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
1c990 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20  ubsystem..**.** 
1c9a0 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65  ^The [sqlite3_me
1c9b0 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75  mory_used()] rou
1c9c0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
1c9d0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
1c9e0 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75  .** of memory cu
1c9f0 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64  rrently outstand
1ca00 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75  ing (malloced bu
1ca10 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a  t not freed)..**
1ca20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d   ^The [sqlite3_m
1ca30 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
1ca40 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  )] routine retur
1ca50 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a  ns the maximum.*
1ca60 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69  * value of [sqli
1ca70 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
1ca80 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 67  )] since the hig
1ca90 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20  h-water mark.** 
1caa0 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20  was last reset. 
1cab0 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74   ^The values ret
1cac0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
1cad0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
1cae0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
1caf0 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
1cb00 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79  r()] include any
1cb10 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64   overhead.** add
1cb20 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20  ed by SQLite in 
1cb30 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  its implementati
1cb40 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  on of [sqlite3_m
1cb50 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74  alloc()],.** but
1cb60 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64   not overhead ad
1cb70 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 75  ded by the any u
1cb80 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d  nderlying system
1cb90 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74   library.** rout
1cba0 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74  ines that [sqlit
1cbb0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79  e3_malloc()] may
1cbc0 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   call..**.** ^Th
1cbd0 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61  e memory high-wa
1cbe0 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65  ter mark is rese
1cbf0 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74  t to the current
1cc00 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71   value of.** [sq
1cc10 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
1cc20 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79  d()] if and only
1cc30 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
1cc40 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  r to.** [sqlite3
1cc50 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
1cc60 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e  r()] is true.  ^
1cc70 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  The value return
1cc80 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65  ed.** by [sqlite
1cc90 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1cca0 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 69  er(1)] is the hi
1ccb0 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a  gh-water mark.**
1ccc0 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65   prior to the re
1ccd0 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  set..*/.sqlite3_
1cce0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65  int64 sqlite3_me
1ccf0 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b  mory_used(void);
1cd00 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
1cd10 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1cd20 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65  ghwater(int rese
1cd30 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  tFlag);../*.** C
1cd40 41 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d  API3REF: Pseudo-
1cd50 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65  Random Number Ge
1cd60 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51  nerator.**.** SQ
1cd70 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20  Lite contains a 
1cd80 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65  high-quality pse
1cd90 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65  udo-random numbe
1cda0 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e  r generator (PRN
1cdb0 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65  G) used to.** se
1cdc0 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57  lect random [ROW
1cdd0 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65  ID | ROWIDs] whe
1cde0 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20  n inserting new 
1cdf0 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74  records into a t
1ce00 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72  able that.** alr
1ce10 65 61 64 79 20 75 73 65 73 20 74 68 65 20 6c 61  eady uses the la
1ce20 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b  rgest possible [
1ce30 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e  ROWID].  The PRN
1ce40 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66  G is also used f
1ce50 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d  or.** the build-
1ce60 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20  in random() and 
1ce70 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c  randomblob() SQL
1ce80 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69   functions.  Thi
1ce90 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f  s interface allo
1cea0 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  ws.** applicatio
1ceb0 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  ns to access the
1cec0 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f   same PRNG for o
1ced0 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a  ther purposes..*
1cee0 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20  *.** ^A call to 
1cef0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f  this routine sto
1cf00 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72  res N bytes of r
1cf10 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62  andomness into b
1cf20 75 66 66 65 72 20 50 2e 0a 2a 2a 20 5e 49 66 20  uffer P..** ^If 
1cf30 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f  N is less than o
1cf40 6e 65 2c 20 74 68 65 6e 20 50 20 63 61 6e 20 62  ne, then P can b
1cf50 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
1cf60 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73  ..**.** ^If this
1cf70 20 72 6f 75 74 69 6e 65 20 68 61 73 20 6e 6f 74   routine has not
1cf80 20 62 65 65 6e 20 70 72 65 76 69 6f 75 73 6c 79   been previously
1cf90 20 63 61 6c 6c 65 64 20 6f 72 20 69 66 20 74 68   called or if th
1cfa0 65 20 70 72 65 76 69 6f 75 73 0a 2a 2a 20 63 61  e previous.** ca
1cfb0 6c 6c 20 68 61 64 20 4e 20 6c 65 73 73 20 74 68  ll had N less th
1cfc0 61 6e 20 6f 6e 65 2c 20 74 68 65 6e 20 74 68 65  an one, then the
1cfd0 20 50 52 4e 47 20 69 73 20 73 65 65 64 65 64 20   PRNG is seeded 
1cfe0 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73  using randomness
1cff0 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  .** obtained fro
1d000 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  m the xRandomnes
1d010 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  s method of the 
1d020 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
1d030 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  _vfs] object..**
1d040 20 5e 49 66 20 74 68 65 20 70 72 65 76 69 6f 75   ^If the previou
1d050 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72  s call to this r
1d060 6f 75 74 69 6e 65 20 68 61 64 20 61 6e 20 4e 20  outine had an N 
1d070 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 74 68 65  of 1 or more the
1d080 6e 0a 2a 2a 20 74 68 65 20 70 73 65 75 64 6f 2d  n.** the pseudo-
1d090 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65  randomness is ge
1d0a0 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72  nerated.** inter
1d0b0 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75  nally and withou
1d0c0 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68  t recourse to th
1d0d0 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  e [sqlite3_vfs] 
1d0e0 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d  xRandomness.** m
1d0f0 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73  ethod..*/.void s
1d100 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73  qlite3_randomnes
1d110 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50  s(int N, void *P
1d120 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1d130 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65  EF: Compile-Time
1d140 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43   Authorization C
1d150 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e  allbacks.**.** ^
1d160 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67  This routine reg
1d170 69 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72  isters an author
1d180 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69  izer callback wi
1d190 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  th a particular.
1d1a0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
1d1b0 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69  nection], suppli
1d1c0 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ed in the first 
1d1d0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  argument..** ^Th
1d1e0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1d1f0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
1d200 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   as SQL statemen
1d210 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d  ts are being com
1d220 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c  piled.** by [sql
1d230 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
1d240 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20  or its variants 
1d250 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1d260 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  _v2()],.** [sqli
1d270 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
1d280 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
1d290 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20  epare16_v2()].  
1d2a0 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70  ^At various.** p
1d2b0 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65  oints during the
1d2c0 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f   compilation pro
1d2d0 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69  cess, as logic i
1d2e0 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a  s being created.
1d2f0 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61  ** to perform va
1d300 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74  rious actions, t
1d310 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1d320 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
1d330 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74  d to.** see if t
1d340 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65  hose actions are
1d350 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20   allowed.  ^The 
1d360 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1d370 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65  ack should.** re
1d380 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
1d390 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63   to allow the ac
1d3a0 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47  tion, [SQLITE_IG
1d3b0 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f  NORE] to disallo
1d3c0 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69  w the.** specifi
1d3d0 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c  c action but all
1d3e0 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  ow the SQL state
1d3f0 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65  ment to continue
1d400 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c   to be.** compil
1d410 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  ed, or [SQLITE_D
1d420 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68  ENY] to cause th
1d430 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61  e entire SQL sta
1d440 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20  tement to be.** 
1d450 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e  rejected with an
1d460 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65   error.  ^If the
1d470 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1d480 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20  back returns.** 
1d490 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20  any value other 
1d4a0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e  than [SQLITE_IGN
1d4b0 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b  ORE], [SQLITE_OK
1d4c0 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45  ], or [SQLITE_DE
1d4d0 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  NY].** then the 
1d4e0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1d4f0 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61  _v2()] or equiva
1d500 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74  lent call that t
1d510 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20  riggered.** the 
1d520 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20  authorizer will 
1d530 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72  fail with an err
1d540 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a  or message..**.*
1d550 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  * When the callb
1d560 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
1d570 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65  ITE_OK], that me
1d580 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f  ans the operatio
1d590 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69  n.** requested i
1d5a0 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65  s ok.  ^When the
1d5b0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1d5c0 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c  s [SQLITE_DENY],
1d5d0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
1d5e0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
1d5f0 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c  r equivalent cal
1d600 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
1d610 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
1d620 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74  er will fail wit
1d630 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  h an error messa
1d640 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68  ge explaining th
1d650 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20  at.** access is 
1d660 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e  denied. .**.** ^
1d670 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
1d680 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ter to the autho
1d690 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
1d6a0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
1d6b0 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74  third.** paramet
1d6c0 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
1d6d0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1d6e0 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54  () interface. ^T
1d6f0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1d700 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61  ter.** to the ca
1d710 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74  llback is an int
1d720 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50  eger [SQLITE_COP
1d730 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d  Y | action code]
1d740 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a   that specifies.
1d750 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  ** the particula
1d760 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  r action to be a
1d770 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20  uthorized. ^The 
1d780 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69  third through si
1d790 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  xth parameters.*
1d7a0 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  * to the callbac
1d7b0 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69  k are zero-termi
1d7c0 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68  nated strings th
1d7d0 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74  at contain addit
1d7e0 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73  ional.** details
1d7f0 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f   about the actio
1d800 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a  n to be authoriz
1d810 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
1d820 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73  e action code is
1d830 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a   [SQLITE_READ].*
1d840 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61  * and the callba
1d850 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
1d860 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20  TE_IGNORE] then 
1d870 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
1d880 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74   statement] stat
1d890 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75  ement is constru
1d8a0 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 74 75  cted to substitu
1d8b0 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c  te.** a NULL val
1d8c0 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74  ue in place of t
1d8d0 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  he table column 
1d8e0 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a  that would have.
1d8f0 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 20  ** been read if 
1d900 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20  [SQLITE_OK] had 
1d910 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20  been returned.  
1d920 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  The [SQLITE_IGNO
1d930 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61  RE].** return ca
1d940 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e  n be used to den
1d950 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75  y an untrusted u
1d960 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e  ser access to in
1d970 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75  dividual.** colu
1d980 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a  mns of a table..
1d990 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f  ** ^If the actio
1d9a0 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54  n code is [SQLIT
1d9b0 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68  E_DELETE] and th
1d9c0 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
1d9d0 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47  ns.** [SQLITE_IG
1d9e0 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b  NORE] then the [
1d9f0 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f  DELETE] operatio
1da00 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 20 74  n proceeds but t
1da10 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20  he.** [truncate 
1da20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73  optimization] is
1da30 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c   disabled and al
1da40 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74  l rows are delet
1da50 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e  ed individually.
1da60 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72  .**.** An author
1da70 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65  izer is used whe
1da80 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
1da90 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a  re | preparing].
1daa0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
1dab0 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73  s from an untrus
1dac0 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65  ted source, to e
1dad0 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53  nsure that the S
1dae0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
1daf0 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61   do not try to a
1db00 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20  ccess data they 
1db10 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20  are not allowed 
1db20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20  to see, or that 
1db30 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74  they do not.** t
1db40 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61  ry to execute ma
1db50 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e  licious statemen
1db60 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74  ts that damage t
1db70 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f  he database.  Fo
1db80 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e  r.** example, an
1db90 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79   application may
1dba0 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f   allow a user to
1dbb0 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79   enter arbitrary
1dbc0 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20  .** SQL queries 
1dbd0 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62  for evaluation b
1dbe0 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42  y a database.  B
1dbf0 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ut the applicati
1dc00 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77  on does.** not w
1dc10 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20  ant the user to 
1dc20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20  be able to make 
1dc30 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65  arbitrary change
1dc40 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61  s to the.** data
1dc50 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72  base.  An author
1dc60 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20  izer could then 
1dc70 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20  be put in place 
1dc80 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65  while the.** use
1dc90 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73  r-entered SQL is
1dca0 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   being [sqlite3_
1dcb0 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72  prepare | prepar
1dcc0 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61  ed] that.** disa
1dcd0 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67  llows everything
1dce0 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d   except [SELECT]
1dcf0 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
1dd00 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
1dd10 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f  that need to pro
1dd20 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e  cess SQL from un
1dd30 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a  trusted sources.
1dd40 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f  ** might also co
1dd50 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20  nsider lowering 
1dd60 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20  resource limits 
1dd70 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c  using [sqlite3_l
1dd80 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c  imit()].** and l
1dd90 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65  imiting database
1dda0 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20   size using the 
1ddb0 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d  [max_page_count]
1ddc0 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20   [PRAGMA].** in 
1ddd0 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e  addition to usin
1dde0 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e  g an authorizer.
1ddf0 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20  .**.** ^(Only a 
1de00 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65  single authorize
1de10 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63  r can be in plac
1de20 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20  e on a database 
1de30 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74  connection.** at
1de40 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63   a time.  Each c
1de50 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
1de60 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76  et_authorizer ov
1de70 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70  errides the.** p
1de80 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20  revious call.)^ 
1de90 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61 75   ^Disable the au
1dea0 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74  thorizer by inst
1deb0 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61  alling a NULL ca
1dec0 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61  llback..** The a
1ded0 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73  uthorizer is dis
1dee0 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
1def0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68  ..**.** The auth
1df00 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1df10 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
1df20 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
1df30 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
1df40 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1df50 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
1df60 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1df70 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74  lback..** Note t
1df80 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hat [sqlite3_pre
1df90 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
1dfa0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1dfb0 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69  both modify thei
1dfc0 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
1dfd0 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68  nnections for th
1dfe0 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f  e meaning of "mo
1dff0 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61  dify" in this pa
1e000 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e  ragraph..**.** ^
1e010 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  When [sqlite3_pr
1e020 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75  epare_v2()] is u
1e030 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 61  sed to prepare a
1e040 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a   statement, the.
1e050 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67  ** statement mig
1e060 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 72 65  ht be re-prepare
1e070 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65  d during [sqlite
1e080 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f  3_step()] due to
1e090 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68   a .** schema ch
1e0a0 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68  ange.  Hence, th
1e0b0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
1e0c0 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74  ould ensure that
1e0d0 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20   the.** correct 
1e0e0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1e0f0 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70  ack remains in p
1e100 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20  lace during the 
1e110 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1e120 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68  ..**.** ^Note th
1e130 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  at the authorize
1e140 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
1e150 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e  voked only durin
1e160 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  g.** [sqlite3_pr
1e170 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20  epare()] or its 
1e180 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f  variants.  Autho
1e190 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a  rization is not.
1e1a0 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72  ** performed dur
1e1b0 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76  ing statement ev
1e1c0 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c  aluation in [sql
1e1d0 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e  ite3_step()], un
1e1e0 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65  less.** as state
1e1f0 64 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75  d in the previou
1e200 73 20 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c  s paragraph, sql
1e210 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f  ite3_step() invo
1e220 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70  kes.** sqlite3_p
1e230 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72  repare_v2() to r
1e240 65 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65  eprepare a state
1e250 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73 63 68  ment after a sch
1e260 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69  ema change..*/.i
1e270 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  nt sqlite3_set_a
1e280 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c  uthorizer(.  sql
1e290 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78  ite3*,.  int (*x
1e2a0 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  Auth)(void*,int,
1e2b0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
1e2c0 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
1e2d0 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  ar*,const char*)
1e2e0 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44  ,.  void *pUserD
1e2f0 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ata.);../*.** CA
1e300 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a  PI3REF: Authoriz
1e310 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a  er Return Codes.
1e320 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  **.** The [sqlit
1e330 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1e340 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63  r | authorizer c
1e350 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1e360 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e  ] must.** return
1e370 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
1e380 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68  OK] or one of th
1e390 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74  ese two constant
1e3a0 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f  s in order.** to
1e3b0 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77   signal SQLite w
1e3c0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
1e3d0 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d  e action is perm
1e3e0 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a  itted.  See the.
1e3f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  ** [sqlite3_set_
1e400 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
1e410 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74  horizer document
1e420 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74  ation] for addit
1e430 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61  ional.** informa
1e440 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  tion..**.** Note
1e450 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49 47 4e   that SQLITE_IGN
1e460 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73 65 64  ORE is also used
1e470 20 61 73 20 61 20 5b 63 6f 6e 66 6c 69 63 74 20   as a [conflict 
1e480 72 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d  resolution mode]
1e490 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 66 72 6f  .** returned fro
1e4a0 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  m the [sqlite3_v
1e4b0 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28  tab_on_conflict(
1e4c0 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f  )] interface..*/
1e4d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1e4e0 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62  DENY   1   /* Ab
1e4f0 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74  ort the SQL stat
1e500 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72  ement with an er
1e510 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ror */.#define S
1e520 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20  QLITE_IGNORE 2  
1e530 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20   /* Don't allow 
1e540 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27  access, but don'
1e550 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72  t generate an er
1e560 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  ror */../*.** CA
1e570 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a  PI3REF: Authoriz
1e580 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a  er Action Codes.
1e590 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  **.** The [sqlit
1e5a0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1e5b0 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  r()] interface r
1e5c0 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62  egisters a callb
1e5d0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ack function.** 
1e5e0 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20  that is invoked 
1e5f0 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72  to authorize cer
1e600 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  tain SQL stateme
1e610 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65  nt actions.  The
1e620 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
1e630 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c  eter to the call
1e640 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67  back is an integ
1e650 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65  er code that spe
1e660 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61  cifies.** what a
1e670 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61  ction is being a
1e680 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73  uthorized.  Thes
1e690 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65  e are the intege
1e6a0 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74  r action codes t
1e6b0 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f  hat.** the autho
1e6c0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  rizer callback m
1e6d0 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a  ay be passed..**
1e6e0 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e  .** These action
1e6f0 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67   code values sig
1e700 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f  nify what kind o
1e710 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74  f operation is t
1e720 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a  o be.** authoriz
1e730 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64  ed.  The 3rd and
1e740 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20   4th parameters 
1e750 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61  to the authoriza
1e760 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  tion.** callback
1e770 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62   function will b
1e780 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20  e parameters or 
1e790 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f  NULL depending o
1e7a0 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65  n which of these
1e7b0 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65  .** codes is use
1e7c0 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
1e7d0 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68  parameter.  ^(Th
1e7e0 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
1e7f0 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72  to the.** author
1e800 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
1e810 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
1e820 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e   database ("main
1e830 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74  ", "temp",.** et
1e840 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c  c.) if applicabl
1e850 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70  e.)^  ^The 6th p
1e860 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
1e870 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1e880 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61  ack.** is the na
1e890 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d  me of the inner-
1e8a0 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20  most trigger or 
1e8b0 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73  view that is res
1e8c0 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20  ponsible for.** 
1e8d0 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d  the access attem
1e8e0 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  pt or NULL if th
1e8f0 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  is access attemp
1e900 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72  t is directly fr
1e910 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20  om.** top-level 
1e920 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a  SQL code..*/./**
1e930 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1e940 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1e950 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a  ********* 3rd **
1e960 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a  ********** 4th *
1e970 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66  **********/.#def
1e980 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1e990 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  E_INDEX         
1e9a0 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61   1   /* Index Na
1e9b0 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
1e9c0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1e9d0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1e9e0 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
1e9f0 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  2   /* Table Nam
1ea00 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1ea10 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1ea20 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1ea30 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33  TEMP_INDEX     3
1ea40 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
1ea50 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
1ea60 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1ea70 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1ea80 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20  EMP_TABLE     4 
1ea90 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1eaa0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1eab0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1eac0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
1ead0 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20  MP_TRIGGER   5  
1eae0 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
1eaf0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1eb00 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1eb10 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
1eb20 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20  P_VIEW      6   
1eb30 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
1eb40 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1eb50 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1eb60 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47  LITE_CREATE_TRIG
1eb70 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f  GER        7   /
1eb80 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
1eb90 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1eba0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1ebb0 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20  ITE_CREATE_VIEW 
1ebc0 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a            8   /*
1ebd0 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
1ebe0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1ebf0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1ec00 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20  TE_DELETE       
1ec10 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20           9   /* 
1ec20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1ec30 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1ec40 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1ec50 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20  E_DROP_INDEX    
1ec60 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49         10   /* I
1ec70 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
1ec80 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1ec90 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1eca0 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20  _DROP_TABLE     
1ecb0 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61        11   /* Ta
1ecc0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
1ecd0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1ece0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1ecf0 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20  DROP_TEMP_INDEX 
1ed00 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64       12   /* Ind
1ed10 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
1ed20 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1ed30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1ed40 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20  ROP_TEMP_TABLE  
1ed50 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c      13   /* Tabl
1ed60 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1ed70 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1ed80 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1ed90 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20  OP_TEMP_TRIGGER 
1eda0 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67     14   /* Trigg
1edb0 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
1edc0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1edd0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1ede0 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20  P_TEMP_VIEW     
1edf0 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e    15   /* View N
1ee00 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
1ee10 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1ee20 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1ee30 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20  _TRIGGER        
1ee40 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72   16   /* Trigger
1ee50 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
1ee60 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1ee70 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1ee80 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20  VIEW            
1ee90 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d  17   /* View Nam
1eea0 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
1eeb0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1eec0 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54  ne SQLITE_INSERT
1eed0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
1eee0 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  8   /* Table Nam
1eef0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1ef00 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1ef10 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20  e SQLITE_PRAGMA 
1ef20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39                19
1ef30 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d     /* Pragma Nam
1ef40 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72  e     1st arg or
1ef50 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65   NULL */.#define
1ef60 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20   SQLITE_READ    
1ef70 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20               20 
1ef80 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1ef90 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65       Column Name
1efa0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1efb0 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20  SQLITE_SELECT   
1efc0 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20              21  
1efd0 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20   /* NULL        
1efe0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1eff0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1f000 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f  QLITE_TRANSACTIO
1f010 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20  N          22   
1f020 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20  /* Operation    
1f030 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1f040 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1f050 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20  LITE_UPDATE     
1f060 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f            23   /
1f070 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1f080 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20    Column Name   
1f090 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1f0a0 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20  ITE_ATTACH      
1f0b0 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a           24   /*
1f0c0 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20   Filename       
1f0d0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1f0e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f0f0 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20  TE_DETACH       
1f100 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20          25   /* 
1f110 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20  Database Name   
1f120 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1f130 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f140 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20  E_ALTER_TABLE   
1f150 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44         26   /* D
1f160 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54  atabase Name   T
1f170 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1f180 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f190 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20  _REINDEX        
1f1a0 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e        27   /* In
1f1b0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  dex Name      NU
1f1c0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1f1d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f1e0 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20  ANALYZE         
1f1f0 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62       28   /* Tab
1f200 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1f210 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1f220 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1f230 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20  REATE_VTABLE    
1f240 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c      29   /* Tabl
1f250 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75  e Name      Modu
1f260 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  le Name     */.#
1f270 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1f280 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20  OP_VTABLE       
1f290 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65     30   /* Table
1f2a0 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c   Name      Modul
1f2b0 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  e Name     */.#d
1f2c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e  efine SQLITE_FUN
1f2d0 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20  CTION           
1f2e0 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    31   /* NULL  
1f2f0 20 20 20 20 20 20 20 20 20 20 46 75 6e 63 74 69            Functi
1f300 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65  on Name   */.#de
1f310 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45  fine SQLITE_SAVE
1f320 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20 20  POINT           
1f330 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69   32   /* Operati
1f340 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f 69  on       Savepoi
1f350 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66  nt Name  */.#def
1f360 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20  ine SQLITE_COPY 
1f370 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1f380 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65   0   /* No longe
1f390 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e  r used */.#defin
1f3a0 65 20 53 51 4c 49 54 45 5f 52 45 43 55 52 53 49  e SQLITE_RECURSI
1f3b0 56 45 20 20 20 20 20 20 20 20 20 20 20 20 33 33  VE            33
1f3c0 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
1f3d0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1f3e0 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20        */../*.** 
1f3f0 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e  CAPI3REF: Tracin
1f400 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20  g And Profiling 
1f410 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
1f420 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
1f430 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b  egister callback
1f440 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
1f450 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a  can be used for.
1f460 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70  ** tracing and p
1f470 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65  rofiling the exe
1f480 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74  cution of SQL st
1f490 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
1f4a0 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ^The callback fu
1f4b0 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
1f4c0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61  d by sqlite3_tra
1f4d0 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20  ce() is invoked 
1f4e0 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69  at.** various ti
1f4f0 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20  mes when an SQL 
1f500 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69  statement is bei
1f510 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74  ng run by [sqlit
1f520 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e  e3_step()]..** ^
1f530 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63  The sqlite3_trac
1f540 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  e() callback is 
1f550 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55  invoked with a U
1f560 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f  TF-8 rendering o
1f570 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61  f the.** SQL sta
1f580 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74  tement text as t
1f590 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72  he statement fir
1f5a0 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74  st begins execut
1f5b0 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69  ing..** ^(Additi
1f5c0 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61  onal sqlite3_tra
1f5d0 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d  ce() callbacks m
1f5e0 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73  ight occur.** as
1f5f0 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20   each triggered 
1f600 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e  subprogram is en
1f610 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c  tered.  The call
1f620 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65  backs for trigge
1f630 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20  rs.** contain a 
1f640 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e  UTF-8 SQL commen
1f650 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65  t that identifie
1f660 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e  s the trigger.)^
1f670 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  .**.** The [SQLI
1f680 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49  TE_TRACE_SIZE_LI
1f690 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  MIT] compile-tim
1f6a0 65 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  e option can be 
1f6b0 75 73 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a  used to limit.**
1f6c0 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b   the length of [
1f6d0 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 5d  bound parameter]
1f6e0 20 65 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68   expansion in th
1f6f0 65 20 6f 75 74 70 75 74 20 6f 66 20 73 71 6c 69  e output of sqli
1f700 74 65 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a  te3_trace()..**.
1f710 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b  ** ^The callback
1f720 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74   function regist
1f730 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ered by sqlite3_
1f740 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76  profile() is inv
1f750 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20  oked.** as each 
1f760 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69  SQL statement fi
1f770 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72  nishes.  ^The pr
1f780 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63  ofile callback c
1f790 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f  ontains.** the o
1f7a0 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e  riginal statemen
1f7b0 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73  t text and an es
1f7c0 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63  timate of wall-c
1f7d0 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20  lock time.** of 
1f7e0 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74  how long that st
1f7f0 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20  atement took to 
1f800 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69  run.  ^The profi
1f810 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74  le callback.** t
1f820 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20  ime is in units 
1f830 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20  of nanoseconds, 
1f840 68 6f 77 65 76 65 72 20 74 68 65 20 63 75 72 72  however the curr
1f850 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ent implementati
1f860 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61  on.** is only ca
1f870 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65  pable of millise
1f880 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20  cond resolution 
1f890 73 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73 74  so the six least
1f8a0 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20   significant.** 
1f8b0 64 69 67 69 74 73 20 69 6e 20 74 68 65 20 74 69  digits in the ti
1f8c0 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65  me are meaningle
1f8d0 73 73 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  ss.  Future vers
1f8e0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a  ions of SQLite.*
1f8f0 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20  * might provide 
1f900 67 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69  greater resoluti
1f910 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c  on on the profil
1f920 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68  er callback.  Th
1f930 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f  e.** sqlite3_pro
1f940 66 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  file() function 
1f950 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78  is considered ex
1f960 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69  perimental and i
1f970 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20  s.** subject to 
1f980 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65  change in future
1f990 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
1f9a0 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ite..*/.void *sq
1f9b0 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69  lite3_trace(sqli
1f9c0 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61  te3*, void(*xTra
1f9d0 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20  ce)(void*,const 
1f9e0 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  char*), void*);.
1f9f0 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e  SQLITE_EXPERIMEN
1fa00 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  TAL void *sqlite
1fa10 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65  3_profile(sqlite
1fa20 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72  3*,.   void(*xPr
1fa30 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e  ofile)(void*,con
1fa40 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33  st char*,sqlite3
1fa50 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29  _uint64), void*)
1fa60 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1fa70 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65 73  F: Query Progres
1fa80 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a  s Callbacks.**.*
1fa90 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 70  * ^The sqlite3_p
1faa0 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
1fab0 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 61  D,N,X,P) interfa
1fac0 63 65 20 63 61 75 73 65 73 20 74 68 65 20 63 61  ce causes the ca
1fad0 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69  llback.** functi
1fae0 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b  on X to be invok
1faf0 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20  ed periodically 
1fb00 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e  during long runn
1fb10 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ing calls to.** 
1fb20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
1fb30 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
1fb40 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1fb50 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72  get_table()] for
1fb60 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
1fb70 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65  nection D.  An e
1fb80 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74  xample use for t
1fb90 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  his.** interface
1fba0 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55   is to keep a GU
1fbb0 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e 67  I updated during
1fbc0 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a   a large query..
1fbd0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d  **.** ^The param
1fbe0 65 74 65 72 20 50 20 69 73 20 70 61 73 73 65 64  eter P is passed
1fbf0 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20   through as the 
1fc00 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74  only parameter t
1fc10 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61  o the .** callba
1fc20 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20  ck function X.  
1fc30 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e  ^The parameter N
1fc40 20 69 73 20 74 68 65 20 61 70 70 72 6f 78 69 6d   is the approxim
1fc50 61 74 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a  ate number of .*
1fc60 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69  * [virtual machi
1fc70 6e 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d  ne instructions]
1fc80 20 74 68 61 74 20 61 72 65 20 65 76 61 6c 75 61   that are evalua
1fc90 74 65 64 20 62 65 74 77 65 65 6e 20 73 75 63 63  ted between succ
1fca0 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61  essive.** invoca
1fcb0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c  tions of the cal
1fcc0 6c 62 61 63 6b 20 58 2e 20 20 5e 49 66 20 4e 20  lback X.  ^If N 
1fcd0 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65  is less than one
1fce0 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72 65   then the progre
1fcf0 73 73 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69 73  ss.** handler is
1fd00 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a   disabled..**.**
1fd10 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20   ^Only a single 
1fd20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
1fd30 20 6d 61 79 20 62 65 20 64 65 66 69 6e 65 64 20   may be defined 
1fd40 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a  at one time per.
1fd50 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
1fd60 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e  nection]; settin
1fd70 67 20 61 20 6e 65 77 20 70 72 6f 67 72 65 73 73  g a new progress
1fd80 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73   handler cancels
1fd90 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e   the.** old one.
1fda0 20 20 5e 53 65 74 74 69 6e 67 20 70 61 72 61 6d    ^Setting param
1fdb0 65 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64  eter X to NULL d
1fdc0 69 73 61 62 6c 65 73 20 74 68 65 20 70 72 6f 67  isables the prog
1fdd0 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  ress handler..**
1fde0 20 5e 54 68 65 20 70 72 6f 67 72 65 73 73 20 68   ^The progress h
1fdf0 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 64  andler is also d
1fe00 69 73 61 62 6c 65 64 20 62 79 20 73 65 74 74 69  isabled by setti
1fe10 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 20  ng N to a value 
1fe20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a  less.** than 1..
1fe30 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72  **.** ^If the pr
1fe40 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20  ogress callback 
1fe50 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
1fe60 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20  , the operation 
1fe70 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65  is.** interrupte
1fe80 64 2e 20 20 54 68 69 73 20 66 65 61 74 75 72 65  d.  This feature
1fe90 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
1fea0 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22  implement a.** "
1feb0 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f  Cancel" button o
1fec0 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65 73 73  n a GUI progress
1fed0 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a   dialog box..**.
1fee0 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73 20  ** The progress 
1fef0 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
1ff00 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
1ff10 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
1ff20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
1ff30 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1ff40 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
1ff50 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
1ff60 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ler..** Note tha
1ff70 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  t [sqlite3_prepa
1ff80 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
1ff90 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f  lite3_step()] bo
1ffa0 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a  th modify their.
1ffb0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
1ffc0 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20  ections for the 
1ffd0 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69  meaning of "modi
1ffe0 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61  fy" in this para
1fff0 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69  graph..**.*/.voi
20000 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65  d sqlite3_progre
20010 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74  ss_handler(sqlit
20020 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29  e3*, int, int(*)
20030 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b  (void*), void*);
20040 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
20050 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20  : Opening A New 
20060 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
20070 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ion.**.** ^These
20080 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61   routines open a
20090 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73  n SQLite databas
200a0 65 20 66 69 6c 65 20 61 73 20 73 70 65 63 69 66  e file as specif
200b0 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66  ied by the .** f
200c0 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
200d0 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20  . ^The filename 
200e0 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65  argument is inte
200f0 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38  rpreted as UTF-8
20100 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
20110 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
20120 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64  e3_open_v2() and
20130 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68   as UTF-16 in th
20140 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a  e native byte.**
20150 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74   order for sqlit
20160 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41  e3_open16(). ^(A
20170 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
20180 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73  ction] handle is
20190 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75   usually.** retu
201a0 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65  rned in *ppDb, e
201b0 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20  ven if an error 
201c0 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c  occurs.  The onl
201d0 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74  y exception is t
201e0 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65  hat.** if SQLite
201f0 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
20200 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f  locate memory to
20210 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74   hold the [sqlit
20220 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61  e3] object,.** a
20230 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72   NULL will be wr
20240 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62  itten into *ppDb
20250 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f   instead of a po
20260 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  inter to the [sq
20270 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74  lite3].** object
20280 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74  .)^ ^(If the dat
20290 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
202a0 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29  (and/or created)
202b0 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74   successfully, t
202c0 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  hen.** [SQLITE_O
202d0 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  K] is returned. 
202e0 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65   Otherwise an [e
202f0 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
20300 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a  turned.)^ ^The.*
20310 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  * [sqlite3_errms
20320 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  g()] or [sqlite3
20330 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75  _errmsg16()] rou
20340 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65  tines can be use
20350 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61  d to obtain.** a
20360 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61  n English langua
20370 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f  ge description o
20380 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c  f the error foll
20390 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20  owing a failure 
203a0 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65  of any.** of the
203b0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
203c0 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
203d0 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63  ^The default enc
203e0 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64 61  oding for the da
203f0 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 55  tabase will be U
20400 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74  TF-8 if.** sqlit
20410 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
20420 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
20430 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20  s called and.** 
20440 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61  UTF-16 in the na
20450 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
20460 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  if sqlite3_open1
20470 36 28 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  6() is used..**.
20480 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f  ** Whether or no
20490 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  t an error occur
204a0 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65  s when it is ope
204b0 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a  ned, resources.*
204c0 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
204d0 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
204e0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
204f0 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c  le should be rel
20500 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73  eased by.** pass
20510 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74  ing it to [sqlit
20520 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e  e3_close()] when
20530 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72   it is no longer
20540 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
20550 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65   The sqlite3_ope
20560 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  n_v2() interface
20570 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69   works like sqli
20580 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78  te3_open().** ex
20590 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63  cept that it acc
205a0 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f  epts two additio
205b0 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66  nal parameters f
205c0 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f  or additional co
205d0 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68  ntrol.** over th
205e0 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  e new database c
205f0 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68  onnection.  ^(Th
20600 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  e flags paramete
20610 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  r to.** sqlite3_
20620 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61  open_v2() can ta
20630 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65  ke one of.** the
20640 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65   following three
20650 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61   values, optiona
20660 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74  lly combined wit
20670 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54  h the .** [SQLIT
20680 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c  E_OPEN_NOMUTEX],
20690 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55   [SQLITE_OPEN_FU
206a0 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54  LLMUTEX], [SQLIT
206b0 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
206c0 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  HE],.** [SQLITE_
206d0 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
206e0 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49  E], and/or [SQLI
206f0 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61  TE_OPEN_URI] fla
20700 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  gs:)^.**.** <dl>
20710 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54  .** ^(<dt>[SQLIT
20720 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
20730 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
20740 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
20750 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79  ned in read-only
20760 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64   mode.  If the d
20770 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74  atabase does not
20780 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73  .** already exis
20790 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72  t, an error is r
207a0 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a  eturned.</dd>)^.
207b0 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  **.** ^(<dt>[SQL
207c0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
207d0 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TE]</dt>.** <dd>
207e0 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
207f0 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69  opened for readi
20800 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69  ng and writing i
20810 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72  f possible, or r
20820 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69  eading.** only i
20830 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72  f the file is wr
20840 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79  ite protected by
20850 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
20860 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65  ystem.  In eithe
20870 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61  r.** case the da
20880 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65  tabase must alre
20890 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72  ady exist, other
208a0 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73  wise an error is
208b0 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29   returned.</dd>)
208c0 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  ^.**.** ^(<dt>[S
208d0 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
208e0 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f  RITE] | [SQLITE_
208f0 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74  OPEN_CREATE]</dt
20900 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
20910 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
20920 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
20930 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20  writing, and is 
20940 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74  created if.** it
20950 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64   does not alread
20960 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73  y exist. This is
20970 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68   the behavior th
20980 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65  at is always use
20990 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  d for.** sqlite3
209a0 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
209b0 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64  te3_open16().</d
209c0 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a  d>)^.** </dl>.**
209d0 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70  .** If the 3rd p
209e0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
209f0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
20a00 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a   not one of the.
20a10 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20  ** combinations 
20a20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69  shown above opti
20a30 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20  onally combined 
20a40 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53  with other.** [S
20a50 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
20a60 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45  NLY | SQLITE_OPE
20a70 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65  N_* bits].** the
20a80 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
20a90 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
20aa0 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49  ** ^If the [SQLI
20ab0 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d  TE_OPEN_NOMUTEX]
20ac0 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68   flag is set, th
20ad0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
20ae0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70  connection.** op
20af0 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69  ens in the multi
20b00 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69  -thread [threadi
20b10 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67  ng mode] as long
20b20 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74   as the single-t
20b30 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61  hread.** mode ha
20b40 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61  s not been set a
20b50 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  t compile-time o
20b60 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e  r start-time.  ^
20b70 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  If the.** [SQLIT
20b80 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
20b90 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 68  ] flag is set th
20ba0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
20bb0 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73  connection opens
20bc0 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61  .** in the seria
20bd0 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
20be0 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69   mode] unless si
20bf0 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a  ngle-thread was.
20c00 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65  ** previously se
20c10 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c  lected at compil
20c20 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d  e-time or start-
20c30 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53  time..** ^The [S
20c40 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
20c50 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75  DCACHE] flag cau
20c60 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ses the database
20c70 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62   connection to b
20c80 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f  e.** eligible to
20c90 20 75 73 65 20 5b 73 68 61 72 65 64 20 63 61 63   use [shared cac
20ca0 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64  he mode], regard
20cb0 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
20cc0 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a  or not shared.**
20cd0 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65   cache is enable
20ce0 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
20cf0 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63  _enable_shared_c
20d00 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a  ache()].  ^The.*
20d10 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  * [SQLITE_OPEN_P
20d20 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61  RIVATECACHE] fla
20d30 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74  g causes the dat
20d40 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
20d50 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69   to not.** parti
20d60 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65  cipate in [share
20d70 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76  d cache mode] ev
20d80 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61 62  en if it is enab
20d90 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  led..**.** ^The 
20da0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
20db0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
20dc0 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d  _v2() is the nam
20dd0 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  e of the.** [sql
20de0 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
20df0 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68   that defines th
20e00 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
20e10 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  em interface tha
20e20 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74  t.** the new dat
20e30 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
20e40 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49   should use.  ^I
20e50 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
20e60 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e  ameter is.** a N
20e70 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
20e80 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
20e90 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
20ea0 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  t is used..**.**
20eb0 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d   ^If the filenam
20ec0 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c  e is ":memory:",
20ed0 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c   then a private,
20ee0 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65   temporary in-me
20ef0 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a  mory database.**
20f00 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20   is created for 
20f10 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  the connection. 
20f20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79   ^This in-memory
20f30 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76   database will v
20f40 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68  anish when.** th
20f50 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
20f60 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e  ction is closed.
20f70 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
20f80 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68  s of SQLite migh
20f90 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66  t.** make use of
20fa0 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63   additional spec
20fb0 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68  ial filenames th
20fc0 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68  at begin with th
20fd0 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e  e ":" character.
20fe0 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d  .** It is recomm
20ff0 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e 20  ended that when 
21000 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e  a database filen
21010 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65  ame actually doe
21020 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20  s begin with.** 
21030 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 20  a ":" character 
21040 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69  you should prefi
21050 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77  x the filename w
21060 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73  ith a pathname s
21070 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74  uch as.** "./" t
21080 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74  o avoid ambiguit
21090 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  y..**.** ^If the
210a0 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20   filename is an 
210b0 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68  empty string, th
210c0 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65  en a private, te
210d0 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69  mporary.** on-di
210e0 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  sk database will
210f0 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54   be created.  ^T
21100 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61  his private data
21110 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20  base will be.** 
21120 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65  automatically de
21130 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73  leted as soon as
21140 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
21150 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
21160 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20  ed..**.** [[URI 
21170 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c  filenames in sql
21180 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68  ite3_open()]] <h
21190 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c  3>URI Filenames<
211a0 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b  /h3>.**.** ^If [
211b0 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e  URI filename] in
211c0 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20  terpretation is 
211d0 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65  enabled, and the
211e0 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
211f0 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74  nt.** begins wit
21200 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20  h "file:", then 
21210 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
21220 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
21230 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69   URI. ^URI.** fi
21240 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74  lename interpret
21250 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ation is enabled
21260 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   if the [SQLITE_
21270 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69  OPEN_URI] flag i
21280 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20  s.** set in the 
21290 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20  fourth argument 
212a0 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
212b0 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68  v2(), or if it h
212c0 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c  as.** been enabl
212d0 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e  ed globally usin
212e0 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f  g the [SQLITE_CO
212f0 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e  NFIG_URI] option
21300 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71   with the.** [sq
21310 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
21320 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65  method or by the
21330 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49   [SQLITE_USE_URI
21340 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
21350 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20  ption..** As of 
21360 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
21370 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e 61  .7.7, URI filena
21380 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  me interpretatio
21390 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66 0a  n is turned off.
213a0 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20 62  ** by default, b
213b0 75 74 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  ut future releas
213c0 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  es of SQLite mig
213d0 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66 69  ht enable URI fi
213e0 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70  lename.** interp
213f0 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66 61  retation by defa
21400 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49 20  ult.  See "[URI 
21410 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20  filenames]" for 
21420 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e  additional.** in
21430 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
21440 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 61   URI filenames a
21450 72 65 20 70 61 72 73 65 64 20 61 63 63 6f 72 64  re parsed accord
21460 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36 2e  ing to RFC 3986.
21470 20 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f 6e   ^If the URI con
21480 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68  tains an.** auth
21490 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20 6d  ority, then it m
214a0 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 6e  ust be either an
214b0 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72   empty string or
214c0 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20   the string .** 
214d0 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66  "localhost". ^If
214e0 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 69   the authority i
214f0 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20 73  s not an empty s
21500 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68  tring or "localh
21510 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72  ost", an .** err
21520 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 74  or is returned t
21530 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54  o the caller. ^T
21540 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70  he fragment comp
21550 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c 20  onent of a URI, 
21560 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20  if .** present, 
21570 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a  is ignored..**.*
21580 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74  * ^SQLite uses t
21590 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e  he path componen
215a0 74 20 6f 66 20 74 68 65 20 55 52 49 20 61 73 20  t of the URI as 
215b0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
215c0 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69  disk file.** whi
215d0 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20  ch contains the 
215e0 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74 68  database. ^If th
215f0 65 20 70 61 74 68 20 62 65 67 69 6e 73 20 77 69  e path begins wi
21600 74 68 20 61 20 27 2f 27 20 63 68 61 72 61 63 74  th a '/' charact
21610 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20  er, .** then it 
21620 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
21630 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61  s an absolute pa
21640 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68  th. ^If the path
21650 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e 20   does not begin 
21660 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20 28  .** with a '/' (
21670 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68 65  meaning that the
21680 20 61 75 74 68 6f 72 69 74 79 20 73 65 63 74 69   authority secti
21690 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  on is omitted fr
216a0 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20 74  om the URI).** t
216b0 68 65 6e 20 74 68 65 20 70 61 74 68 20 69 73 20  hen the path is 
216c0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
216d0 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e 20   relative path. 
216e0 0a 2a 2a 20 5e 4f 6e 20 77 69 6e 64 6f 77 73 2c  .** ^On windows,
216f0 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70 6f   the first compo
21700 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c  nent of an absol
21710 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 20  ute path .** is 
21720 61 20 64 72 69 76 65 20 73 70 65 63 69 66 69 63  a drive specific
21730 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22  ation (e.g. "C:"
21740 29 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20  )..**.** [[core 
21750 55 52 49 20 71 75 65 72 79 20 70 61 72 61 6d 65  URI query parame
21760 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75  ters]].** The qu
21770 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ery component of
21780 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 61   a URI may conta
21790 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 68  in parameters th
217a0 61 74 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  at are interpret
217b0 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 20  ed.** either by 
217c0 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 6f  SQLite itself, o
217d0 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20 63 75  r by a [VFS | cu
217e0 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65  stom VFS impleme
217f0 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c  ntation]..** SQL
21800 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20 74  ite interprets t
21810 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72  he following thr
21820 65 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  ee query paramet
21830 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ers:.**.** <ul>.
21840 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73  **   <li> <b>vfs
21850 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66 73 22  </b>: ^The "vfs"
21860 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
21870 65 20 75 73 65 64 20 74 6f 20 73 70 65 63 69 66  e used to specif
21880 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a  y the name of.**
21890 20 20 20 20 20 61 20 56 46 53 20 6f 62 6a 65 63       a VFS objec
218a0 74 20 74 68 61 74 20 70 72 6f 76 69 64 65 73 20  t that provides 
218b0 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
218c0 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74  stem interface t
218d0 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20  hat should.**   
218e0 20 20 62 65 20 75 73 65 64 20 74 6f 20 61 63 63    be used to acc
218f0 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ess the database
21900 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e   file on disk. ^
21910 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69  If this option i
21920 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20  s set to.**     
21930 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20  an empty string 
21940 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20  the default VFS 
21950 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 20  object is used. 
21960 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75  ^Specifying an u
21970 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46  nknown.**     VF
21980 53 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e  S is an error. ^
21990 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  If sqlite3_open_
219a0 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64  v2() is used and
219b0 20 74 68 65 20 76 66 73 20 6f 70 74 69 6f 6e 20   the vfs option 
219c0 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 73 65 6e  is.**     presen
219d0 74 2c 20 74 68 65 6e 20 74 68 65 20 56 46 53 20  t, then the VFS 
219e0 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
219f0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 70 72   option takes pr
21a00 65 63 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a  ecedence over.**
21a10 20 20 20 20 20 74 68 65 20 76 61 6c 75 65 20 70       the value p
21a20 61 73 73 65 64 20 61 73 20 74 68 65 20 66 6f 75  assed as the fou
21a30 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
21a40 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
21a50 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e  ()..**.**   <li>
21a60 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28   <b>mode</b>: ^(
21a70 54 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74  The mode paramet
21a80 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f  er may be set to
21a90 20 65 69 74 68 65 72 20 22 72 6f 22 2c 20 22 72   either "ro", "r
21aa0 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63 22  w",.**     "rwc"
21ab0 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20 41  , or "memory". A
21ac0 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65 74  ttempting to set
21ad0 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 65 72   it to any other
21ae0 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20 20   value is.**    
21af0 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a   an error)^. .**
21b00 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20 69 73       ^If "ro" is
21b10 20 73 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e   specified, then
21b20 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
21b30 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
21b40 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63  -only .**     ac
21b50 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20 69 66  cess, just as if
21b60 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
21b70 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67  N_READONLY] flag
21b80 20 68 61 64 20 62 65 65 6e 20 73 65 74 20 69 6e   had been set in
21b90 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74 68 69   the .**     thi
21ba0 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  rd argument to s
21bb0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
21bc0 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f  . ^If the mode o
21bd0 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 20  ption is set to 
21be0 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74 68  .**     "rw", th
21bf0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
21c00 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
21c10 61 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e 6f  ad-write (but no
21c20 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20 20  t create) .**   
21c30 20 20 61 63 63 65 73 73 2c 20 61 73 20 69 66 20    access, as if 
21c40 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
21c50 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20 53  WRITE (but not S
21c60 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
21c70 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20 62  E) had .**     b
21c80 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65 20  een set. ^Value 
21c90 22 72 77 63 22 20 69 73 20 65 71 75 69 76 61 6c  "rwc" is equival
21ca0 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 62  ent to setting b
21cb0 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49  oth .**     SQLI
21cc0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
21cd0 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45  E and SQLITE_OPE
21ce0 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 66 20 74  N_CREATE.  ^If t
21cf0 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69  he mode option i
21d00 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 74 6f 20  s.**     set to 
21d10 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20 61 20  "memory" then a 
21d20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20  pure [in-memory 
21d30 64 61 74 61 62 61 73 65 5d 20 74 68 61 74 20 6e  database] that n
21d40 65 76 65 72 20 72 65 61 64 73 0a 2a 2a 20 20 20  ever reads.**   
21d50 20 20 6f 72 20 77 72 69 74 65 73 20 66 72 6f 6d    or writes from
21d60 20 64 69 73 6b 20 69 73 20 75 73 65 64 2e 20 5e   disk is used. ^
21d70 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 74  It is an error t
21d80 6f 20 73 70 65 63 69 66 79 20 61 20 76 61 6c 75  o specify a valu
21d90 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68 65  e for.**     the
21da0 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20   mode parameter 
21db0 74 68 61 74 20 69 73 20 6c 65 73 73 20 72 65 73  that is less res
21dc0 74 72 69 63 74 69 76 65 20 74 68 61 6e 20 74 68  trictive than th
21dd0 61 74 20 73 70 65 63 69 66 69 65 64 20 62 79 0a  at specified by.
21de0 2a 2a 20 20 20 20 20 74 68 65 20 66 6c 61 67 73  **     the flags
21df0 20 70 61 73 73 65 64 20 69 6e 20 74 68 65 20 74   passed in the t
21e00 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
21e10 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
21e20 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69  2()..**.**   <li
21e30 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20  > <b>cache</b>: 
21e40 5e 54 68 65 20 63 61 63 68 65 20 70 61 72 61 6d  ^The cache param
21e50 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20  eter may be set 
21e60 74 6f 20 65 69 74 68 65 72 20 22 73 68 61 72 65  to either "share
21e70 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72  d" or.**     "pr
21e80 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69 6e 67  ivate". ^Setting
21e90 20 69 74 20 74 6f 20 22 73 68 61 72 65 64 22 20   it to "shared" 
21ea0 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f  is equivalent to
21eb0 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20   setting the.** 
21ec0 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f      SQLITE_OPEN_
21ed0 53 48 41 52 45 44 43 41 43 48 45 20 62 69 74 20  SHAREDCACHE bit 
21ee0 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61 72 67  in the flags arg
21ef0 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f 0a  ument passed to.
21f00 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33 5f 6f  **     sqlite3_o
21f10 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74 69  pen_v2(). ^Setti
21f20 6e 67 20 74 68 65 20 63 61 63 68 65 20 70 61 72  ng the cache par
21f30 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69 76 61  ameter to "priva
21f40 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 20 65  te" is .**     e
21f50 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74  quivalent to set
21f60 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f  ting the SQLITE_
21f70 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
21f80 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49  E bit..**     ^I
21f90 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  f sqlite3_open_v
21fa0 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20  2() is used and 
21fb0 74 68 65 20 22 63 61 63 68 65 22 20 70 61 72 61  the "cache" para
21fc0 6d 65 74 65 72 20 69 73 20 70 72 65 73 65 6e 74  meter is present
21fd0 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52 49   in.**     a URI
21fe0 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76   filename, its v
21ff0 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73 20 61  alue overrides a
22000 6e 79 20 62 65 68 61 76 69 6f 72 20 72 65 71 75  ny behavior requ
22010 65 73 74 65 64 20 62 79 20 73 65 74 74 69 6e 67  ested by setting
22020 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f  .**     SQLITE_O
22030 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
22040 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   or SQLITE_OPEN_
22050 53 48 41 52 45 44 43 41 43 48 45 20 66 6c 61 67  SHAREDCACHE flag
22060 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62  ..**.**  <li> <b
22070 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54 68 65 20  >psow</b>: ^The 
22080 70 73 6f 77 20 70 61 72 61 6d 65 74 65 72 20 6d  psow parameter m
22090 61 79 20 62 65 20 22 74 72 75 65 22 20 28 6f 72  ay be "true" (or
220a0 20 22 6f 6e 22 20 6f 72 20 22 79 65 73 22 20 6f   "on" or "yes" o
220b0 72 0a 2a 2a 20 20 20 20 20 22 31 22 29 20 6f 72  r.**     "1") or
220c0 20 22 66 61 6c 73 65 22 20 28 6f 72 20 22 6f 66   "false" (or "of
220d0 66 22 20 6f 72 20 22 6e 6f 22 20 6f 72 20 22 30  f" or "no" or "0
220e0 22 29 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  ") to indicate t
220f0 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b  hat the.**     [
22100 70 6f 77 65 72 73 61 66 65 20 6f 76 65 72 77 72  powersafe overwr
22110 69 74 65 5d 20 70 72 6f 70 65 72 74 79 20 64 6f  ite] property do
22120 65 73 20 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61  es or does not a
22130 70 70 6c 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20  pply to the.**  
22140 20 20 20 73 74 6f 72 61 67 65 20 6d 65 64 69 61     storage media
22150 20 6f 6e 20 77 68 69 63 68 20 74 68 65 20 64 61   on which the da
22160 74 61 62 61 73 65 20 66 69 6c 65 20 72 65 73 69  tabase file resi
22170 64 65 73 2e 20 20 5e 54 68 65 20 70 73 6f 77 20  des.  ^The psow 
22180 71 75 65 72 79 0a 2a 2a 20 20 20 20 20 70 61 72  query.**     par
22190 61 6d 65 74 65 72 20 6f 6e 6c 79 20 77 6f 72 6b  ameter only work
221a0 73 20 66 6f 72 20 74 68 65 20 62 75 69 6c 74 2d  s for the built-
221b0 69 6e 20 75 6e 69 78 20 61 6e 64 20 57 69 6e 64  in unix and Wind
221c0 6f 77 73 20 56 46 53 65 73 2e 0a 2a 2a 0a 2a 2a  ows VFSes..**.**
221d0 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b    <li> <b>nolock
221e0 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f 63  </b>: ^The noloc
221f0 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  k parameter is a
22200 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 20 70   boolean query p
22210 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20  arameter.**     
22220 77 68 69 63 68 20 69 66 20 73 65 74 20 64 69 73  which if set dis
22230 61 62 6c 65 73 20 66 69 6c 65 20 6c 6f 63 6b 69  ables file locki
22240 6e 67 20 69 6e 20 72 6f 6c 6c 62 61 63 6b 20 6a  ng in rollback j
22250 6f 75 72 6e 61 6c 20 6d 6f 64 65 73 2e 20 20 54  ournal modes.  T
22260 68 69 73 0a 2a 2a 20 20 20 20 20 69 73 20 75 73  his.**     is us
22270 65 66 75 6c 20 66 6f 72 20 61 63 63 65 73 73 69  eful for accessi
22280 6e 67 20 61 20 64 61 74 61 62 61 73 65 20 6f 6e  ng a database on
22290 20 61 20 66 69 6c 65 73 79 73 74 65 6d 20 74 68   a filesystem th
222a0 61 74 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20  at does not.**  
222b0 20 20 20 73 75 70 70 6f 72 74 20 6c 6f 63 6b 69     support locki
222c0 6e 67 2e 20 20 43 61 75 74 69 6f 6e 3a 20 20 44  ng.  Caution:  D
222d0 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69  atabase corrupti
222e0 6f 6e 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  on might result 
222f0 69 66 20 74 77 6f 0a 2a 2a 20 20 20 20 20 6f 72  if two.**     or
22300 20 6d 6f 72 65 20 70 72 6f 63 65 73 73 65 73 20   more processes 
22310 77 72 69 74 65 20 74 6f 20 74 68 65 20 73 61 6d  write to the sam
22320 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61  e database and a
22330 6e 79 20 6f 6e 65 20 6f 66 20 74 68 6f 73 65 0a  ny one of those.
22340 2a 2a 20 20 20 20 20 70 72 6f 63 65 73 73 65 73  **     processes
22350 20 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a   uses nolock=1..
22360 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 69  **.**  <li> <b>i
22370 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e 54  mmutable</b>: ^T
22380 68 65 20 69 6d 6d 75 74 61 62 6c 65 20 70 61 72  he immutable par
22390 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c  ameter is a bool
223a0 65 61 6e 20 71 75 65 72 79 0a 2a 2a 20 20 20 20  ean query.**    
223b0 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20   parameter that 
223c0 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74  indicates that t
223d0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
223e0 20 69 73 20 73 74 6f 72 65 64 20 6f 6e 0a 2a 2a   is stored on.**
223f0 20 20 20 20 20 72 65 61 64 2d 6f 6e 6c 79 20 6d       read-only m
22400 65 64 69 61 2e 20 20 5e 57 68 65 6e 20 69 6d 6d  edia.  ^When imm
22410 75 74 61 62 6c 65 20 69 73 20 73 65 74 2c 20 53  utable is set, S
22420 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68  QLite assumes th
22430 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 64 61  at the.**     da
22440 74 61 62 61 73 65 20 66 69 6c 65 20 63 61 6e 6e  tabase file cann
22450 6f 74 20 62 65 20 63 68 61 6e 67 65 64 2c 20 65  ot be changed, e
22460 76 65 6e 20 62 79 20 61 20 70 72 6f 63 65 73 73  ven by a process
22470 20 77 69 74 68 20 68 69 67 68 65 72 0a 2a 2a 20   with higher.** 
22480 20 20 20 20 70 72 69 76 69 6c 65 67 65 2c 20 61      privilege, a
22490 6e 64 20 73 6f 20 74 68 65 20 64 61 74 61 62 61  nd so the databa
224a0 73 65 20 69 73 20 6f 70 65 6e 65 64 20 72 65 61  se is opened rea
224b0 64 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c 20 6c  d-only and all l
224c0 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20 20 20 61 6e  ocking.**     an
224d0 64 20 63 68 61 6e 67 65 20 64 65 74 65 63 74 69  d change detecti
224e0 6f 6e 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20  on is disabled. 
224f0 20 43 61 75 74 69 6f 6e 3a 20 53 65 74 74 69 6e   Caution: Settin
22500 67 20 74 68 65 20 69 6d 6d 75 74 61 62 6c 65 0a  g the immutable.
22510 2a 2a 20 20 20 20 20 70 72 6f 70 65 72 74 79 20  **     property 
22520 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69  on a database fi
22530 6c 65 20 74 68 61 74 20 64 6f 65 73 20 69 6e 20  le that does in 
22540 66 61 63 74 20 63 68 61 6e 67 65 20 63 61 6e 20  fact change can 
22550 72 65 73 75 6c 74 0a 2a 2a 20 20 20 20 20 69 6e  result.**     in
22560 20 69 6e 63 6f 72 72 65 63 74 20 71 75 65 72 79   incorrect query
22570 20 72 65 73 75 6c 74 73 20 61 6e 64 2f 6f 72 20   results and/or 
22580 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d  [SQLITE_CORRUPT]
22590 20 65 72 72 6f 72 73 2e 0a 2a 2a 20 20 20 20 20   errors..**     
225a0 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54  See also: [SQLIT
225b0 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c  E_IOCAP_IMMUTABL
225c0 45 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 0a 2a 2a  E]..**       .**
225d0 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70   </ul>.**.** ^Sp
225e0 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e  ecifying an unkn
225f0 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69 6e  own parameter in
22600 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f   the query compo
22610 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69 73  nent of a URI is
22620 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72   not an.** error
22630 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
22640 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  ns of SQLite mig
22650 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61 64  ht understand ad
22660 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a  ditional query.*
22670 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 53  * parameters.  S
22680 65 65 20 22 5b 71 75 65 72 79 20 70 61 72 61 6d  ee "[query param
22690 65 74 65 72 73 20 77 69 74 68 20 73 70 65 63 69  eters with speci
226a0 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51  al meaning to SQ
226b0 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64  Lite]" for.** ad
226c0 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
226d0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52  tion..**.** [[UR
226e0 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70  I filename examp
226f0 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69  les]] <h3>URI fi
22700 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c  lename examples<
22710 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c  /h3>.**.** <tabl
22720 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c 69  e border="1" ali
22730 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70 61  gn=center cellpa
22740 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e  dding=5>.** <tr>
22750 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d  <th> URI filenam
22760 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a  es <th> Results.
22770 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
22780 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a  :data.db <td> .*
22790 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
227a0 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64  the file "data.d
227b0 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  b" in the curren
227c0 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20  t directory..** 
227d0 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68  <tr><td> file:/h
227e0 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
227f0 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20  <br>.**         
22800 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72   file:///home/fr
22810 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20  ed/data.db <br> 
22820 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c  .**          fil
22830 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f  e://localhost/ho
22840 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20  me/fred/data.db 
22850 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  <br> <td> .**   
22860 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20         Open the 
22870 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 22 2f  database file "/
22880 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
22890 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  b"..** <tr><td> 
228a0 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f  file://darkstar/
228b0 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
228c0 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  b <td> .**      
228d0 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 64      An error. "d
228e0 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74 20  arkstar" is not 
228f0 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75 74  a recognized aut
22900 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c  hority..** <tr><
22910 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65 2d  td style="white-
22920 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a  space:nowrap"> .
22930 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65  **          file
22940 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73  :///C:/Documents
22950 25 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e 67  %20and%20Setting
22960 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64  s/fred/Desktop/d
22970 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74  ata.db.**     <t
22980 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a  d> Windows only:
22990 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22   Open the file "
229a0 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65 64  data.db" on fred
229b0 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72  's desktop on dr
229c0 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ive.**          
229d0 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68  C:. Note that th
229e0 65 20 25 32 30 20 65 73 63 61 70 69 6e 67 20 69  e %20 escaping i
229f0 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20 69  n this example i
22a00 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 0a  s not strictly .
22a10 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63 65  **          nece
22a20 73 73 61 72 79 20 2d 20 73 70 61 63 65 20 63 68  ssary - space ch
22a30 61 72 61 63 74 65 72 73 20 63 61 6e 20 62 65 20  aracters can be 
22a40 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a  used literally.*
22a50 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 55 52  *          in UR
22a60 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20  I filenames..** 
22a70 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61  <tr><td> file:da
22a80 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61  ta.db?mode=ro&ca
22a90 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64 3e  che=private <td>
22aa0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70   .**          Op
22ab0 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62  en file "data.db
22ac0 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  " in the current
22ad0 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20 72   directory for r
22ae0 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e  ead-only access.
22af0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65 67  .**          Reg
22b00 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
22b10 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64  er or not shared
22b20 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20 65  -cache mode is e
22b30 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20  nabled by.**    
22b40 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20 75        default, u
22b50 73 65 20 61 20 70 72 69 76 61 74 65 20 63 61 63  se a private cac
22b60 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  he..** <tr><td> 
22b70 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f  file:/home/fred/
22b80 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78  data.db?vfs=unix
22b90 2d 64 6f 74 66 69 6c 65 20 3c 74 64 3e 0a 2a 2a  -dotfile <td>.**
22ba0 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66            Open f
22bb0 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f  ile "/home/fred/
22bc0 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74 68  data.db". Use th
22bd0 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 22 75  e special VFS "u
22be0 6e 69 78 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a 20  nix-dotfile".** 
22bf0 20 20 20 20 20 20 20 20 20 74 68 61 74 20 75 73           that us
22c00 65 73 20 64 6f 74 2d 66 69 6c 65 73 20 69 6e 20  es dot-files in 
22c10 70 6c 61 63 65 20 6f 66 20 70 6f 73 69 78 20 61  place of posix a
22c20 64 76 69 73 6f 72 79 20 6c 6f 63 6b 69 6e 67 2e  dvisory locking.
22c30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
22c40 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72  e:data.db?mode=r
22c50 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a  eadonly <td> .**
22c60 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72            An err
22c70 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20 69  or. "readonly" i
22c80 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f 70  s not a valid op
22c90 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f  tion for the "mo
22ca0 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  de" parameter..*
22cb0 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a  * </table>.**.**
22cc0 20 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d 61   ^URI hexadecima
22cd0 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63  l escape sequenc
22ce0 65 73 20 28 25 48 48 29 20 61 72 65 20 73 75 70  es (%HH) are sup
22cf0 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74 68  ported within th
22d00 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75  e path and.** qu
22d10 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f  ery components o
22d20 66 20 61 20 55 52 49 2e 20 41 20 68 65 78 61 64  f a URI. A hexad
22d30 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
22d40 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73 20  quence consists 
22d50 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20  of a.** percent 
22d60 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c  sign - "%" - fol
22d70 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c 79  lowed by exactly
22d80 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61 6c   two hexadecimal
22d90 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65 63   digits .** spec
22da0 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74 20  ifying an octet 
22db0 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20 74  value. ^Before t
22dc0 68 65 20 70 61 74 68 20 6f 72 20 71 75 65 72 79  he path or query
22dd0 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61   components of a
22de0 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  .** URI filename
22df0 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
22e00 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f 64  , they are encod
22e10 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20 61  ed using UTF-8 a
22e20 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64  nd all .** hexad
22e30 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
22e40 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65 64  quences replaced
22e50 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79 74   by a single byt
22e60 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  e containing the
22e70 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  .** correspondin
22e80 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69 73  g octet. If this
22e90 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61 74   process generat
22ea0 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55 54  es an invalid UT
22eb0 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a  F-8 encoding,.**
22ec0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
22ed0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
22ee0 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e  * <b>Note to Win
22ef0 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20  dows users:</b> 
22f00 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73   The encoding us
22f10 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e  ed for the filen
22f20 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ame argument.** 
22f30 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  of sqlite3_open(
22f40 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
22f50 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20  en_v2() must be 
22f60 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65  UTF-8, not whate
22f70 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20  ver.** codepage 
22f80 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  is currently def
22f90 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73  ined.  Filenames
22fa0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65   containing inte
22fb0 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61  rnational.** cha
22fc0 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20  racters must be 
22fd0 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46  converted to UTF
22fe0 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73  -8 prior to pass
22ff0 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a  ing them into.**
23000 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
23010 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
23020 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e  v2()..**.** <b>N
23030 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52  ote to Windows R
23040 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62  untime users:</b
23050 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79  >  The temporary
23060 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20   directory must 
23070 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20  be set.** prior 
23080 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74  to calling sqlit
23090 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
230a0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20  ite3_open_v2(). 
230b0 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72 69   Otherwise, vari
230c0 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20  ous.** features 
230d0 74 68 61 74 20 72 65 71 75 69 72 65 20 74 68 65  that require the
230e0 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72   use of temporar
230f0 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c  y files may fail
23100 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
23110 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f  : [sqlite3_temp_
23120 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 69 6e  directory].*/.in
23130 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a  t sqlite3_open(.
23140 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69    const char *fi
23150 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
23160 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
23170 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69  UTF-8) */.  sqli
23180 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20  te3 **ppDb      
23190 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
231a0 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
231b0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
231c0 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76  pen16(.  const v
231d0 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  oid *filename,  
231e0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
231f0 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a  ename (UTF-16) *
23200 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
23210 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db          /* O
23220 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
23230 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  ndle */.);.int s
23240 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a  qlite3_open_v2(.
23250 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69    const char *fi
23260 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
23270 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
23280 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69  UTF-8) */.  sqli
23290 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20  te3 **ppDb,     
232a0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
232b0 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
232c0 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20    int flags,    
232d0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61            /* Fla
232e0 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  gs */.  const ch
232f0 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20  ar *zVfs        
23300 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d  /* Name of VFS m
23310 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a  odule to use */.
23320 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
23330 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75 65  EF: Obtain Value
23340 73 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d 65  s For URI Parame
23350 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ters.**.** These
23360 20 61 72 65 20 75 74 69 6c 69 74 79 20 72 6f 75   are utility rou
23370 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20 74 6f  tines, useful to
23380 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
23390 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63 6b  ions, that check
233a0 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61 20  .** to see if a 
233b0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61  database file wa
233c0 73 20 61 20 55 52 49 20 74 68 61 74 20 63 6f 6e  s a URI that con
233d0 74 61 69 6e 65 64 20 61 20 73 70 65 63 69 66 69  tained a specifi
233e0 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72 61  c query .** para
233f0 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73 6f  meter, and if so
23400 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61 6c   obtains the val
23410 75 65 20 6f 66 20 74 68 61 74 20 71 75 65 72 79  ue of that query
23420 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
23430 2a 20 49 66 20 46 20 69 73 20 74 68 65 20 64 61  * If F is the da
23440 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
23450 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 69  pointer passed i
23460 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 20  nto the xOpen() 
23470 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20  method of .** a 
23480 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
23490 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c 61 67  on when the flag
234a0 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78  s parameter to x
234b0 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f  Open() has one o
234c0 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68  r .** more of th
234d0 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  e [SQLITE_OPEN_U
234e0 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f  RI] or [SQLITE_O
234f0 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74  PEN_MAIN_DB] bit
23500 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69  s set and.** P i
23510 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
23520 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  e query paramete
23530 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  r, then.** sqlit
23540 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72  e3_uri_parameter
23550 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 74 68  (F,P) returns th
23560 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 50  e value of the P
23570 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66  .** parameter if
23580 20 69 74 20 65 78 69 73 74 73 20 6f 72 20 61 20   it exists or a 
23590 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20  NULL pointer if 
235a0 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61  P does not appea
235b0 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65 72 79  r as a .** query
235c0 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e   parameter on F.
235d0 20 20 49 66 20 50 20 69 73 20 61 20 71 75 65 72    If P is a quer
235e0 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 46  y parameter of F
235f0 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c 69  .** has no expli
23600 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20  cit value, then 
23610 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
23620 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72  meter(F,P) retur
23630 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  ns.** a pointer 
23640 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  to an empty stri
23650 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ng..**.** The sq
23660 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
23670 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65  n(F,P,B) routine
23680 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 50 20   assumes that P 
23690 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20  is a boolean.** 
236a0 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65  parameter and re
236b0 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 6f  turns true (1) o
236c0 72 20 66 61 6c 73 65 20 28 30 29 20 61 63 63 6f  r false (0) acco
236d0 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76 61 6c  rding to the val
236e0 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65  ue.** of P.  The
236f0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
23700 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74  lean(F,P,B) rout
23710 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72 75 65  ine returns true
23720 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a 20 76   (1) if the.** v
23730 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20 70 61  alue of query pa
23740 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65  rameter P is one
23750 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72 75 65   of "yes", "true
23760 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e  ", or "on" in an
23770 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69 66 20  y.** case or if 
23780 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73  the value begins
23790 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f   with a non-zero
237a0 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a   number.  The .*
237b0 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  * sqlite3_uri_bo
237c0 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75  olean(F,P,B) rou
237d0 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20 66 61  tines returns fa
237e0 6c 73 65 20 28 30 29 20 69 66 20 74 68 65 20 76  lse (0) if the v
237f0 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79  alue of.** query
23800 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20   parameter P is 
23810 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61  one of "no", "fa
23820 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22 20 69  lse", or "off" i
23830 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a  n any case or.**
23840 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65   if the value be
23850 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75 6d 65  gins with a nume
23860 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20 50 20  ric zero.  If P 
23870 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a  is not a query.*
23880 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46  * parameter on F
23890 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65   or if the value
238a0 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20 6e 6f   of P is does no
238b0 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66 20 74  t match any of t
238c0 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65  he.** above, the
238d0 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  n sqlite3_uri_bo
238e0 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74  olean(F,P,B) ret
238f0 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a  urns (B!=0)..**.
23900 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  ** The sqlite3_u
23910 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29 20  ri_int64(F,P,D) 
23920 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72 74 73  routine converts
23930 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20   the value of P 
23940 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74  into a.** 64-bit
23950 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20   signed integer 
23960 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68 61 74  and returns that
23970 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44 20 69   integer, or D i
23980 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  f P does not.** 
23990 65 78 69 73 74 2e 20 20 49 66 20 74 68 65 20 76  exist.  If the v
239a0 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73 6f 6d  alue of P is som
239b0 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61  ething other tha
239c0 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68  n an integer, th
239d0 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65  en.** zero is re
239e0 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49  turned..** .** I
239f0 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  f F is a NULL po
23a00 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71 6c 69  inter, then sqli
23a10 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
23a20 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 4e  r(F,P) returns N
23a30 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74  ULL and.** sqlit
23a40 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
23a50 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 42 2e  ,P,B) returns B.
23a60 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20 61 20    If F is not a 
23a70 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64  NULL pointer and
23a80 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64 61 74  .** is not a dat
23a90 61 62 61 73 65 20 66 69 6c 65 20 70 61 74 68 6e  abase file pathn
23aa0 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ame pointer that
23ab0 20 53 51 4c 69 74 65 20 70 61 73 73 65 64 20 69   SQLite passed i
23ac0 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a  nto the xOpen.**
23ad0 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68 65   VFS method, the
23ae0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  n the behavior o
23af0 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  f this routine i
23b00 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20  s undefined and 
23b10 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65  probably.** unde
23b20 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73  sirable..*/.cons
23b30 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
23b40 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f  uri_parameter(co
23b50 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e  nst char *zFilen
23b60 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  ame, const char 
23b70 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e 74 20 73 71  *zParam);.int sq
23b80 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
23b90 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  n(const char *zF
23ba0 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  ile, const char 
23bb0 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65  *zParam, int bDe
23bc0 66 61 75 6c 74 29 3b 0a 73 71 6c 69 74 65 33 5f  fault);.sqlite3_
23bd0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 72  int64 sqlite3_ur
23be0 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20 63 68  i_int64(const ch
23bf0 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  ar*, const char*
23c00 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
23c10 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ;.../*.** CAPI3R
23c20 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20  EF: Error Codes 
23c30 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a  And Messages.**.
23c40 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
23c50 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66  errcode() interf
23c60 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
23c70 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20  numeric [result 
23c80 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  code] or.** [ext
23c90 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
23ca0 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20  e] for the most 
23cb0 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71  recent failed sq
23cc0 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c  lite3_* API call
23cd0 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
23ce0 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20  ith a [database 
23cf0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20  connection]. If 
23d00 61 20 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c  a prior API call
23d10 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74   failed.** but t
23d20 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41  he most recent A
23d30 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65  PI call succeede
23d40 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  d, the return va
23d50 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69  lue from.** sqli
23d60 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73  te3_errcode() is
23d70 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 5e 54 68   undefined.  ^Th
23d80 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  e sqlite3_extend
23d90 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20  ed_errcode().** 
23da0 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 65  interface is the
23db0 20 73 61 6d 65 20 65 78 63 65 70 74 20 74 68 61   same except tha
23dc0 74 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75  t it always retu
23dd0 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74  rns the .** [ext
23de0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
23df0 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74  e] even when ext
23e00 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
23e10 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c  es are.** disabl
23e20 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
23e30 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20  qlite3_errmsg() 
23e40 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  and sqlite3_errm
23e50 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e  sg16() return En
23e60 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a  glish-language.*
23e70 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63  * text that desc
23e80 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c  ribes the error,
23e90 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38   as either UTF-8
23ea0 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65   or UTF-16 respe
23eb0 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65  ctively..** ^(Me
23ec0 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
23ed0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
23ee0 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64  tring is managed
23ef0 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20   internally..** 
23f00 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
23f10 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
23f20 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65   worry about fre
23f30 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e  eing the result.
23f40 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65  .** However, the
23f50 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69   error string mi
23f60 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74  ght be overwritt
23f70 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65  en or deallocate
23f80 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65  d by.** subseque
23f90 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65  nt calls to othe
23fa0 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
23fb0 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a  ce functions.)^.
23fc0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
23fd0 65 33 5f 65 72 72 73 74 72 28 29 20 69 6e 74 65  e3_errstr() inte
23fe0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
23ff0 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61  e English-langua
24000 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 61 74 20  ge text.** that 
24010 64 65 73 63 72 69 62 65 73 20 74 68 65 20 5b 72  describes the [r
24020 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73 20  esult code], as 
24030 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f  UTF-8..** ^(Memo
24040 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65  ry to hold the e
24050 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
24060 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69  ing is managed i
24070 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64  nternally.** and
24080 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 66 72 65   must not be fre
24090 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ed by the applic
240a0 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57  ation)^..**.** W
240b0 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a  hen the serializ
240c0 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
240d0 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69  de] is in use, i
240e0 74 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a  t might be the.*
240f0 2a 20 63 61 73 65 20 74 68 61 74 20 61 20 73 65  * case that a se
24100 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72  cond error occur
24110 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20  s on a separate 
24120 74 68 72 65 61 64 20 69 6e 20 62 65 74 77 65 65  thread in betwee
24130 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66  n.** the time of
24140 20 74 68 65 20 66 69 72 73 74 20 65 72 72 6f 72   the first error
24150 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f   and the call to
24160 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
24170 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20  s..** When that 
24180 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63  happens, the sec
24190 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62  ond error will b
241a0 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65  e reported since
241b0 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66   these.** interf
241c0 61 63 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f  aces always repo
241d0 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  rt the most rece
241e0 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61  nt result.  To a
241f0 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61  void.** this, ea
24200 63 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62  ch thread can ob
24210 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75  tain exclusive u
24220 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62  se of the [datab
24230 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
24240 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67  D.** by invoking
24250 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
24260 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f  enter]([sqlite3_
24270 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65  db_mutex](D)) be
24280 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a  fore beginning.*
24290 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69  * to use D and i
242a0 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33  nvoking [sqlite3
242b0 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73  _mutex_leave]([s
242c0 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d  qlite3_db_mutex]
242d0 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c  (D)) after.** al
242e0 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69  l calls to the i
242f0 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74 65 64  nterfaces listed
24300 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65   here are comple
24310 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  ted..**.** If an
24320 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73   interface fails
24330 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53   with SQLITE_MIS
24340 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  USE, that means 
24350 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  the interface.**
24360 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63   was invoked inc
24370 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68 65 20  orrectly by the 
24380 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e  application.  In
24390 20 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a   that case, the.
243a0 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e  ** error code an
243b0 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72  d message may or
243c0 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e   may not be set.
243d0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
243e0 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20  errcode(sqlite3 
243f0 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *db);.int sqlite
24400 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
24410 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b  de(sqlite3 *db);
24420 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
24430 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69  ite3_errmsg(sqli
24440 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  te3*);.const voi
24450 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  d *sqlite3_errms
24460 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63  g16(sqlite3*);.c
24470 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
24480 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29 3b 0a  e3_errstr(int);.
24490 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
244a0 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f   SQL Statement O
244b0 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44  bject.** KEYWORD
244c0 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 61  S: {prepared sta
244d0 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65  tement} {prepare
244e0 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a  d statements}.**
244f0 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
24500 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72  of this object r
24510 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67  epresents a sing
24520 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  le SQL statement
24530 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
24540 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e   is variously kn
24550 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70 61 72  own as a "prepar
24560 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72  ed statement" or
24570 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20   a.** "compiled 
24580 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f  SQL statement" o
24590 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73  r simply as a "s
245a0 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a  tatement"..**.**
245b0 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73   The life of a s
245c0 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20  tatement object 
245d0 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c  goes something l
245e0 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20  ike this:.**.** 
245f0 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65  <ol>.** <li> Cre
24600 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75  ate the object u
24610 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
24620 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61  epare_v2()] or a
24630 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20   related.**     
24640 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c   function..** <l
24650 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74  i> Bind values t
24660 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  o [host paramete
24670 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71  rs] using the sq
24680 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a  lite3_bind_*().*
24690 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65  *      interface
246a0 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74  s..** <li> Run t
246b0 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e  he SQL by callin
246c0 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
246d0 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74  )] one or more t
246e0 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65  imes..** <li> Re
246f0 73 65 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e  set the statemen
24700 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
24710 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67  _reset()] then g
24720 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74  o back.**      t
24730 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68  o step 2.  Do th
24740 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20  is zero or more 
24750 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44  times..** <li> D
24760 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63  estroy the objec
24770 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
24780 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a  _finalize()]..**
24790 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66   </ol>.**.** Ref
247a0 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74  er to documentat
247b0 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61  ion on individua
247c0 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  l methods above 
247d0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
247e0 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
247f0 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
24800 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71   sqlite3_stmt sq
24810 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a  lite3_stmt;../*.
24820 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
24830 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a  -time Limits.**.
24840 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66  ** ^(This interf
24850 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73  ace allows the s
24860 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63  ize of various c
24870 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
24880 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20  limited.** on a 
24890 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f  connection by co
248a0 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20  nnection basis. 
248b0 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
248c0 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b  eter is the.** [
248d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
248e0 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74  ion] whose limit
248f0 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72   is to be set or
24900 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a   queried.  The.*
24910 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
24920 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65  er is one of the
24930 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69   [limit categori
24940 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20  es] that define 
24950 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f  a.** class of co
24960 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73  nstructs to be s
24970 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68  ize limited.  Th
24980 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
24990 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20  r is the.** new 
249a0 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63  limit for that c
249b0 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a  onstruct.)^.**.*
249c0 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69  * ^If the new li
249d0 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76  mit is a negativ
249e0 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69  e number, the li
249f0 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64  mit is unchanged
24a00 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20  ..** ^(For each 
24a10 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53  limit category S
24a20 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e  QLITE_LIMIT_<i>N
24a30 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73  AME</i> there is
24a40 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c   a .** [limits |
24a50 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
24a60 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d  d].** set at com
24a70 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43  pile-time by a C
24a80 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
24a90 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c  cro called.** [l
24aa0 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d  imits | SQLITE_M
24ab0 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e  AX_<i>NAME</i>].
24ac0 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54  .** (The "_LIMIT
24ad0 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69  _" in the name i
24ae0 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d  s changed to "_M
24af0 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74  AX_".))^.** ^Att
24b00 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73  empts to increas
24b10 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20  e a limit above 
24b20 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62  its hard upper b
24b30 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65  ound are.** sile
24b40 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74  ntly truncated t
24b50 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72  o the hard upper
24b60 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52   bound..**.** ^R
24b70 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
24b80 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
24b90 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65  limit was change
24ba0 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69  d, the .** [sqli
24bb0 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74  te3_limit()] int
24bc0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
24bd0 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f  he prior value o
24be0 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20  f the limit..** 
24bf0 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20  ^Hence, to find 
24c00 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75  the current valu
24c10 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74  e of a limit wit
24c20 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74  hout changing it
24c30 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f  ,.** simply invo
24c40 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  ke this interfac
24c50 65 20 77 69 74 68 20 74 68 65 20 74 68 69 72 64  e with the third
24c60 20 70 61 72 61 6d 65 74 65 72 20 73 65 74 20 74   parameter set t
24c70 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d  o -1..**.** Run-
24c80 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20  time limits are 
24c90 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
24ca0 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   in applications
24cb0 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20   that manage.** 
24cc0 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69  both their own i
24cd0 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65  nternal database
24ce0 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61   and also databa
24cf0 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e  ses that are con
24d00 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e  trolled.** by un
24d10 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c  trusted external
24d20 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78   sources.  An ex
24d30 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f  ample applicatio
24d40 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20  n might be a.** 
24d50 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 74  web browser that
24d60 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74   has its own dat
24d70 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69  abases for stori
24d80 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a  ng history and.*
24d90 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62  * separate datab
24da0 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20  ases controlled 
24db0 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70  by JavaScript ap
24dc0 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c  plications downl
24dd0 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65  oaded.** off the
24de0 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20   Internet.  The 
24df0 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73  internal databas
24e00 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20  es can be given 
24e10 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65  the.** large, de
24e20 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44  fault limits.  D
24e30 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64  atabases managed
24e40 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75   by external sou
24e50 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67  rces can.** be g
24e60 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65  iven much smalle
24e70 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65  r limits designe
24e80 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64  d to prevent a d
24e90 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65  enial of service
24ea0 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76  .** attack.  Dev
24eb0 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c  elopers might al
24ec0 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74  so want to use t
24ed0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
24ee0 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a  authorizer()].**
24ef0 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75   interface to fu
24f00 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e  rther control un
24f10 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68  trusted SQL.  Th
24f20 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61  e size of the da
24f30 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65  tabase.** create
24f40 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65  d by an untruste
24f50 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20  d script can be 
24f60 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20  contained using 
24f70 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65  the.** [max_page
24f80 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d  _count] [PRAGMA]
24f90 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d  ..**.** New run-
24fa0 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67  time limit categ
24fb0 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64  ories may be add
24fc0 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
24fd0 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71  eases..*/.int sq
24fe0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69  lite3_limit(sqli
24ff0 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e  te3*, int id, in
25000 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a  t newVal);../*.*
25010 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d  * CAPI3REF: Run-
25020 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67  Time Limit Categ
25030 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  ories.** KEYWORD
25040 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f  S: {limit catego
25050 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65  ry} {*limit cate
25060 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68  gories}.**.** Th
25070 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65  ese constants de
25080 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72  fine various per
25090 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a  formance limits.
250a0 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c  ** that can be l
250b0 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69  owered at run-ti
250c0 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  me using [sqlite
250d0 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54  3_limit()]..** T
250e0 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74  he synopsis of t
250f0 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74  he meanings of t
25100 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74  he various limit
25110 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77  s is shown below
25120 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20  ..** Additional 
25130 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61  information is a
25140 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d  vailable at [lim
25150 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20  its | Limits in 
25160 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  SQLite]..**.** <
25170 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  dl>.** [[SQLITE_
25180 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e  LIMIT_LENGTH]] ^
25190 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
251a0 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a  T_LENGTH</dt>.**
251b0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
251c0 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72   size of any str
251d0 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74  ing or BLOB or t
251e0 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 74  able row, in byt
251f0 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  es.<dd>)^.**.** 
25200 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  [[SQLITE_LIMIT_S
25210 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64  QL_LENGTH]] ^(<d
25220 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  t>SQLITE_LIMIT_S
25230 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  QL_LENGTH</dt>.*
25240 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
25250 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53  m length of an S
25260 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e  QL statement, in
25270 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a   bytes.</dd>)^.*
25280 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
25290 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c  MIT_COLUMN]] ^(<
252a0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
252b0 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c  COLUMN</dt>.** <
252c0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
252d0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
252e0 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69   in a table defi
252f0 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65  nition or in the
25300 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f  .** result set o
25310 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20  f a [SELECT] or 
25320 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  the maximum numb
25330 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
25340 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20   an index.** or 
25350 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f  in an ORDER BY o
25360 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73  r GROUP BY claus
25370 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  e.</dd>)^.**.** 
25380 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  [[SQLITE_LIMIT_E
25390 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64  XPR_DEPTH]] ^(<d
253a0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  t>SQLITE_LIMIT_E
253b0 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a  XPR_DEPTH</dt>.*
253c0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
253d0 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 70  m depth of the p
253e0 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79  arse tree on any
253f0 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64   expression.</dd
25400 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
25410 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
25420 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74  D_SELECT]] ^(<dt
25430 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  >SQLITE_LIMIT_CO
25440 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64  MPOUND_SELECT</d
25450 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
25460 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
25470 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f  terms in a compo
25480 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65  und SELECT state
25490 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ment.</dd>)^.**.
254a0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
254b0 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64  T_VDBE_OP]] ^(<d
254c0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  t>SQLITE_LIMIT_V
254d0 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  DBE_OP</dt>.** <
254e0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
254f0 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63  umber of instruc
25500 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75  tions in a virtu
25510 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72  al machine progr
25520 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d  am.** used to im
25530 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73  plement an SQL s
25540 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 69 73 20  tatement.  This 
25550 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 75 72  limit is not cur
25560 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63  rently.** enforc
25570 65 64 2c 20 74 68 6f 75 67 68 20 74 68 61 74 20  ed, though that 
25580 6d 69 67 68 74 20 62 65 20 61 64 64 65 64 20 69  might be added i
25590 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65  n some future re
255a0 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69  lease of.** SQLi
255b0 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  te.</dd>)^.**.**
255c0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
255d0 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e  FUNCTION_ARG]] ^
255e0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
255f0 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f  T_FUNCTION_ARG</
25600 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
25610 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
25620 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20   arguments on a 
25630 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e  function.</dd>)^
25640 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
25650 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 5d 5d  LIMIT_ATTACHED]]
25660 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
25670 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74  MIT_ATTACHED</dt
25680 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
25690 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b  imum number of [
256a0 41 54 54 41 43 48 20 7c 20 61 74 74 61 63 68 65  ATTACH | attache
256b0 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c  d databases].)^<
256c0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
256d0 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50  ITE_LIMIT_LIKE_P
256e0 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a  ATTERN_LENGTH]].
256f0 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
25700 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
25710 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  RN_LENGTH</dt>.*
25720 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
25730 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  m length of the 
25740 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74  pattern argument
25750 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f   to the [LIKE] o
25760 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72  r.** [GLOB] oper
25770 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ators.</dd>)^.**
25780 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
25790 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
257a0 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  ER]].** ^(<dt>SQ
257b0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
257c0 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a  BLE_NUMBER</dt>.
257d0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
257e0 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20  um index number 
257f0 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65  of any [paramete
25800 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61  r] in an SQL sta
25810 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  tement.)^.**.** 
25820 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54  [[SQLITE_LIMIT_T
25830 52 49 47 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e  RIGGER_DEPTH]] ^
25840 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
25850 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c  T_TRIGGER_DEPTH<
25860 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
25870 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66  maximum depth of
25880 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74   recursion for t
25890 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a  riggers.</dd>)^.
258a0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
258b0 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45  IMIT_WORKER_THRE
258c0 41 44 53 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  ADS]] ^(<dt>SQLI
258d0 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f  TE_LIMIT_WORKER_
258e0 54 48 52 45 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20  THREADS</dt>.** 
258f0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
25900 6e 75 6d 62 65 72 20 6f 66 20 61 75 78 69 6c 69  number of auxili
25910 61 72 79 20 77 6f 72 6b 65 72 20 74 68 72 65 61  ary worker threa
25920 64 73 20 74 68 61 74 20 61 20 73 69 6e 67 6c 65  ds that a single
25930 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
25940 61 74 65 6d 65 6e 74 5d 20 6d 61 79 20 73 74 61  atement] may sta
25950 72 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f  rt.</dd>)^.** </
25960 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
25970 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
25980 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
25990 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20        0.#define 
259a0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
259b0 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20  _LENGTH         
259c0 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
259d0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f   SQLITE_LIMIT_CO
259e0 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20  LUMN            
259f0 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
25a00 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  e SQLITE_LIMIT_E
25a10 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20  XPR_DEPTH       
25a20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69           3.#defi
25a30 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
25a40 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20  COMPOUND_SELECT 
25a50 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66            4.#def
25a60 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
25a70 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20  _VDBE_OP        
25a80 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65             5.#de
25a90 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
25aa0 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20  T_FUNCTION_ARG  
25ab0 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64              6.#d
25ac0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
25ad0 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20  IT_ATTACHED     
25ae0 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23               7.#
25af0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
25b00 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
25b10 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a  _LENGTH       8.
25b20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
25b30 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
25b40 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39  MBER           9
25b50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
25b60 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45  LIMIT_TRIGGER_DE
25b70 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31  PTH            1
25b80 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
25b90 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48  _LIMIT_WORKER_TH
25ba0 52 45 41 44 53 20 20 20 20 20 20 20 20 20 20 20  READS           
25bb0 31 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  11../*.** CAPI3R
25bc0 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e  EF: Compiling An
25bd0 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a   SQL Statement.*
25be0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c  * KEYWORDS: {SQL
25bf0 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69   statement compi
25c00 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78  ler}.**.** To ex
25c10 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65  ecute an SQL que
25c20 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73  ry, it must firs
25c30 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e  t be compiled in
25c40 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a  to a byte-code.*
25c50 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20  * program using 
25c60 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75  one of these rou
25c70 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tines..**.** The
25c80 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c   first argument,
25c90 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74   "db", is a [dat
25ca0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
25cb0 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  ] obtained from 
25cc0 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65  a.** prior succe
25cd0 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
25ce0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
25cf0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
25d00 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
25d10 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54  e3_open16()].  T
25d20 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
25d30 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  ection must not 
25d40 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64  have been closed
25d50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ..**.** The seco
25d60 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53  nd argument, "zS
25d70 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 74  ql", is the stat
25d80 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70  ement to be comp
25d90 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a  iled, encoded.**
25da0 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38   as either UTF-8
25db0 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65   or UTF-16.  The
25dc0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
25dd0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
25de0 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69  repare_v2().** i
25df0 6e 74 65 72 66 61 63 65 73 20 75 73 65 20 55 54  nterfaces use UT
25e00 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33  F-8, and sqlite3
25e10 5f 70 72 65 70 61 72 65 31 36 28 29 20 61 6e 64  _prepare16() and
25e20 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
25e30 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55  16_v2().** use U
25e40 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  TF-16..**.** ^If
25e50 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d   the nByte argum
25e60 65 6e 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ent is less than
25e70 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c   zero, then zSql
25e80 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74   is read up to t
25e90 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f  he.** first zero
25ea0 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66   terminator. ^If
25eb0 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65   nByte is non-ne
25ec0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20  gative, then it 
25ed0 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a  is the maximum.*
25ee0 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74  * number of  byt
25ef0 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71  es read from zSq
25f00 6c 2e 20 20 5e 57 68 65 6e 20 6e 42 79 74 65 20  l.  ^When nByte 
25f10 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
25f20 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72   the.** zSql str
25f30 69 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74 68  ing ends at eith
25f40 65 72 20 74 68 65 20 66 69 72 73 74 20 27 5c 30  er the first '\0
25f50 30 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20  00' or '\u0000' 
25f60 63 68 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20  character or.** 
25f70 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74  the nByte-th byt
25f80 65 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d  e, whichever com
25f90 65 73 20 66 69 72 73 74 2e 20 49 66 20 74 68 65  es first. If the
25fa0 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a   caller knows.**
25fb0 20 74 68 61 74 20 74 68 65 20 73 75 70 70 6c 69   that the suppli
25fc0 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c  ed string is nul
25fd0 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65  -terminated, the
25fe0 6e 20 74 68 65 72 65 20 69 73 20 61 20 73 6d 61  n there is a sma
25ff0 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63  ll.** performanc
26000 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62  e advantage to b
26010 65 20 67 61 69 6e 65 64 20 62 79 20 70 61 73 73  e gained by pass
26020 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72  ing an nByte par
26030 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69  ameter that.** i
26040 73 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e  s equal to the n
26050 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
26060 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  n the input stri
26070 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c  ng <i>including<
26080 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74  /i>.** the nul-t
26090 65 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 20  erminator bytes 
260a0 61 73 20 74 68 69 73 20 73 61 76 65 73 20 53 51  as this saves SQ
260b0 4c 69 74 65 20 66 72 6f 6d 20 68 61 76 69 6e 67  Lite from having
260c0 20 74 6f 0a 2a 2a 20 6d 61 6b 65 20 61 20 63 6f   to.** make a co
260d0 70 79 20 6f 66 20 74 68 65 20 69 6e 70 75 74 20  py of the input 
260e0 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49  string..**.** ^I
260f0 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20  f pzTail is not 
26100 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69  NULL then *pzTai
26110 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69  l is made to poi
26120 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  nt to the first 
26130 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65  byte.** past the
26140 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73   end of the firs
26150 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
26160 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20  in zSql.  These 
26170 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a  routines only.**
26180 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72   compile the fir
26190 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  st statement in 
261a0 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c  zSql, so *pzTail
261b0 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
261c0 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d  g to.** what rem
261d0 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e  ains uncompiled.
261e0 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20  .**.** ^*ppStmt 
261f0 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
26200 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b   to a compiled [
26210 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
26220 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a  nt] that can be.
26230 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e  ** executed usin
26240 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
26250 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69  )].  ^If there i
26260 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53  s an error, *ppS
26270 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f  tmt is set.** to
26280 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20   NULL.  ^If the 
26290 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61  input text conta
262a0 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74  ins no SQL (if t
262b0 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65  he input is an e
262c0 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  mpty.** string o
262d0 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65  r a comment) the
262e0 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  n *ppStmt is set
262f0 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65   to NULL..** The
26300 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75   calling procedu
26310 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  re is responsibl
26320 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74  e for deleting t
26330 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53  he compiled.** S
26340 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  QL statement usi
26350 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
26360 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74  lize()] after it
26370 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
26380 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74  th it..** ppStmt
26390 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c   may not be NULL
263a0 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63  ..**.** ^On succ
263b0 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ess, the sqlite3
263c0 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c  _prepare() famil
263d0 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65  y of routines re
263e0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
263f0 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61  ;.** otherwise a
26400 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
26410 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
26420 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72  * The sqlite3_pr
26430 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73  epare_v2() and s
26440 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
26450 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 73  _v2() interfaces
26460 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e   are.** recommen
26470 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20  ded for all new 
26480 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77  programs. The tw
26490 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63  o older interfac
264a0 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a  es are retained.
264b0 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ** for backwards
264c0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20   compatibility, 
264d0 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73  but their use is
264e0 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a   discouraged..**
264f0 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e   ^In the "v2" in
26500 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72  terfaces, the pr
26510 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
26520 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75  .** that is retu
26530 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74  rned (the [sqlit
26540 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29  e3_stmt] object)
26550 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79   contains a copy
26560 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69   of the.** origi
26570 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68  nal SQL text. Th
26580 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73  is causes the [s
26590 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69  qlite3_step()] i
265a0 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62  nterface to.** b
265b0 65 68 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c  ehave differentl
265c0 79 20 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a  y in three ways:
265d0 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
265e0 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64  li>.** ^If the d
265f0 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63  atabase schema c
26600 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20  hanges, instead 
26610 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51  of returning [SQ
26620 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20  LITE_SCHEMA] as 
26630 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65  it.** always use
26640 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65  d to do, [sqlite
26650 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61  3_step()] will a
26660 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63  utomatically rec
26670 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a  ompile the SQL.*
26680 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  * statement and 
26690 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67  try to run it ag
266a0 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73 20  ain. As many as 
266b0 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45  [SQLITE_MAX_SCHE
266c0 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74  MA_RETRY].** ret
266d0 72 69 65 73 20 77 69 6c 6c 20 6f 63 63 75 72 20  ries will occur 
266e0 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 73  before sqlite3_s
266f0 74 65 70 28 29 20 67 69 76 65 73 20 75 70 20 61  tep() gives up a
26700 6e 64 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72  nd returns an er
26710 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  ror..** </li>.**
26720 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65  .** <li>.** ^Whe
26730 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  n an error occur
26740 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  s, [sqlite3_step
26750 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
26760 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69  one of the detai
26770 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f  led.** [error co
26780 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65  des] or [extende
26790 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20  d error codes]. 
267a0 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65 68   ^The legacy beh
267b0 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a  avior was that.*
267c0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
267d0 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65  )] would only re
267e0 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b  turn a generic [
267f0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65  SQLITE_ERROR] re
26800 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64  sult code.** and
26810 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
26820 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d   would have to m
26830 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c  ake a second cal
26840 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  l to [sqlite3_re
26850 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64  set()].** in ord
26860 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75  er to find the u
26870 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20  nderlying cause 
26880 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20  of the problem. 
26890 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72  With the "v2" pr
268a0 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61  epare.** interfa
268b0 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79  ces, the underly
268c0 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74  ing reason for t
268d0 68 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  he error is retu
268e0 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  rned immediately
268f0 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  ..** </li>.**.**
26900 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65   <li>.** ^If the
26910 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20   specific value 
26920 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65  bound to [parame
26930 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d  ter | host param
26940 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a  eter] in the .**
26950 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69   WHERE clause mi
26960 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68  ght influence th
26970 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72  e choice of quer
26980 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61  y plan for a sta
26990 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20  tement,.** then 
269a0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69  the statement wi
269b0 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61  ll be automatica
269c0 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20  lly recompiled, 
269d0 61 73 20 69 66 20 74 68 65 72 65 20 68 61 64 20  as if there had 
269e0 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d  been .** a schem
269f0 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65  a change, on the
26a00 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33   first  [sqlite3
26a10 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f  _step()] call fo
26a20 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e  llowing any chan
26a30 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  ge.** to the [sq
26a40 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20  lite3_bind_text 
26a50 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74  | bindings] of t
26a60 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e  hat [parameter].
26a70 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66   .** ^The specif
26a80 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52  ic value of WHER
26a90 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65  E-clause [parame
26aa0 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75  ter] might influ
26ab0 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f  ence the .** cho
26ac0 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61  ice of query pla
26ad0 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  n if the paramet
26ae0 65 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68  er is the left-h
26af0 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c  and side of a [L
26b00 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42  IKE].** or [GLOB
26b10 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66  ] operator or if
26b20 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
26b30 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e  s compared to an
26b40 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a   indexed column.
26b50 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49  ** and the [SQLI
26b60 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d  TE_ENABLE_STAT3]
26b70 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
26b80 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e  tion is enabled.
26b90 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f  .** </li>.** </o
26ba0 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l>.*/.int sqlite
26bb0 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c  3_prepare(.  sql
26bc0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
26bd0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
26be0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
26bf0 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
26c00 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
26c10 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
26c20 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
26c30 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
26c40 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
26c50 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
26c60 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
26c70 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
26c80 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
26c90 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
26ca0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
26cb0 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
26cc0 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
26cd0 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
26ce0 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
26cf0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
26d00 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
26d10 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
26d20 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
26d30 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
26d40 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
26d50 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
26d60 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
26d70 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
26d80 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
26d90 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
26da0 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
26db0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
26dc0 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
26dd0 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
26de0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
26df0 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
26e00 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
26e10 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
26e20 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
26e30 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
26e40 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20  re16(.  sqlite3 
26e50 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
26e60 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
26e70 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
26e80 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  id *zSql,       
26e90 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
26ea0 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  , UTF-16 encoded
26eb0 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
26ec0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
26ed0 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
26ee0 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
26ef0 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
26f00 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
26f10 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
26f20 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
26f30 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c  st void **pzTail
26f40 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
26f50 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
26f60 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
26f70 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
26f80 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20  _prepare16_v2(. 
26f90 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
26fa0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
26fb0 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
26fc0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71   const void *zSq
26fd0 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
26fe0 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31  statement, UTF-1
26ff0 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  6 encoded */.  i
27000 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
27010 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
27020 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
27030 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
27040 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
27050 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
27060 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
27070 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
27080 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
27090 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
270a0 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
270b0 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f  of zSql */.);../
270c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
270d0 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d  etrieving Statem
270e0 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54  ent SQL.**.** ^T
270f0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
27100 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 74  n be used to ret
27110 72 69 65 76 65 20 61 20 73 61 76 65 64 20 63 6f  rieve a saved co
27120 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e  py of the origin
27130 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75  al.** SQL text u
27140 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 61 20  sed to create a 
27150 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
27160 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74 61  ent] if that sta
27170 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f  tement was.** co
27180 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74  mpiled using eit
27190 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  her [sqlite3_pre
271a0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
271b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
271c0 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74  _v2()]..*/.const
271d0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73   char *sqlite3_s
271e0 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ql(sqlite3_stmt 
271f0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
27200 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d  CAPI3REF: Determ
27210 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74  ine If An SQL St
27220 61 74 65 6d 65 6e 74 20 57 72 69 74 65 73 20 54  atement Writes T
27230 68 65 20 44 61 74 61 62 61 73 65 0a 2a 2a 0a 2a  he Database.**.*
27240 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
27250 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20  tmt_readonly(X) 
27260 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
27270 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f  s true (non-zero
27280 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79  ) if.** and only
27290 20 69 66 20 74 68 65 20 5b 70 72 65 70 61 72 65   if the [prepare
272a0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d  d statement] X m
272b0 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20 63  akes no direct c
272c0 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65  hanges to.** the
272d0 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
272e0 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a  database file..*
272f0 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  *.** Note that [
27300 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
27310 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
27320 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61  s] or.** [virtua
27330 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 20  l tables] might 
27340 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
27350 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20 61  ase indirectly a
27360 73 20 61 20 73 69 64 65 20 65 66 66 65 63 74 2e  s a side effect.
27370 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d    .** ^(For exam
27380 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c 69  ple, if an appli
27390 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 61  cation defines a
273a0 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28   function "eval(
273b0 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c  )" that .** call
273c0 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  s [sqlite3_exec(
273d0 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 6c  )], then the fol
273e0 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74 65  lowing SQL state
273f0 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68  ment would.** ch
27400 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73  ange the databas
27410 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20 73  e file through s
27420 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a  ide-effects:.**.
27430 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
27440 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43  pre>.**    SELEC
27450 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20 46  T eval('DELETE F
27460 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 32  ROM t1') FROM t2
27470 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
27480 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42  ckquote>.**.** B
27490 75 74 20 62 65 63 61 75 73 65 20 74 68 65 20 5b  ut because the [
274a0 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
274b0 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67  t does not chang
274c0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  e the database f
274d0 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c  ile.** directly,
274e0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
274f0 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73  adonly() would s
27500 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 65  till return true
27510 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73  .)^.**.** ^Trans
27520 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73  action control s
27530 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20 61  tatements such a
27540 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d  s [BEGIN], [COMM
27550 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c  IT], [ROLLBACK],
27560 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c  .** [SAVEPOINT],
27570 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 63   and [RELEASE] c
27580 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ause sqlite3_stm
27590 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20  t_readonly() to 
275a0 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20  return true,.** 
275b0 73 69 6e 63 65 20 74 68 65 20 73 74 61 74 65 6d  since the statem
275c0 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73 20  ents themselves 
275d0 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20  do not actually 
275e0 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62  modify the datab
275f0 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 65  ase but.** rathe
27600 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74  r they control t
27610 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 65  he timing of whe
27620 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65 6e  n other statemen
27630 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a  ts modify the .*
27640 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54 68  * database.  ^Th
27650 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 5b  e [ATTACH] and [
27660 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65 6e  DETACH] statemen
27670 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a  ts also cause.**
27680 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
27690 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75  adonly() to retu
276a0 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20 77  rn true since, w
276b0 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74 65  hile those state
276c0 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20  ments.** change 
276d0 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
276e0 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73 65 20  n of a database 
276f0 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79  connection, they
27700 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a   do not make .**
27710 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20   changes to the 
27720 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64  content of the d
27730 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f 6e  atabase files on
27740 20 64 69 73 6b 2e 0a 2a 2f 0a 69 6e 74 20 73 71   disk..*/.int sq
27750 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
27760 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  nly(sqlite3_stmt
27770 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
27780 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72   CAPI3REF: Deter
27790 6d 69 6e 65 20 49 66 20 41 20 50 72 65 70 61 72  mine If A Prepar
277a0 65 64 20 53 74 61 74 65 6d 65 6e 74 20 48 61 73  ed Statement Has
277b0 20 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a 0a 2a   Been Reset.**.*
277c0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
277d0 74 6d 74 5f 62 75 73 79 28 53 29 20 69 6e 74 65  tmt_busy(S) inte
277e0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72  rface returns tr
277f0 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66  ue (non-zero) if
27800 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
27810 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68  d statement] S h
27820 61 73 20 62 65 65 6e 20 73 74 65 70 70 65 64 20  as been stepped 
27830 61 74 20 6c 65 61 73 74 20 6f 6e 63 65 20 75 73  at least once us
27840 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ing .** [sqlite3
27850 5f 73 74 65 70 28 53 29 5d 20 62 75 74 20 68 61  _step(S)] but ha
27860 73 20 6e 6f 74 20 72 75 6e 20 74 6f 20 63 6f 6d  s not run to com
27870 70 6c 65 74 69 6f 6e 20 61 6e 64 2f 6f 72 20 68  pletion and/or h
27880 61 73 20 6e 6f 74 20 0a 2a 2a 20 62 65 65 6e 20  as not .** been 
27890 72 65 73 65 74 20 75 73 69 6e 67 20 5b 73 71 6c  reset using [sql
278a0 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 20  ite3_reset(S)]. 
278b0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74   ^The sqlite3_st
278c0 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69 6e  mt_busy(S).** in
278d0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
278e0 66 61 6c 73 65 20 69 66 20 53 20 69 73 20 61 20  false if S is a 
278f0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49  NULL pointer.  I
27900 66 20 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a 2a  f S is not a .**
27910 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e   NULL pointer an
27920 64 20 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74  d is not a point
27930 65 72 20 74 6f 20 61 20 76 61 6c 69 64 20 5b 70  er to a valid [p
27940 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
27950 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 68  t].** object, th
27960 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
27970 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
27980 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69   probably undesi
27990 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  rable..**.** Thi
279a0 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  s interface can 
279b0 62 65 20 75 73 65 64 20 69 6e 20 63 6f 6d 62 69  be used in combi
279c0 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f  nation [sqlite3_
279d0 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20  next_stmt()].** 
279e0 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70 72  to locate all pr
279f0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
27a00 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  s associated wit
27a10 68 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a 2a  h a database .**
27a20 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
27a30 20 61 72 65 20 69 6e 20 6e 65 65 64 20 6f 66 20   are in need of 
27a40 62 65 69 6e 67 20 72 65 73 65 74 2e 20 20 54 68  being reset.  Th
27a50 69 73 20 63 61 6e 20 62 65 20 75 73 65 64 2c 0a  is can be used,.
27a60 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20  ** for example, 
27a70 69 6e 20 64 69 61 67 6e 6f 73 74 69 63 20 72 6f  in diagnostic ro
27a80 75 74 69 6e 65 73 20 74 6f 20 73 65 61 72 63 68  utines to search
27a90 20 66 6f 72 20 70 72 65 70 61 72 65 64 20 0a 2a   for prepared .*
27aa0 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61  * statements tha
27ab0 74 20 61 72 65 20 68 6f 6c 64 69 6e 67 20 61 20  t are holding a 
27ac0 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e  transaction open
27ad0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
27ae0 5f 73 74 6d 74 5f 62 75 73 79 28 73 71 6c 69 74  _stmt_busy(sqlit
27af0 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
27b00 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61  * CAPI3REF: Dyna
27b10 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61  mically Typed Va
27b20 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45  lue Object.** KE
27b30 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74  YWORDS: {protect
27b40 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
27b50 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  } {unprotected s
27b60 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a  qlite3_value}.**
27b70 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
27b80 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  the sqlite3_valu
27b90 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72  e object to repr
27ba0 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73  esent all values
27bb0 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20  .** that can be 
27bc0 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61  stored in a data
27bd0 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69  base table. SQLi
27be0 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
27bf0 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68  typing.** for th
27c00 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72  e values it stor
27c10 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f  es.  ^Values sto
27c20 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76  red in sqlite3_v
27c30 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20  alue objects.** 
27c40 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c  can be integers,
27c50 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
27c60 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c  values, strings,
27c70 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e   BLOBs, or NULL.
27c80 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65  .**.** An sqlite
27c90 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d  3_value object m
27ca0 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70 72  ay be either "pr
27cb0 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70  otected" or "unp
27cc0 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f  rotected"..** So
27cd0 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72 65  me interfaces re
27ce0 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74 65  quire a protecte
27cf0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
27d00 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63    Other interfac
27d10 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70  es.** will accep
27d20 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74 65  t either a prote
27d30 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f  cted or an unpro
27d40 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
27d50 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69  alue..** Every i
27d60 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61 63  nterface that ac
27d70 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61  cepts sqlite3_va
27d80 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70  lue arguments sp
27d90 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68  ecifies.** wheth
27da0 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71  er or not it req
27db0 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74 65  uires a protecte
27dc0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
27dd0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73  .**.** The terms
27de0 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64   "protected" and
27df0 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72   "unprotected" r
27e00 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20  efer to whether 
27e10 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65  or not.** a mute
27e20 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69  x is held.  An i
27e30 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73  nternal mutex is
27e40 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74   held for a prot
27e50 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
27e60 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75  _value object bu
27e70 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65  t no mutex is he
27e80 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74  ld for an unprot
27e90 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
27ea0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20  _value object.  
27eb0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
27ec0 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67  piled to be sing
27ed0 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28  le-threaded.** (
27ee0 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52  with [SQLITE_THR
27ef0 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77  EADSAFE=0] and w
27f00 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72  ith [sqlite3_thr
27f10 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72  eadsafe()] retur
27f20 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66  ning 0).** or if
27f30 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69   SQLite is run i
27f40 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64  n one of reduced
27f50 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a   mutex modes .**
27f60 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
27f70 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72  SINGLETHREAD] or
27f80 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
27f90 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20  MULTITHREAD].** 
27fa0 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f  then there is no
27fb0 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74   distinction bet
27fc0 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61  ween protected a
27fd0 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  nd unprotected.*
27fe0 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
27ff0 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79  objects and they
28000 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74   can be used int
28010 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48  erchangeably.  H
28020 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d  owever,.** for m
28030 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74  aximum code port
28040 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 65  ability it is re
28050 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61  commended that a
28060 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
28070 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69  till make the di
28080 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
28090 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  n protected and 
280a0 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
280b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
280c0 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e  ects even when n
280d0 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75  ot strictly requ
280e0 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ired..**.** ^The
280f0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
28100 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20  bjects that are 
28110 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65  passed as parame
28120 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  ters into the.**
28130 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
28140 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  of [application-
28150 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
28160 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65  tions] are prote
28170 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  cted..** ^The sq
28180 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
28190 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ct returned by.*
281a0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
281b0 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e  n_value()] is un
281c0 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e  protected..** Un
281d0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
281e0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
281f0 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  may only be used
28200 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65   with.** [sqlite
28210 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
28220 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  ] and [sqlite3_b
28230 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a  ind_value()]..**
28240 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
28250 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74  lue_blob | sqlit
28260 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d  e3_value_type()]
28270 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e   family of.** in
28280 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65  terfaces require
28290 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
282a0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
282b0 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
282c0 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f  uct Mem sqlite3_
282d0 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  value;../*.** CA
282e0 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63  PI3REF: SQL Func
282f0 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a  tion Context Obj
28300 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ect.**.** The co
28310 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61  ntext in which a
28320 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65  n SQL function e
28330 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65  xecutes is store
28340 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  d in an.** sqlit
28350 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
28360 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74  t.  ^A pointer t
28370 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e  o an sqlite3_con
28380 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69  text object.** i
28390 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70  s always first p
283a0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70  arameter to [app
283b0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
283c0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e   SQL functions].
283d0 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
283e0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
283f0 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
28400 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73  ntation will pas
28410 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65  s this.** pointe
28420 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63  r through into c
28430 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
28440 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71  _result_int | sq
28450 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c  lite3_result()],
28460 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67  .** [sqlite3_agg
28470 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
28480 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72  ], [sqlite3_user
28490 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _data()],.** [sq
284a0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
284b0 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c  _handle()], [sql
284c0 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
284d0 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b  ()],.** and/or [
284e0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
284f0 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  ata()]..*/.typed
28500 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
28510 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65  3_context sqlite
28520 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a  3_context;../*.*
28530 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64  * CAPI3REF: Bind
28540 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72  ing Values To Pr
28550 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
28560 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
28570 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20  host parameter} 
28580 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73  {host parameters
28590 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  } {host paramete
285a0 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f  r name}.** KEYWO
285b0 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65  RDS: {SQL parame
285c0 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65  ter} {SQL parame
285d0 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72  ters} {parameter
285e0 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20   binding}.**.** 
285f0 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61  ^(In the SQL sta
28600 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75  tement text inpu
28610 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72  t to [sqlite3_pr
28620 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
28630 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a  its variants,.**
28640 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65   literals may be
28650 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b   replaced by a [
28660 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20  parameter] that 
28670 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66  matches one of f
28680 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70  ollowing.** temp
28690 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  lates:.**.** <ul
286a0 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20  >.** <li>  ?.** 
286b0 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c  <li>  ?NNN.** <l
286c0 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e  i>  :VVV.** <li>
286d0 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20    @VVV.** <li>  
286e0 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  $VVV.** </ul>.**
286f0 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c  .** In the templ
28700 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20  ates above, NNN 
28710 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e  represents an in
28720 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a  teger literal,.*
28730 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 65 73  * and VVV repres
28740 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d  ents an alphanum
28750 65 72 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e  eric identifier.
28760 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20  )^  ^The values 
28770 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61  of these.** para
28780 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c  meters (also cal
28790 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65  led "host parame
287a0 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53  ter names" or "S
287b0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a  QL parameters").
287c0 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73  ** can be set us
287d0 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
287e0 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
287f0 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a  s defined here..
28800 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
28810 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
28820 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
28830 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c  ) routines is al
28840 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  ways.** a pointe
28850 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
28860 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72  3_stmt] object r
28870 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20  eturned from.** 
28880 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
28890 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61  _v2()] or its va
288a0 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  riants..**.** ^T
288b0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
288c0 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20  nt is the index 
288d0 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d  of the SQL param
288e0 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a  eter to be set..
288f0 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  ** ^The leftmost
28900 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68   SQL parameter h
28910 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31  as an index of 1
28920 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d  .  ^When the sam
28930 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70  e named.** SQL p
28940 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64  arameter is used
28950 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c   more than once,
28960 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   second and subs
28970 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72  equent.** occurr
28980 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73  ences have the s
28990 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65  ame index as the
289a0 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63   first occurrenc
289b0 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78  e..** ^The index
289c0 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d   for named param
289d0 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f  eters can be loo
289e0 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65  ked up using the
289f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
28a00 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
28a10 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69  x()] API if desi
28a20 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78  red.  ^The index
28a30 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70  .** for "?NNN" p
28a40 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65  arameters is the
28a50 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a   value of NNN..*
28a60 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65  * ^The NNN value
28a70 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e   must be between
28a80 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69   1 and the [sqli
28a90 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20  te3_limit()].** 
28aa0 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54  parameter [SQLIT
28ab0 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
28ac0 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c  _NUMBER] (defaul
28ad0 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a  t value: 999)..*
28ae0 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20  *.** ^The third 
28af0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
28b00 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f  value to bind to
28b10 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
28b20 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72 64  ** ^If the third
28b30 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
28b40 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
28b50 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  ) or sqlite3_bin
28b60 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 6f 72  d_text16().** or
28b70 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
28b80 6f 62 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ob() is a NULL p
28b90 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20  ointer then the 
28ba0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
28bb0 0a 2a 2a 20 69 73 20 69 67 6e 6f 72 65 64 20 61  .** is ignored a
28bc0 6e 64 20 74 68 65 20 65 6e 64 20 72 65 73 75 6c  nd the end resul
28bd0 74 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73  t is the same as
28be0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75   sqlite3_bind_nu
28bf0 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  ll()..**.** ^(In
28c00 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20   those routines 
28c10 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72  that have a four
28c20 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73  th argument, its
28c30 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a   value is the.**
28c40 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
28c50 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65   in the paramete
28c60 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a  r.  To be clear:
28c70 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68   the value is th
28c80 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c  e.** number of <
28c90 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74  u>bytes</u> in t
28ca0 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68  he value, not th
28cb0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
28cc0 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66  acters.)^.** ^If
28cd0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
28ce0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
28cf0 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20  _bind_text() or 
28d00 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
28d10 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61  t16().** is nega
28d20 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 6c  tive, then the l
28d30 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 72  ength of the str
28d40 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75  ing is.** the nu
28d50 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 70  mber of bytes up
28d60 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65   to the first ze
28d70 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a  ro terminator..*
28d80 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20  * If the fourth 
28d90 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
28da0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
28db0 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
28dc0 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61 76 69  en.** the behavi
28dd0 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
28de0 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67  .** If a non-neg
28df0 61 74 69 76 65 20 66 6f 75 72 74 68 20 70 61 72  ative fourth par
28e00 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76 69 64  ameter is provid
28e10 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  ed to sqlite3_bi
28e20 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20  nd_text().** or 
28e30 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
28e40 74 31 36 28 29 20 74 68 65 6e 20 74 68 61 74 20  t16() then that 
28e50 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62  parameter must b
28e60 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73 65  e the byte offse
28e70 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 20 4e  t.** where the N
28e80 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f  UL terminator wo
28e90 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75 6d 69  uld occur assumi
28ea0 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20 77 65  ng the string we
28eb0 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e  re NUL.** termin
28ec0 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55  ated.  If any NU
28ed0 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 63  L characters occ
28ee0 75 72 20 61 74 20 62 79 74 65 20 6f 66 66 73 65  ur at byte offse
28ef0 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a  ts less than .**
28f00 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
28f10 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
28f20 65 72 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  er then the resu
28f30 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76 61 6c  lting string val
28f40 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61  ue will.** conta
28f50 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73  in embedded NULs
28f60 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 6f 66  .  The result of
28f70 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e 76   expressions inv
28f80 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a  olving strings.*
28f90 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 20  * with embedded 
28fa0 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65  NULs is undefine
28fb0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  d..**.** ^The fi
28fc0 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  fth argument to 
28fd0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
28fe0 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e  b(), sqlite3_bin
28ff0 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a  d_text(), and.**
29000 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
29010 78 74 31 36 28 29 20 69 73 20 61 20 64 65 73 74  xt16() is a dest
29020 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64  ructor used to d
29030 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c  ispose of the BL
29040 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20  OB or.** string 
29050 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73  after SQLite has
29060 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
29070 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75 63  t.  ^The destruc
29080 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a  tor is called.**
29090 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74   to dispose of t
290a0 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  he BLOB or strin
290b0 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 63 61  g even if the ca
290c0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  ll to sqlite3_bi
290d0 6e 64 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20 73 71  nd_blob(),.** sq
290e0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
290f0 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  ), or sqlite3_bi
29100 6e 64 5f 74 65 78 74 31 36 28 29 20 66 61 69 6c  nd_text16() fail
29110 73 2e 20 20 0a 2a 2a 20 5e 49 66 20 74 68 65 20  s.  .** ^If the 
29120 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69  fifth argument i
29130 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c  s.** the special
29140 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53   value [SQLITE_S
29150 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c  TATIC], then SQL
29160 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74  ite assumes that
29170 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74   the.** informat
29180 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63  ion is in static
29190 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63  , unmanaged spac
291a0 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e  e and does not n
291b0 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e  eed to be freed.
291c0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74  .** ^If the fift
291d0 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74  h argument has t
291e0 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  he value [SQLITE
291f0 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65  _TRANSIENT], the
29200 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65  n.** SQLite make
29210 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74  s its own privat
29220 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61  e copy of the da
29230 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20  ta immediately, 
29240 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71  before.** the sq
29250 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
29260 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a  outine returns..
29270 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
29280 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
29290 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73  () routine binds
292a0 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74   a BLOB of lengt
292b0 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66  h N that.** is f
292c0 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65  illed with zeroe
292d0 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20  s.  ^A zeroblob 
292e0 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f  uses a fixed amo
292f0 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a  unt of memory.**
29300 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65   (just an intege
29310 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69  r to hold its si
29320 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20  ze) while it is 
29330 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e  being processed.
29340 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72  .** Zeroblobs ar
29350 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65  e intended to se
29360 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64  rve as placehold
29370 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68  ers for BLOBs wh
29380 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69  ose.** content i
29390 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20  s later written 
293a0 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
293b0 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e  3_blob_open | in
293c0 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49  cremental BLOB I
293d0 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  /O] routines..**
293e0 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c   ^A negative val
293f0 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62  ue for the zerob
29400 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61  lob results in a
29410 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f   zero-length BLO
29420 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79  B..**.** ^If any
29430 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
29440 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
29450 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74  s are called wit
29460 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
29470 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65  .** for the [pre
29480 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
29490 20 6f 72 20 77 69 74 68 20 61 20 70 72 65 70 61   or with a prepa
294a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f  red statement fo
294b0 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69  r which.** [sqli
294c0 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
294d0 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65  been called more
294e0 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b   recently than [
294f0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
29500 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61  ,.** then the ca
29510 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  ll will return [
29520 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
29530 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f   If any sqlite3_
29540 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69  bind_().** routi
29550 6e 65 20 69 73 20 70 61 73 73 65 64 20 61 20 5b  ne is passed a [
29560 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
29570 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62 65 65  nt] that has bee
29580 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65  n finalized, the
29590 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e  .** result is un
295a0 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62  defined and prob
295b0 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a  ably harmful..**
295c0 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72  .** ^Bindings ar
295d0 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79  e not cleared by
295e0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   the [sqlite3_re
295f0 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a  set()] routine..
29600 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61  ** ^Unbound para
29610 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72  meters are inter
29620 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a  preted as NULL..
29630 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
29640 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e  e3_bind_* routin
29650 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
29660 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
29670 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72   or an.** [error
29680 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69   code] if anythi
29690 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a  ng goes wrong..*
296a0 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45  * ^[SQLITE_RANGE
296b0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  ] is returned if
296c0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a   the parameter.*
296d0 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f  * index is out o
296e0 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49  f range.  ^[SQLI
296f0 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74  TE_NOMEM] is ret
29700 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28  urned if malloc(
29710 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53  ) fails..**.** S
29720 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
29730 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
29740 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73  _count()],.** [s
29750 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
29760 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61  meter_name()], a
29770 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  nd [sqlite3_bind
29780 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
29790 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
297a0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71  te3_bind_blob(sq
297b0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
297c0 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
297d0 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f  nt n, void(*)(vo
297e0 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
297f0 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73  e3_bind_double(s
29800 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
29810 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20  t, double);.int 
29820 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74  sqlite3_bind_int
29830 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
29840 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73  int, int);.int s
29850 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36  qlite3_bind_int6
29860 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
29870 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e   int, sqlite3_in
29880 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  t64);.int sqlite
29890 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69  3_bind_null(sqli
298a0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b  te3_stmt*, int);
298b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
298c0 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73  d_text(sqlite3_s
298d0 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
298e0 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76   char*, int n, v
298f0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
29900 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
29910 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
29920 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
29930 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
29940 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
29950 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
29960 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74  value(sqlite3_st
29970 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
29980 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
29990 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
299a0 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74  d_zeroblob(sqlit
299b0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69  e3_stmt*, int, i
299c0 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt n);../*.** CA
299d0 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f  PI3REF: Number O
299e0 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73  f SQL Parameters
299f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
29a00 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64  tine can be used
29a10 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d   to find the num
29a20 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61  ber of [SQL para
29a30 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20  meters].** in a 
29a40 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
29a50 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d  ent].  SQL param
29a60 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73  eters are tokens
29a70 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20   of the.** form 
29a80 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41  "?", "?NNN", ":A
29a90 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20  AA", "$AAA", or 
29aa0 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76  "@AAA" that serv
29ab0 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c  e as.** placehol
29ac0 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20  ders for values 
29ad0 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65  that are [sqlite
29ae0 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f  3_bind_blob | bo
29af0 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70  und].** to the p
29b00 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c  arameters at a l
29b10 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  ater time..**.**
29b20 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20   ^(This routine 
29b30 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73  actually returns
29b40 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
29b50 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74  e largest (right
29b60 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74  most).** paramet
29b70 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d  er. For all form
29b80 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74  s except ?NNN, t
29b90 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70  his will corresp
29ba0 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75  ond to the.** nu
29bb0 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70  mber of unique p
29bc0 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70  arameters.  If p
29bd0 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
29be0 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75   ?NNN form are u
29bf0 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61  sed,.** there ma
29c00 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65  y be gaps in the
29c10 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53   list.)^.**.** S
29c20 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
29c30 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
29c40 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
29c50 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
29c60 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c  rameter_name()],
29c70 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
29c80 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
29c90 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  index()]..*/.int
29ca0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
29cb0 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71  rameter_count(sq
29cc0 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
29cd0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
29ce0 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61  ame Of A Host Pa
29cf0 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54  rameter.**.** ^T
29d00 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
29d10 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50  parameter_name(P
29d20 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  ,N) interface re
29d30 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d  turns.** the nam
29d40 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53  e of the N-th [S
29d50 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  QL parameter] in
29d60 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
29d70 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20  tatement] P..** 
29d80 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73  ^(SQL parameters
29d90 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e   of the form "?N
29da0 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72  NN" or ":AAA" or
29db0 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41   "@AAA" or "$AAA
29dc0 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65  ".** have a name
29dd0 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74   which is the st
29de0 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22  ring "?NNN" or "
29df0 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
29e00 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73  or "$AAA".** res
29e10 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e  pectively..** In
29e20 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
29e30 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72  e initial ":" or
29e40 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22   "$" or "@" or "
29e50 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65  ?".** is include
29e60 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  d as part of the
29e70 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72   name.)^.** ^Par
29e80 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
29e90 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20  orm "?" without 
29ea0 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65  a following inte
29eb0 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65  ger have no name
29ec0 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65  .** and are refe
29ed0 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65  rred to as "name
29ee0 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d  less" or "anonym
29ef0 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e  ous parameters".
29f00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
29f10 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  t host parameter
29f20 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
29f30 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a   1, not 0..**.**
29f40 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e   ^If the value N
29f50 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
29f60 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20   or if the N-th 
29f70 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
29f80 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e  nameless, then N
29f90 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ULL is returned.
29fa0 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20    ^The returned 
29fb0 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77  string is.** alw
29fc0 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63  ays in UTF-8 enc
29fd0 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68  oding even if th
29fe0 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  e named paramete
29ff0 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61  r was.** origina
2a000 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73  lly specified as
2a010 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69   UTF-16 in [sqli
2a020 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
2a030 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
2a040 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
2a050 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
2a060 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2a070 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
2a080 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
2a090 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2a0a0 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a  count()], and.**
2a0b0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2a0c0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
2a0d0 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  ]..*/.const char
2a0e0 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   *sqlite3_bind_p
2a0f0 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71  arameter_name(sq
2a100 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2a110 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2a120 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50  EF: Index Of A P
2a130 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 20  arameter With A 
2a140 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a  Given Name.**.**
2a150 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64   ^Return the ind
2a160 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72  ex of an SQL par
2a170 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73  ameter given its
2a180 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20   name.  ^The.** 
2a190 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75  index value retu
2a1a0 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65  rned is suitable
2a1b0 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20   for use as the 
2a1c0 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65  second.** parame
2a1d0 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
2a1e0 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
2a1f0 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a  3_bind()].  ^A z
2a200 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  ero.** is return
2a210 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e  ed if no matchin
2a220 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66  g parameter is f
2a230 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61  ound.  ^The para
2a240 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75  meter.** name mu
2a250 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55  st be given in U
2a260 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65  TF-8 even if the
2a270 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d   original statem
2a280 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61  ent.** was prepa
2a290 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20  red from UTF-16 
2a2a0 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  text using [sqli
2a2b0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2a2c0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ()]..**.** See a
2a2d0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
2a2e0 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
2a2f0 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
2a300 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2a310 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e  ter_count()], an
2a320 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
2a330 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
2a340 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ex()]..*/.int sq
2a350 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2a360 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74  eter_index(sqlit
2a370 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20  e3_stmt*, const 
2a380 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f  char *zName);../
2a390 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
2a3a0 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67  eset All Binding
2a3b0 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20  s On A Prepared 
2a3c0 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20  Statement.**.** 
2a3d0 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65  ^Contrary to the
2a3e0 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61   intuition of ma
2a3f0 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ny, [sqlite3_res
2a400 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72  et()] does not r
2a410 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  eset.** the [sql
2a420 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
2a430 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20   bindings] on a 
2a440 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2a450 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68  ent]..** ^Use th
2a460 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65  is routine to re
2a470 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72  set all host par
2a480 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e  ameters to NULL.
2a490 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2a4a0 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73  clear_bindings(s
2a4b0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
2a4c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2a4d0 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e  Number Of Column
2a4e0 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65  s In A Result Se
2a4f0 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20  t.**.** ^Return 
2a500 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
2a510 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
2a520 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64  ult set returned
2a530 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   by the.** [prep
2a540 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
2a550 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
2a560 65 74 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d  eturns 0 if pStm
2a570 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73  t is an SQL.** s
2a580 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f  tatement that do
2a590 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61  es not return da
2a5a0 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  ta (for example 
2a5b0 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a  an [UPDATE])..**
2a5c0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
2a5d0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
2a5e0 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  t()].*/.int sqli
2a5f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
2a600 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
2a610 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
2a620 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e  PI3REF: Column N
2a630 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74  ames In A Result
2a640 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73   Set.**.** ^Thes
2a650 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
2a660 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67  n the name assig
2a670 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 75  ned to a particu
2a680 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e  lar column.** in
2a690 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
2a6a0 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74  of a [SELECT] st
2a6b0 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73  atement.  ^The s
2a6c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
2a6d0 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  me().** interfac
2a6e0 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
2a6f0 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65  ter to a zero-te
2a700 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
2a710 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c  tring.** and sql
2a720 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
2a730 31 36 28 29 20 72 65 74 75 72 6e 73 20 61 20 70  16() returns a p
2a740 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f  ointer to a zero
2a750 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55  -terminated.** U
2a760 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e  TF-16 string.  ^
2a770 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
2a780 74 65 72 20 69 73 20 74 68 65 20 5b 70 72 65 70  ter is the [prep
2a790 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
2a7a0 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ** that implemen
2a7b0 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20  ts the [SELECT] 
2a7c0 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20  statement. ^The 
2a7d0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
2a7e0 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d   is the.** colum
2a7f0 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 20  n number.  ^The 
2a800 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  leftmost column 
2a810 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a  is number 0..**.
2a820 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  ** ^The returned
2a830 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20   string pointer 
2a840 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65  is valid until e
2a850 69 74 68 65 72 20 74 68 65 20 5b 70 72 65 70 61  ither the [prepa
2a860 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
2a870 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 62  * is destroyed b
2a880 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  y [sqlite3_final
2a890 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20  ize()] or until 
2a8a0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
2a8b0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a   automatically.*
2a8c0 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20  * reprepared by 
2a8d0 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74  the first call t
2a8e0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
2a8f0 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  )] for a particu
2a900 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e  lar run.** or un
2a910 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c  til the next cal
2a920 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  l to.** sqlite3_
2a930 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72  column_name() or
2a940 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2a950 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20  name16() on the 
2a960 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a  same column..**.
2a970 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d  ** ^If sqlite3_m
2a980 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75  alloc() fails du
2a990 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73  ring the process
2a9a0 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f  ing of either ro
2a9b0 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78  utine.** (for ex
2a9c0 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63  ample during a c
2a9d0 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55  onversion from U
2a9e0 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20  TF-8 to UTF-16) 
2a9f0 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70  then a.** NULL p
2aa00 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e  ointer is return
2aa10 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e  ed..**.** ^The n
2aa20 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20  ame of a result 
2aa30 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61  column is the va
2aa40 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53 22 20  lue of the "AS" 
2aa50 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68  clause for.** th
2aa60 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68  at column, if th
2aa70 65 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61  ere is an AS cla
2aa80 75 73 65 2e 20 20 49 66 20 74 68 65 72 65 20 69  use.  If there i
2aa90 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a  s no AS clause.*
2aaa0 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20  * then the name 
2aab0 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73  of the column is
2aac0 20 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64   unspecified and
2aad0 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d   may change from
2aae0 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20  .** one release 
2aaf0 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65  of SQLite to the
2ab00 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20   next..*/.const 
2ab10 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2ab20 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65  lumn_name(sqlite
2ab30 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b  3_stmt*, int N);
2ab40 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
2ab50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
2ab60 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2ab70 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int N);../*.**
2ab80 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63   CAPI3REF: Sourc
2ab90 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51  e Of Data In A Q
2aba0 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a  uery Result.**.*
2abb0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
2abc0 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e  s provide a mean
2abd0 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74  s to determine t
2abe0 68 65 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  he database, tab
2abf0 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65  le, and.** table
2ac00 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20   column that is 
2ac10 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20  the origin of a 
2ac20 70 61 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c  particular resul
2ac30 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b  t column in.** [
2ac40 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
2ac50 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20  t..** ^The name 
2ac60 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
2ac70 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75  or table or colu
2ac80 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e  mn can be return
2ac90 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20  ed as.** either 
2aca0 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  a UTF-8 or UTF-1
2acb0 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20  6 string.  ^The 
2acc0 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69  _database_ routi
2acd0 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68  nes return.** th
2ace0 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c  e database name,
2acf0 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75   the _table_ rou
2ad00 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
2ad10 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64   table name, and
2ad20 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20  .** the origin_ 
2ad30 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
2ad40 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e  the column name.
2ad50 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65  .** ^The returne
2ad60 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69  d string is vali
2ad70 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65  d until the [pre
2ad80 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2ad90 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a   is destroyed.**
2ada0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2adb0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75  finalize()] or u
2adc0 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65  ntil the stateme
2add0 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61  nt is automatica
2ade0 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65  lly.** reprepare
2adf0 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63  d by the first c
2ae00 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2ae10 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61  step()] for a pa
2ae20 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20  rticular run.** 
2ae30 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d  or until the sam
2ae40 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  e information is
2ae50 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67   requested.** ag
2ae60 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65  ain in a differe
2ae70 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a  nt encoding..**.
2ae80 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65  ** ^The names re
2ae90 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f  turned are the o
2aea0 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73  riginal un-alias
2aeb0 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a  ed names of the.
2aec0 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  ** database, tab
2aed0 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a  le, and column..
2aee0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
2aef0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
2af00 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 69 73  se interfaces is
2af10 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2af20 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65  tement]..** ^The
2af30 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  se functions ret
2af40 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  urn information 
2af50 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65  about the Nth re
2af60 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75  sult column retu
2af70 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73  rned by.** the s
2af80 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20  tatement, where 
2af90 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  N is the second 
2afa0 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
2afb0 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d  t..** ^The left-
2afc0 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63  most column is c
2afd0 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73  olumn 0 for thes
2afe0 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  e routines..**.*
2aff0 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f  * ^If the Nth co
2b000 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79  lumn returned by
2b010 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
2b020 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20  s an expression 
2b030 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61  or.** subquery a
2b040 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75  nd is not a colu
2b050 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61  mn value, then a
2b060 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63  ll of these func
2b070 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20  tions return.** 
2b080 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f  NULL.  ^These ro
2b090 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f  utine might also
2b0a0 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20   return NULL if 
2b0b0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
2b0c0 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63  ion error.** occ
2b0d0 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65  urs.  ^Otherwise
2b0e0 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68  , they return th
2b0f0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74  e name of the at
2b100 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c  tached database,
2b110 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f   table,.** or co
2b120 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20  lumn that query 
2b130 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61  result column wa
2b140 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d  s extracted from
2b150 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68  ..**.** ^As with
2b160 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74   all other SQLit
2b170 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68  e APIs, those wh
2b180 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69  ose names end wi
2b190 74 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a  th "16" return.*
2b1a0 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  * UTF-16 encoded
2b1b0 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65   strings and the
2b1c0 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73   other functions
2b1d0 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a   return UTF-8..*
2b1e0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73  *.** ^These APIs
2b1f0 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61   are only availa
2b200 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61  ble if the libra
2b210 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  ry was compiled 
2b220 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
2b230 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d  ITE_ENABLE_COLUM
2b240 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72  N_METADATA] C-pr
2b250 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f  eprocessor symbo
2b260 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20  l..**.** If two 
2b270 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  or more threads 
2b280 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  call one or more
2b290 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
2b2a0 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73  es against the s
2b2b0 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20  ame.** prepared 
2b2c0 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f  statement and co
2b2d0 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65  lumn at the same
2b2e0 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72   time then the r
2b2f0 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e  esults are.** un
2b300 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  defined..**.** I
2b310 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68  f two or more th
2b320 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f  reads call one o
2b330 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74  r more.** [sqlit
2b340 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
2b350 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e  se_name | column
2b360 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66   metadata interf
2b370 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65  aces].** for the
2b380 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20   same [prepared 
2b390 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72  statement] and r
2b3a0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  esult column.** 
2b3b0 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
2b3c0 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
2b3d0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
2b3e0 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
2b3f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
2b400 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c  atabase_name(sql
2b410 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
2b420 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
2b430 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
2b440 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69  base_name16(sqli
2b450 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2b460 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
2b470 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65  te3_column_table
2b480 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
2b490 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
2b4a0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
2b4b0 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31  lumn_table_name1
2b4c0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2b4d0 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  int);.const char
2b4e0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2b4f0 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c  _origin_name(sql
2b500 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
2b510 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
2b520 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67  ite3_column_orig
2b530 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  in_name16(sqlite
2b540 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f  3_stmt*,int);../
2b550 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2b560 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65  eclared Datatype
2b570 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75   Of A Query Resu
2b580 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66  lt.**.** ^(The f
2b590 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
2b5a0 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  s a [prepared st
2b5b0 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20  atement]..** If 
2b5c0 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69  this statement i
2b5d0 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  s a [SELECT] sta
2b5e0 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e  tement and the N
2b5f0 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  th column of the
2b600 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73  .** returned res
2b610 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20  ult set of that 
2b620 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61  [SELECT] is a ta
2b630 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20  ble column (not 
2b640 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  an.** expression
2b650 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68   or subquery) th
2b660 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  en the declared 
2b670 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c  type of the tabl
2b680 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72  e.** column is r
2b690 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20  eturned.)^  ^If 
2b6a0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
2b6b0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
2b6c0 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73   is an.** expres
2b6d0 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
2b6e0 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f  , then a NULL po
2b6f0 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
2b700 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  d..** ^The retur
2b710 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c  ned string is al
2b720 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64  ways UTF-8 encod
2b730 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20  ed..**.** ^(For 
2b740 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74  example, given t
2b750 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
2b760 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45  ma:.**.** CREATE
2b770 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52   TABLE t1(c1 VAR
2b780 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64  IANT);.**.** and
2b790 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73   the following s
2b7a0 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63  tatement to be c
2b7b0 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53  ompiled:.**.** S
2b7c0 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31  ELECT c1 + 1, c1
2b7d0 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20   FROM t1;.**.** 
2b7e0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75  this routine wou
2b7f0 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74  ld return the st
2b800 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66  ring "VARIANT" f
2b810 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65  or the second re
2b820 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28  sult.** column (
2b830 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c  i==1), and a NUL
2b840 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68  L pointer for th
2b850 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63  e first result c
2b860 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a  olumn (i==0).)^.
2b870 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73  **.** ^SQLite us
2b880 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74  es dynamic run-t
2b890 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f  ime typing.  ^So
2b8a0 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20   just because a 
2b8b0 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63  column.** is dec
2b8c0 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e  lared to contain
2b8d0 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79   a particular ty
2b8e0 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e  pe does not mean
2b8f0 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74   that the.** dat
2b900 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74  a stored in that
2b910 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68   column is of th
2b920 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e  e declared type.
2b930 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73    SQLite is.** s
2b940 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62  trongly typed, b
2b950 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73  ut the typing is
2b960 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61   dynamic not sta
2b970 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69  tic.  ^Type.** i
2b980 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  s associated wit
2b990 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c  h individual val
2b9a0 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68  ues, not with th
2b9b0 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20  e containers.** 
2b9c0 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f  used to hold tho
2b9d0 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f  se values..*/.co
2b9e0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
2b9f0 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
2ba00 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2ba10 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
2ba20 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2ba30 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69  _decltype16(sqli
2ba40 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2ba50 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2ba60 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c   Evaluate An SQL
2ba70 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a   Statement.**.**
2ba80 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 61 72   After a [prepar
2ba90 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61  ed statement] ha
2baa0 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64 20  s been prepared 
2bab0 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20  using either.** 
2bac0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2bad0 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
2bae0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2baf0 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65  )] or one of the
2bb00 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
2bb10 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70  faces [sqlite3_p
2bb20 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71  repare()] or [sq
2bb30 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
2bb40 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f  )], this functio
2bb50 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c  n.** must be cal
2bb60 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  led one or more 
2bb70 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74  times to evaluat
2bb80 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e  e the statement.
2bb90 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69  .**.** The detai
2bba0 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 69  ls of the behavi
2bbb0 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  or of the sqlite
2bbc0 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 61  3_step() interfa
2bbd0 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20  ce depend.** on 
2bbe0 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61 74  whether the stat
2bbf0 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 72  ement was prepar
2bc00 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77  ed using the new
2bc10 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  er "v2" interfac
2bc20 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  e.** [sqlite3_pr
2bc30 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
2bc40 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2bc50 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20  16_v2()] or the 
2bc60 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20  older legacy.** 
2bc70 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74  interface [sqlit
2bc80 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
2bc90 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
2bca0 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73  re16()].  The us
2bcb0 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20  e of the.** new 
2bcc0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69  "v2" interface i
2bcd0 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  s recommended fo
2bce0 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  r new applicatio
2bcf0 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 61 63  ns but the legac
2bd00 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77  y.** interface w
2bd10 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20  ill continue to 
2bd20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a  be supported..**
2bd30 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67 61  .** ^In the lega
2bd40 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  cy interface, th
2bd50 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77  e return value w
2bd60 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53  ill be either [S
2bd70 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20  QLITE_BUSY],.** 
2bd80 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b  [SQLITE_DONE], [
2bd90 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51  SQLITE_ROW], [SQ
2bda0 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20  LITE_ERROR], or 
2bdb0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
2bdc0 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22 76  .** ^With the "v
2bdd0 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e  2" interface, an
2bde0 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b  y of the other [
2bdf0 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72  result codes] or
2be00 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
2be10 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 68  sult codes] migh
2be20 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73  t be returned as
2be30 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53   well..**.** ^[S
2be40 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e  QLITE_BUSY] mean
2be50 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62  s that the datab
2be60 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75  ase engine was u
2be70 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65  nable to acquire
2be80 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
2be90 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20   locks it needs 
2bea0 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20  to do its job.  
2beb0 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e  ^If the statemen
2bec0 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a  t is a [COMMIT].
2bed0 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74  ** or occurs out
2bee0 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69  side of an expli
2bef0 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  cit transaction,
2bf00 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65   then you can re
2bf10 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65  try the.** state
2bf20 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74  ment.  If the st
2bf30 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61  atement is not a
2bf40 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63   [COMMIT] and oc
2bf50 63 75 72 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a  curs within an.*
2bf60 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  * explicit trans
2bf70 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20  action then you 
2bf80 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20  should rollback 
2bf90 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
2bfa0 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e  before.** contin
2bfb0 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51  uing..**.** ^[SQ
2bfc0 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73  LITE_DONE] means
2bfd0 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65 6d   that the statem
2bfe0 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65 64  ent has finished
2bff0 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75   executing.** su
2c000 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c  ccessfully.  sql
2c010 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75  ite3_step() shou
2c020 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64  ld not be called
2c030 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76   again on this v
2c040 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
2c050 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 20  e without first 
2c060 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
2c070 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73  _reset()] to res
2c080 65 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a  et the virtual.*
2c090 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74  * machine back t
2c0a0 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74  o its initial st
2c0b0 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ate..**.** ^If t
2c0c0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
2c0d0 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 20   being executed 
2c0e0 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61  returns any data
2c0f0 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52  , then [SQLITE_R
2c100 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  OW].** is return
2c110 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e  ed each time a n
2c120 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69  ew row of data i
2c130 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63  s ready for proc
2c140 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a  essing by the.**
2c150 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c   caller. The val
2c160 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65 73  ues may be acces
2c170 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63  sed using the [c
2c180 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
2c190 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69  ctions]..** sqli
2c1a0 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 61  te3_step() is ca
2c1b0 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65  lled again to re
2c1c0 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 20  trieve the next 
2c1d0 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a  row of data..**.
2c1e0 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ** ^[SQLITE_ERRO
2c1f0 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20  R] means that a 
2c200 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28  run-time error (
2c210 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72  such as a constr
2c220 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f  aint.** violatio
2c230 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e  n) has occurred.
2c240 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
2c250 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
2c260 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a  alled again on.*
2c270 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69  * the VM. More i
2c280 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62  nformation may b
2c290 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69  e found by calli
2c2a0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ng [sqlite3_errm
2c2b0 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20  sg()]..** ^With 
2c2c0 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
2c2d0 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65  face, a more spe
2c2e0 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65  cific error code
2c2f0 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a   (for example,.*
2c300 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  * [SQLITE_INTERR
2c310 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43  UPT], [SQLITE_SC
2c320 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43  HEMA], [SQLITE_C
2c330 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20  ORRUPT], and so 
2c340 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65  forth).** can be
2c350 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c   obtained by cal
2c360 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
2c370 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a  set()] on the.**
2c380 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2c390 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20  ment].  ^In the 
2c3a0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a  "v2" interface,.
2c3b0 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63  ** the more spec
2c3c0 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20  ific error code 
2c3d0 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 65  is returned dire
2c3e0 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ctly by sqlite3_
2c3f0 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53  step()..**.** [S
2c400 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65  QLITE_MISUSE] me
2c410 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 69  ans that the thi
2c420 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61  s routine was ca
2c430 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61  lled inappropria
2c440 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73  tely..** Perhaps
2c450 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f   it was called o
2c460 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
2c470 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61  atement] that ha
2c480 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65  s.** already bee
2c490 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  n [sqlite3_final
2c4a0 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d  ize | finalized]
2c4b0 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20   or on one that 
2c4c0 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  had.** previousl
2c4d0 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  y returned [SQLI
2c4e0 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51  TE_ERROR] or [SQ
2c4f0 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20  LITE_DONE].  Or 
2c500 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74  it could.** be t
2c510 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
2c520 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
2c530 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69  onnection is bei
2c540 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f  ng used by two o
2c550 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64  r.** more thread
2c560 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f  s at the same mo
2c570 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a  ment in time..**
2c580 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72 73  .** For all vers
2c590 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 75  ions of SQLite u
2c5a0 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69  p to and includi
2c5b0 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63  ng 3.6.23.1, a c
2c5c0 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
2c5d0 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61 73 20  e3_reset()] was 
2c5e0 72 65 71 75 69 72 65 64 20 61 66 74 65 72 20 73  required after s
2c5f0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72 65  qlite3_step() re
2c600 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a  turned anything.
2c610 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ** other than [S
2c620 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72  QLITE_ROW] befor
2c630 65 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74  e any subsequent
2c640 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a   invocation of.*
2c650 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
2c660 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20 72 65  .  Failure to re
2c670 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64  set the prepared
2c680 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
2c690 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65   .** [sqlite3_re
2c6a0 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72 65 73  set()] would res
2c6b0 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54  ult in an [SQLIT
2c6c0 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72 6e  E_MISUSE] return
2c6d0 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33   from.** sqlite3
2c6e0 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20 61 66  _step().  But af
2c6f0 74 65 72 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e  ter version 3.6.
2c700 32 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f 73 74  23.1, sqlite3_st
2c710 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61  ep() began.** ca
2c720 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
2c730 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74 69  eset()] automati
2c740 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69  cally in this ci
2c750 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65  rcumstance rathe
2c760 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72 6e  r.** than return
2c770 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  ing [SQLITE_MISU
2c780 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e 6f  SE].  This is no
2c790 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20 63  t considered a c
2c7a0 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20  ompatibility.** 
2c7b0 62 72 65 61 6b 20 62 65 63 61 75 73 65 20 61 6e  break because an
2c7c0 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68  y application th
2c7d0 61 74 20 65 76 65 72 20 72 65 63 65 69 76 65 73  at ever receives
2c7e0 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53   an SQLITE_MISUS
2c7f0 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72  E error.** is br
2c800 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74 69  oken by definiti
2c810 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  on.  The [SQLITE
2c820 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54 5d  _OMIT_AUTORESET]
2c830 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
2c840 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75  tion.** can be u
2c850 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20 74  sed to restore t
2c860 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
2c870 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f  or..**.** <b>Goo
2c880 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65  fy Interface Ale
2c890 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c  rt:</b> In the l
2c8a0 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
2c8b0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65   the sqlite3_ste
2c8c0 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79  p().** API alway
2c8d0 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65  s returns a gene
2c8e0 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20  ric error code, 
2c8f0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
2c900 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a  following any.**
2c910 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61   error other tha
2c920 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
2c930 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  and [SQLITE_MISU
2c940 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63  SE].  You must c
2c950 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  all.** [sqlite3_
2c960 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
2c970 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2c980 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e   in order to fin
2c990 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  d one of the.** 
2c9a0 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
2c9b0 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74  codes] that bett
2c9c0 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65  er describes the
2c9d0 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64   error..** We ad
2c9e0 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73  mit that this is
2c9f0 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e   a goofy design.
2ca00 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61    The problem ha
2ca10 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20  s been fixed.** 
2ca20 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  with the "v2" in
2ca30 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75  terface.  If you
2ca40 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20   prepare all of 
2ca50 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65  your SQL stateme
2ca60 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74  nts.** using eit
2ca70 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  her [sqlite3_pre
2ca80 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
2ca90 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2caa0 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a  _v2()] instead.*
2cab0 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20  * of the legacy 
2cac0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2cad0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2cae0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e  _prepare16()] in
2caf0 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65  terfaces,.** the
2cb00 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69  n the more speci
2cb10 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  fic [error codes
2cb20 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 64  ] are returned d
2cb30 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71  irectly.** by sq
2cb40 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54  lite3_step().  T
2cb50 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22 76  he use of the "v
2cb60 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  2" interface is 
2cb70 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a  recommended..*/.
2cb80 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70  int sqlite3_step
2cb90 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
2cba0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2cbb0 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  : Number of colu
2cbc0 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20  mns in a result 
2cbd0 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  set.**.** ^The s
2cbe0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
2cbf0 74 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72  t(P) interface r
2cc00 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
2cc10 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
2cc20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72  the.** current r
2cc30 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ow of the result
2cc40 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65   set of [prepare
2cc50 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a  d statement] P..
2cc60 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64 20  ** ^If prepared 
2cc70 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73  statement P does
2cc80 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74   not have result
2cc90 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 72  s ready to retur
2cca0 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20  n.** (via calls 
2ccb0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
2ccc0 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c  column_int | sql
2ccd0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d  ite3_column_*()]
2cce0 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65   of.** interface
2ccf0 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  s) then sqlite3_
2cd00 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65  data_count(P) re
2cd10 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65  turns 0..** ^The
2cd20 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
2cd30 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 61  unt(P) routine a
2cd40 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66  lso returns 0 if
2cd50 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   P is a NULL poi
2cd60 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  nter..** ^The sq
2cd70 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2cd80 28 50 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  (P) routine retu
2cd90 72 6e 73 20 30 20 69 66 20 74 68 65 20 70 72 65  rns 0 if the pre
2cda0 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a  vious call to.**
2cdb0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28   [sqlite3_step](
2cdc0 50 29 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  P) returned [SQL
2cdd0 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65  ITE_DONE].  ^The
2cde0 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
2cdf0 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72  unt(P).** will r
2ce00 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69  eturn non-zero i
2ce10 66 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  f previous call 
2ce20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
2ce30 5d 28 50 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ](P) returned.**
2ce40 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65   [SQLITE_ROW], e
2ce50 78 63 65 70 74 20 69 6e 20 74 68 65 20 63 61 73  xcept in the cas
2ce60 65 20 6f 66 20 74 68 65 20 5b 50 52 41 47 4d 41  e of the [PRAGMA
2ce70 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63   incremental_vac
2ce80 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74  uum].** where it
2ce90 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
2cea0 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 63 68 20  zero since each 
2ceb0 73 74 65 70 20 6f 66 20 74 68 61 74 20 6d 75 6c  step of that mul
2cec0 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d  ti-step.** pragm
2ced0 61 20 72 65 74 75 72 6e 73 20 30 20 63 6f 6c 75  a returns 0 colu
2cee0 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a  mns of data..**.
2cef0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
2cf00 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
2cf10 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  nt()].*/.int sql
2cf20 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
2cf30 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2cf40 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2cf50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74  I3REF: Fundament
2cf60 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20  al Datatypes.** 
2cf70 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45  KEYWORDS: SQLITE
2cf80 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76  _TEXT.**.** ^(Ev
2cf90 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c  ery value in SQL
2cfa0 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66  ite has one of f
2cfb0 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20  ive fundamental 
2cfc0 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a  datatypes:.**.**
2cfd0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34   <ul>.** <li> 64
2cfe0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
2cff0 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62  ger.** <li> 64-b
2d000 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67  it IEEE floating
2d010 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a   point number.**
2d020 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20   <li> string.** 
2d030 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69  <li> BLOB.** <li
2d040 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29  > NULL.** </ul>)
2d050 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  ^.**.** These co
2d060 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65  nstants are code
2d070 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68  s for each of th
2d080 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a  ose types..**.**
2d090 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53   Note that the S
2d0a0 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74  QLITE_TEXT const
2d0b0 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65  ant was also use
2d0c0 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73  d in SQLite vers
2d0d0 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63  ion 2.** for a c
2d0e0 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72  ompletely differ
2d0f0 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f  ent meaning.  So
2d100 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b  ftware that link
2d110 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a  s against both.*
2d120 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  * SQLite version
2d130 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65   2 and SQLite ve
2d140 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75  rsion 3 should u
2d150 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c  se SQLITE3_TEXT,
2d160 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54   not.** SQLITE_T
2d170 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  EXT..*/.#define 
2d180 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20  SQLITE_INTEGER  
2d190 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
2d1a0 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66  _FLOAT    2.#def
2d1b0 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20  ine SQLITE_BLOB 
2d1c0 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
2d1d0 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a  LITE_NULL     5.
2d1e0 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45  #ifdef SQLITE_TE
2d1f0 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54  XT.# undef SQLIT
2d200 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64  E_TEXT.#else.# d
2d210 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58  efine SQLITE_TEX
2d220 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23  T     3.#endif.#
2d230 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54  define SQLITE3_T
2d240 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a  EXT     3../*.**
2d250 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c   CAPI3REF: Resul
2d260 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20  t Values From A 
2d270 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44  Query.** KEYWORD
2d280 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  S: {column acces
2d290 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a  s functions}.**.
2d2a0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
2d2b0 73 20 66 6f 72 6d 20 74 68 65 20 22 72 65 73 75  s form the "resu
2d2c0 6c 74 20 73 65 74 22 20 69 6e 74 65 72 66 61 63  lt set" interfac
2d2d0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  e..**.** ^These 
2d2e0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
2d2f0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
2d300 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d  t a single colum
2d310 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  n of the current
2d320 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f  .** result row o
2d330 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20  f a query.  ^In 
2d340 65 76 65 72 79 20 63 61 73 65 20 74 68 65 20 66  every case the f
2d350 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
2d360 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
2d370 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2d380 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69  tatement] that i
2d390 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65  s being evaluate
2d3a0 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d (the [sqlite3_
2d3b0 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77  stmt*].** that w
2d3c0 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  as returned from
2d3d0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2d3e0 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f  e_v2()] or one o
2d3f0 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a  f its variants).
2d400 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  ** and the secon
2d410 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
2d420 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63  e index of the c
2d430 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20  olumn for which 
2d440 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73  information.** s
2d450 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
2d460 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  d. ^The leftmost
2d470 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
2d480 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 68  esult set has th
2d490 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54  e index 0..** ^T
2d4a0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
2d4b0 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
2d4c0 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d  lt can be determ
2d4d0 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ined using.** [s
2d4e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
2d4f0 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  unt()]..**.** If
2d500 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
2d510 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72  nt does not curr
2d520 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61  ently point to a
2d530 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69   valid row, or i
2d540 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  f the.** column 
2d550 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20  index is out of 
2d560 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c  range, the resul
2d570 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  t is undefined..
2d580 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
2d590 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61  s may only be ca
2d5a0 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f  lled when the mo
2d5b0 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
2d5c0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  o.** [sqlite3_st
2d5d0 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e  ep()] has return
2d5e0 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  ed [SQLITE_ROW] 
2d5f0 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b  and neither.** [
2d600 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2d610 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69   nor [sqlite3_fi
2d620 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62  nalize()] have b
2d630 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65  een called subse
2d640 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61  quently..** If a
2d650 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
2d660 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
2d670 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72  after [sqlite3_r
2d680 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
2d690 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2d6a0 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c  )] or after [sql
2d6b0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
2d6c0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d   returned.** som
2d6d0 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61  ething other tha
2d6e0 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  n [SQLITE_ROW], 
2d6f0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
2d700 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66  undefined..** If
2d710 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2d720 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
2d730 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
2d740 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a  e3_finalize()].*
2d750 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f  * are called fro
2d760 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68  m a different th
2d770 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f  read while any o
2d780 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
2d790 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c  .** are pending,
2d7a0 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
2d7b0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
2d7c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2d7d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
2d7e0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
2d7f0 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  s the.** [SQLITE
2d800 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74  _INTEGER | datat
2d810 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68  ype code] for th
2d820 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74  e initial data t
2d830 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65  ype.** of the re
2d840 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54  sult column.  ^T
2d850 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75  he returned valu
2d860 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  e is one of [SQL
2d870 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a  ITE_INTEGER],.**
2d880 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c   [SQLITE_FLOAT],
2d890 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20   [SQLITE_TEXT], 
2d8a0 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f  [SQLITE_BLOB], o
2d8b0 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e  r [SQLITE_NULL].
2d8c0 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72    The value.** r
2d8d0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
2d8e0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
2d8f0 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67   is only meaning
2d900 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a  ful if no type.*
2d910 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61  * conversions ha
2d920 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20 64  ve occurred as d
2d930 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20  escribed below. 
2d940 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63 6f   After a type co
2d950 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65  nversion,.** the
2d960 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
2d970 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
2d980 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64 65  n_type() is unde
2d990 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a  fined.  Future.*
2d9a0 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  * versions of SQ
2d9b0 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20  Lite may change 
2d9c0 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
2d9d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2d9e0 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  ype().** followi
2d9f0 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  ng a type conver
2da00 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  sion..**.** ^If 
2da10 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
2da20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74  BLOB or UTF-8 st
2da30 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71  ring then the sq
2da40 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2da50 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  es().** routine 
2da60 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
2da70 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
2da80 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  hat BLOB or stri
2da90 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
2daa0 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31  esult is a UTF-1
2dab0 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73  6 string, then s
2dac0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2dad0 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a  tes() converts.*
2dae0 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20  * the string to 
2daf0 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72  UTF-8 and then r
2db00 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
2db10 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  r of bytes..** ^
2db20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2db30 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65   a numeric value
2db40 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
2db50 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65  lumn_bytes() use
2db60 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e  s.** [sqlite3_sn
2db70 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e  printf()] to con
2db80 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20  vert that value 
2db90 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  to a UTF-8 strin
2dba0 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a  g and returns.**
2dbb0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2dbc0 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72  ytes in that str
2dbd0 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
2dbe0 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20  result is NULL, 
2dbf0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2dc00 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75  umn_bytes() retu
2dc10 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20  rns zero..**.** 
2dc20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2dc30 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d  s a BLOB or UTF-
2dc40 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74  16 string then t
2dc50 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
2dc60 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72  n_bytes16().** r
2dc70 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
2dc80 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2dc90 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20  es in that BLOB 
2dca0 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  or string..** ^I
2dcb0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2dcc0 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20  a UTF-8 string, 
2dcd0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2dce0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f  umn_bytes16() co
2dcf0 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74  nverts.** the st
2dd00 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61  ring to UTF-16 a
2dd10 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20  nd then returns 
2dd20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2dd30 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  tes..** ^If the 
2dd40 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65  result is a nume
2dd50 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73  ric value then s
2dd60 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2dd70 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20  tes16() uses.** 
2dd80 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
2dd90 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20  f()] to convert 
2dda0 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20  that value to a 
2ddb0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e  UTF-16 string an
2ddc0 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  d returns.** the
2ddd0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2dde0 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e   in that string.
2ddf0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2de00 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  lt is NULL, then
2de10 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2de20 62 79 74 65 73 31 36 28 29 20 72 65 74 75 72 6e  bytes16() return
2de30 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s zero..**.** ^T
2de40 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
2de50 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
2de60 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61  olumn_bytes()] a
2de70 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nd .** [sqlite3_
2de80 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2de90 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65  ] do not include
2dea0 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
2deb0 61 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64  ators at the end
2dec0 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e  .** of the strin
2ded0 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79  g.  ^For clarity
2dee0 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72 65 74  : the values ret
2def0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
2df00 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2df10 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  s()] and [sqlite
2df20 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2df30 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62  ()] are the numb
2df40 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69  er of.** bytes i
2df50 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f  n the string, no
2df60 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
2df70 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a  characters..**.*
2df80 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72  * ^Strings retur
2df90 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
2dfa0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64  olumn_text() and
2dfb0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2dfc0 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65  text16(),.** eve
2dfd0 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c  n empty strings,
2dfe0 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f   are always zero
2dff0 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54  -terminated.  ^T
2e000 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c  he return.** val
2e010 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
2e020 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f  column_blob() fo
2e030 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  r a zero-length 
2e040 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70  BLOB is a NULL p
2e050 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
2e060 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  he object return
2e070 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
2e080 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
2e090 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65  s an.** [unprote
2e0a0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2e0b0 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20  ue] object.  An 
2e0c0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2e0d0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2e0e0 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  .** may only be 
2e0f0 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74  used with [sqlit
2e100 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d  e3_bind_value()]
2e110 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
2e120 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a  sult_value()]..*
2e130 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74  * If the [unprot
2e140 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2e150 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75  lue] object retu
2e160 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
2e170 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
2e180 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61  ()] is used in a
2e190 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e  ny other way, in
2e1a0 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a  cluding calls.**
2e1b0 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b   to routines lik
2e1c0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2e1d0 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65  _int()], [sqlite
2e1e0 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
2e1f0 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
2e200 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20  value_bytes()], 
2e210 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
2e220 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
2e230 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
2e240 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20  ines attempt to 
2e250 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75  convert the valu
2e260 65 20 77 68 65 72 65 20 61 70 70 72 6f 70 72 69  e where appropri
2e270 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78  ate.  ^For.** ex
2e280 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e  ample, if the in
2e290 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74  ternal represent
2e2a0 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61  ation is FLOAT a
2e2b0 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c 74  nd a text result
2e2c0 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65 64  .** is requested
2e2d0 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  , [sqlite3_snpri
2e2e0 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20 69  ntf()] is used i
2e2f0 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72  nternally to per
2e300 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76  form the.** conv
2e310 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63  ersion automatic
2e320 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c  ally.  ^(The fol
2e330 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74  lowing table det
2e340 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73  ails the convers
2e350 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ions.** that are
2e360 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20   applied:.**.** 
2e370 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20  <blockquote>.** 
2e380 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31  <table border="1
2e390 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49  ">.** <tr><th> I
2e3a0 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20  nternal<br>Type 
2e3b0 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62  <th> Requested<b
2e3c0 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e  r>Type <th>  Con
2e3d0 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74  version.**.** <t
2e3e0 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
2e3f0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
2e400 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a  td> Result is 0.
2e410 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
2e420 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  L    <td>  FLOAT
2e430 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
2e440 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74  is 0.0.** <tr><t
2e450 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
2e460 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
2e470 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c  Result is a NULL
2e480 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e   pointer.** <tr>
2e490 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
2e4a0 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
2e4b0 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55  > Result is a NU
2e4c0 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74  LL pointer.** <t
2e4d0 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
2e4e0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
2e4f0 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d  td> Convert from
2e500 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61   integer to floa
2e510 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  t.** <tr><td> IN
2e520 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45  TEGER  <td>   TE
2e530 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49  XT    <td> ASCII
2e540 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
2e550 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72  e integer.** <tr
2e560 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
2e570 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
2e580 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47  d> Same as INTEG
2e590 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e  ER->TEXT.** <tr>
2e5a0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
2e5b0 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
2e5c0 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45  > [CAST] to INTE
2e5d0 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  GER.** <tr><td> 
2e5e0 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20   FLOAT   <td>   
2e5f0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43  TEXT    <td> ASC
2e600 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  II rendering of 
2e610 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72  the float.** <tr
2e620 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
2e630 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
2e640 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 42 4c 4f  d> [CAST] to BLO
2e650 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  B.** <tr><td>  T
2e660 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  EXT    <td> INTE
2e670 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  GER   <td> [CAST
2e680 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20  ] to INTEGER.** 
2e690 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
2e6a0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
2e6b0 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
2e6c0 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  REAL.** <tr><td>
2e6d0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20    TEXT    <td>  
2e6e0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f   BLOB    <td> No
2e6f0 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c   change.** <tr><
2e700 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
2e710 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
2e720 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47   [CAST] to INTEG
2e730 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ER.** <tr><td>  
2e740 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c  BLOB    <td>  FL
2e750 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53  OAT    <td> [CAS
2e760 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74  T] to REAL.** <t
2e770 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
2e780 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
2e790 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74  td> Add a zero t
2e7a0 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65  erminator if nee
2e7b0 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a  ded.** </table>.
2e7c0 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  ** </blockquote>
2e7d0 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62  )^.**.** The tab
2e7e0 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72  le above makes r
2e7f0 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61 6e  eference to stan
2e800 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 20 66  dard C library f
2e810 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a  unctions atoi().
2e820 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20  ** and atof().  
2e830 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20  SQLite does not 
2e840 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73 65  really use these
2e850 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20   functions.  It 
2e860 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65  has its.** own e
2e870 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e  quivalent intern
2e880 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 68  al routines.  Th
2e890 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74 6f  e atoi() and ato
2e8a0 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a  f() names are.**
2e8b0 20 75 73 65 64 20 69 6e 20 74 68 65 20 74 61 62   used in the tab
2e8c0 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79 20 61  le for brevity a
2e8d0 6e 64 20 62 65 63 61 75 73 65 20 74 68 65 79 20  nd because they 
2e8e0 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f 20  are familiar to 
2e8f0 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61  most.** C progra
2e900 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  mmers..**.** Not
2e910 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70 65  e that when type
2e920 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63   conversions occ
2e930 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74  ur, pointers ret
2e940 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a  urned by prior.*
2e950 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  * calls to sqlit
2e960 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
2e970 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  , sqlite3_column
2e980 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a  _text(), and/or.
2e990 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
2e9a0 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20 62  n_text16() may b
2e9b0 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a  e invalidated..*
2e9c0 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  * Type conversio
2e9d0 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69  ns and pointer i
2e9e0 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67  nvalidations mig
2e9f0 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74  ht occur.** in t
2ea00 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73  he following cas
2ea10 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
2ea20 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
2ea30 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20  al content is a 
2ea40 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33  BLOB and sqlite3
2ea50 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f  _column_text() o
2ea60 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
2ea70 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2ea80 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20  ) is called.  A 
2ea90 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20  zero-terminator 
2eaa0 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65  might.**      ne
2eab0 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 74  ed to be added t
2eac0 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c  o the string.</l
2ead0 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  i>.** <li> The i
2eae0 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
2eaf0 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64  s UTF-8 text and
2eb00 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2eb10 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20  bytes16() or.** 
2eb20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
2eb30 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20  umn_text16() is 
2eb40 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e  called.  The con
2eb50 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e  tent must be con
2eb60 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74  verted.**      t
2eb70 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a  o UTF-16.</li>.*
2eb80 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
2eb90 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54  al content is UT
2eba0 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73 71  F-16 text and sq
2ebb0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2ebc0 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  es() or.**      
2ebd0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2ebe0 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  ext() is called.
2ebf0 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75    The content mu
2ec00 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a  st be converted.
2ec10 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38  **      to UTF-8
2ec20 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  .</li>.** </ul>.
2ec30 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f  **.** ^Conversio
2ec40 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31  ns between UTF-1
2ec50 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65  6be and UTF-16le
2ec60 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65   are always done
2ec70 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f   in place and do
2ec80 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61  .** not invalida
2ec90 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74  te a prior point
2eca0 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f  er, though of co
2ecb0 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74  urse the content
2ecc0 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a   of the buffer.*
2ecd0 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f 72  * that the prior
2ece0 20 70 6f 69 6e 74 65 72 20 72 65 66 65 72 65 6e   pointer referen
2ecf0 63 65 73 20 77 69 6c 6c 20 68 61 76 65 20 62 65  ces will have be
2ed00 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74  en modified.  Ot
2ed10 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20  her kinds.** of 
2ed20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64  conversion are d
2ed30 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65  one in place whe
2ed40 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65  n it is possible
2ed50 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20  , but sometimes 
2ed60 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  they.** are not 
2ed70 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20  possible and in 
2ed80 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f  those cases prio
2ed90 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69  r pointers are i
2eda0 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a  nvalidated..**.*
2edb0 2a 20 54 68 65 20 73 61 66 65 73 74 20 61 6e 64  * The safest and
2edc0 20 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d 65   easiest to reme
2edd0 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20 74  mber policy is t
2ede0 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72  o invoke these r
2edf0 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e  outines.** in on
2ee00 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
2ee10 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ng ways:.**.** <
2ee20 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  ul>.**  <li>sqli
2ee30 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2ee40 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
2ee50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2ee60 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c  es()</li>.**  <l
2ee70 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
2ee80 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64  _blob() followed
2ee90 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
2eea0 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a  mn_bytes()</li>.
2eeb0 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
2eec0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
2eed0 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
2eee0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2eef0 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75  16()</li>.** </u
2ef00 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65  l>.**.** In othe
2ef10 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f  r words, you sho
2ef20 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  uld call sqlite3
2ef30 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a  _column_text(),.
2ef40 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
2ef50 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c  n_blob(), or sql
2ef60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2ef70 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f  16() first to fo
2ef80 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a  rce the result.*
2ef90 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72  * into the desir
2efa0 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20  ed format, then 
2efb0 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63  invoke sqlite3_c
2efc0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72  olumn_bytes() or
2efd0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
2efe0 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20  mn_bytes16() to 
2eff0 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66  find the size of
2f000 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f   the result.  Do
2f010 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a   not mix calls.*
2f020 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  * to sqlite3_col
2f030 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71  umn_text() or sq
2f040 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
2f050 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74  b() with calls t
2f060 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  o.** sqlite3_col
2f070 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61  umn_bytes16(), a
2f080 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61  nd do not mix ca
2f090 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
2f0a0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a  olumn_text16().*
2f0b0 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20  * with calls to 
2f0c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2f0d0 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ytes()..**.** ^T
2f0e0 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  he pointers retu
2f0f0 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75  rned are valid u
2f100 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76  ntil a type conv
2f110 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73  ersion occurs as
2f120 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62  .** described ab
2f130 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73  ove, or until [s
2f140 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
2f150 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
2f160 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
2f170 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69  e3_finalize()] i
2f180 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20  s called.  ^The 
2f190 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65  memory space use
2f1a0 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67  d to hold string
2f1b0 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69  s.** and BLOBs i
2f1c0 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69  s freed automati
2f1d0 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f  cally.  Do <b>no
2f1e0 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70  t</b> pass the p
2f1f0 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
2f200 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
2f210 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d  3_column_blob()]
2f220 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  , [sqlite3_colum
2f230 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20  n_text()], etc. 
2f240 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  into.** [sqlite3
2f250 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _free()]..**.** 
2f260 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  ^(If a memory al
2f270 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f  location error o
2f280 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65  ccurs during the
2f290 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61   evaluation of a
2f2a0 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72  ny.** of these r
2f2b0 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75  outines, a defau
2f2c0 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75  lt value is retu
2f2d0 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75  rned.  The defau
2f2e0 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65  lt value.** is e
2f2f0 69 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65  ither the intege
2f300 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e  r 0, the floatin
2f310 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30  g point number 0
2f320 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a  .0, or a NULL.**
2f330 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65   pointer.  Subse
2f340 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b  quent calls to [
2f350 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
2f360 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a  )] will return.*
2f370 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  * [SQLITE_NOMEM]
2f380 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69  .)^.*/.const voi
2f390 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2f3a0 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  n_blob(sqlite3_s
2f3b0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2f3c0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
2f3d0 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65  umn_bytes(sqlite
2f3e0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2f3f0 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
2f400 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73  column_bytes16(s
2f410 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2f420 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20  t iCol);.double 
2f430 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
2f440 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  ouble(sqlite3_st
2f450 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2f460 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
2f470 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  mn_int(sqlite3_s
2f480 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2f490 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
2f4a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
2f4b0 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t64(sqlite3_stmt
2f4c0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f  *, int iCol);.co
2f4d0 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61  nst unsigned cha
2f4e0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
2f4f0 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73  n_text(sqlite3_s
2f500 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2f510 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
2f520 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2f530 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2f540 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
2f550 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f560 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  type(sqlite3_stm
2f570 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73  t*, int iCol);.s
2f580 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71  qlite3_value *sq
2f590 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
2f5a0 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ue(sqlite3_stmt*
2f5b0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a  , int iCol);../*
2f5c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
2f5d0 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64  stroy A Prepared
2f5e0 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
2f5f0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
2f600 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
2f610 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c  function is call
2f620 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b  ed to delete a [
2f630 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2f640 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  nt]..** ^If the 
2f650 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c  most recent eval
2f660 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74  uation of the st
2f670 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65  atement encounte
2f680 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a  red no errors.**
2f690 20 6f 72 20 69 66 20 74 68 65 20 73 74 61 74 65   or if the state
2f6a0 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62 65  ment is never be
2f6b0 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74 68  en evaluated, th
2f6c0 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  en sqlite3_final
2f6d0 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a  ize() returns.**
2f6e0 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66   SQLITE_OK.  ^If
2f6f0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
2f700 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73   evaluation of s
2f710 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c 65  tatement S faile
2f720 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  d, then.** sqlit
2f730 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72  e3_finalize(S) r
2f740 65 74 75 72 6e 73 20 74 68 65 20 61 70 70 72 6f  eturns the appro
2f750 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f  priate [error co
2f760 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e  de] or.** [exten
2f770 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e  ded error code].
2f780 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2f790 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20  te3_finalize(S) 
2f7a0 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63  routine can be c
2f7b0 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69  alled at any poi
2f7c0 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65  nt during.** the
2f7d0 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20 5b   life cycle of [
2f7e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2f7f0 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65  nt] S:.** before
2f800 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73 20   statement S is 
2f810 65 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c 20  ever evaluated, 
2f820 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20  after.** one or 
2f830 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73  more calls to [s
2f840 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c  qlite3_reset()],
2f850 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63 61   or after any ca
2f860 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65  ll.** to [sqlite
2f870 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72 64  3_step()] regard
2f880 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
2f890 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74 65  or not the state
2f8a0 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70  ment has.** comp
2f8b0 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e 2e  leted execution.
2f8c0 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67  .**.** ^Invoking
2f8d0 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
2f8e0 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f  e() on a NULL po
2f8f0 69 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d 6c  inter is a harml
2f900 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a  ess no-op..**.**
2f910 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
2f920 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20 65   must finalize e
2f930 76 65 72 79 20 5b 70 72 65 70 61 72 65 64 20 73  very [prepared s
2f940 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64  tatement] in ord
2f950 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72  er to avoid.** r
2f960 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20 20  esource leaks.  
2f970 49 74 20 69 73 20 61 20 67 72 69 65 76 6f 75 73  It is a grievous
2f980 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20 61   error for the a
2f990 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74 72  pplication to tr
2f9a0 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72  y to use.** a pr
2f9b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2f9c0 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65   after it has be
2f9d0 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41  en finalized.  A
2f9e0 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72 65 70  ny use of a prep
2f9f0 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  ared.** statemen
2fa00 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  t after it has b
2fa10 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63 61  een finalized ca
2fa20 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65  n result in unde
2fa30 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64  fined and.** und
2fa40 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f  esirable behavio
2fa50 72 20 73 75 63 68 20 61 73 20 73 65 67 66 61 75  r such as segfau
2fa60 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f 72  lts and heap cor
2fa70 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20  ruption..*/.int 
2fa80 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2fa90 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
2faa0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
2fab0 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20  PI3REF: Reset A 
2fac0 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
2fad0 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  nt Object.**.** 
2fae0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65  The sqlite3_rese
2faf0 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  t() function is 
2fb00 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20  called to reset 
2fb10 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2fb20 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74  ement].** object
2fb30 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69   back to its ini
2fb40 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64  tial state, read
2fb50 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75  y to be re-execu
2fb60 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c  ted..** ^Any SQL
2fb70 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61   statement varia
2fb80 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61  bles that had va
2fb90 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68  lues bound to th
2fba0 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20  em using.** the 
2fbb0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2fbc0 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e  ob | sqlite3_bin
2fbd0 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69  d_*() API] retai
2fbe0 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a  n their values..
2fbf0 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f  ** Use [sqlite3_
2fc00 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29  clear_bindings()
2fc10 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62  ] to reset the b
2fc20 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e  indings..**.** ^
2fc30 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
2fc40 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  et(S)] interface
2fc50 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 65   resets the [pre
2fc60 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2fc70 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68   S.** back to th
2fc80 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69  e beginning of i
2fc90 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a  ts program..**.*
2fca0 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
2fcb0 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
2fcc0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
2fcd0 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  for the.** [prep
2fce0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2fcf0 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  S returned [SQLI
2fd00 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49  TE_ROW] or [SQLI
2fd10 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20  TE_DONE],.** or 
2fd20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  if [sqlite3_step
2fd30 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62  (S)] has never b
2fd40 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65  efore been calle
2fd50 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20  d on S,.** then 
2fd60 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
2fd70 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  )] returns [SQLI
2fd80 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49  TE_OK]..**.** ^I
2fd90 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
2fda0 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
2fdb0 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20  e3_step(S)] for 
2fdc0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
2fdd0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e   statement] S in
2fde0 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72  dicated an error
2fdf0 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74  , then.** [sqlit
2fe00 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74  e3_reset(S)] ret
2fe10 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69  urns an appropri
2fe20 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ate [error code]
2fe30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ..**.** ^The [sq
2fe40 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
2fe50 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e  interface does n
2fe60 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61  ot change the va
2fe70 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b  lues.** of any [
2fe80 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2fe90 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74  b|bindings] on t
2fea0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2feb0 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e  tement] S..*/.in
2fec0 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28  t sqlite3_reset(
2fed0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2fee0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2fef0 49 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72  I3REF: Create Or
2ff00 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75   Redefine SQL Fu
2ff10 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f  nctions.** KEYWO
2ff20 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63  RDS: {function c
2ff30 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  reation routines
2ff40 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
2ff50 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2ff60 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
2ff70 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
2ff80 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2ff90 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
2ffa0 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  s}.**.** ^These 
2ffb0 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65  functions (colle
2ffc0 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73  ctively known as
2ffd0 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74   "function creat
2ffe0 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a  ion routines").*
2fff0 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64  * are used to ad
30000 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  d SQL functions 
30010 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f 72  or aggregates or
30020 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65   to redefine the
30030 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20   behavior.** of 
30040 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e  existing SQL fun
30050 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67  ctions or aggreg
30060 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20  ates.  The only 
30070 64 69 66 66 65 72 65 6e 63 65 73 20 62 65 74 77  differences betw
30080 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75  een.** these rou
30090 74 69 6e 65 73 20 61 72 65 20 74 68 65 20 74 65  tines are the te
300a0 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 65  xt encoding expe
300b0 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20  cted for.** the 
300c0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
300d0 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68   (the name of th
300e0 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67  e function being
300f0 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64   created).** and
30100 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 72   the presence or
30110 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64 65   absence of a de
30120 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63  structor callbac
30130 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70  k for.** the app
30140 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
30150 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  inter..**.** ^Th
30160 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
30170 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61  r is the [databa
30180 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
30190 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a  o which the SQL.
301a0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ** function is t
301b0 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66  o be added.  ^If
301c0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
301d0 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f  uses more than o
301e0 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  ne database.** c
301f0 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61  onnection then a
30200 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
30210 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
30220 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a   must be added.*
30230 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61  * to each databa
30240 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65  se connection se
30250 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  parately..**.** 
30260 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
30270 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d  meter is the nam
30280 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e  e of the SQL fun
30290 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61  ction to be crea
302a0 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69  ted or.** redefi
302b0 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74  ned.  ^The lengt
302c0 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73  h of the name is
302d0 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20   limited to 255 
302e0 62 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d 38  bytes in a UTF-8
302f0 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74 69  .** representati
30300 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66  on, exclusive of
30310 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   the zero-termin
30320 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61  ator.  ^Note tha
30330 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65  t the name.** le
30340 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e  ngth limit is in
30350 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f   UTF-8 bytes, no
30360 74 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f 72  t characters nor
30370 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20 20   UTF-16 bytes.  
30380 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70 74  .** ^Any attempt
30390 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e   to create a fun
303a0 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e  ction with a lon
303b0 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c  ger name.** will
303c0 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49   result in [SQLI
303d0 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e 67  TE_MISUSE] being
303e0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
303f0 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61   ^The third para
30400 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20  meter (nArg).** 
30410 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
30420 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
30430 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
30440 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
30450 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73   takes. ^If this
30460 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31   parameter is -1
30470 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66  , then the SQL f
30480 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
30490 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65  gregate may take
304a0 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61   any number of a
304b0 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e  rguments between
304c0 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74   0 and the limit
304d0 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69  .** set by [sqli
304e0 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49  te3_limit]([SQLI
304f0 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
30500 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65  N_ARG]).  If the
30510 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65   third.** parame
30520 74 65 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ter is less than
30530 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20 74   -1 or greater t
30540 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65  han 127 then the
30550 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20   behavior is.** 
30560 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
30570 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72   ^The fourth par
30580 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70  ameter, eTextRep
30590 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74  , specifies what
305a0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38  .** [SQLITE_UTF8
305b0 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67   | text encoding
305c0 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74  ] this SQL funct
305d0 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a  ion prefers for.
305e0 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72  ** its parameter
305f0 73 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  s.  The applicat
30600 69 6f 6e 20 73 68 6f 75 6c 64 20 73 65 74 20 74  ion should set t
30610 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  his parameter to
30620 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  .** [SQLITE_UTF1
30630 36 4c 45 5d 20 69 66 20 74 68 65 20 66 75 6e 63  6LE] if the func
30640 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
30650 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a 2a 20  ion invokes .** 
30660 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
30670 65 78 74 31 36 6c 65 28 29 5d 20 6f 6e 20 61 6e  ext16le()] on an
30680 20 69 6e 70 75 74 2c 20 6f 72 20 5b 53 51 4c 49   input, or [SQLI
30690 54 45 5f 55 54 46 31 36 42 45 5d 20 69 66 20 74  TE_UTF16BE] if t
306a0 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
306b0 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b 73 71  tion invokes [sq
306c0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
306d0 31 36 62 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e  16be()] on an in
306e0 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  put, or.** [SQLI
306f0 54 45 5f 55 54 46 31 36 5d 20 69 66 20 5b 73 71  TE_UTF16] if [sq
30700 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
30710 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 6f  16()] is used, o
30720 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 0a  r [SQLITE_UTF8].
30730 2a 2a 20 6f 74 68 65 72 77 69 73 65 2e 20 20 5e  ** otherwise.  ^
30740 54 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e  The same SQL fun
30750 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67  ction may be reg
30760 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65  istered multiple
30770 20 74 69 6d 65 73 20 75 73 69 6e 67 0a 2a 2a 20   times using.** 
30780 64 69 66 66 65 72 65 6e 74 20 70 72 65 66 65 72  different prefer
30790 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
307a0 67 73 2c 20 77 69 74 68 20 64 69 66 66 65 72 65  gs, with differe
307b0 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  nt implementatio
307c0 6e 73 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 65  ns for.** each e
307d0 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57 68 65  ncoding..** ^Whe
307e0 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  n multiple imple
307f0 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
30800 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
30810 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53  are available, S
30820 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69  QLite.** will pi
30830 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20  ck the one that 
30840 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61  involves the lea
30850 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74  st amount of dat
30860 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  a conversion..**
30870 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20  .** ^The fourth 
30880 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 6f 70  parameter may op
30890 74 69 6f 6e 61 6c 6c 79 20 62 65 20 4f 52 65 64  tionally be ORed
308a0 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45   with [SQLITE_DE
308b0 54 45 52 4d 49 4e 49 53 54 49 43 5d 0a 2a 2a 20  TERMINISTIC].** 
308c0 74 6f 20 73 69 67 6e 61 6c 20 74 68 61 74 20 74  to signal that t
308d0 68 65 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c  he function will
308e0 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74   always return t
308f0 68 65 20 73 61 6d 65 20 72 65 73 75 6c 74 20 67  he same result g
30900 69 76 65 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65  iven.** the same
30910 20 69 6e 70 75 74 73 20 77 69 74 68 69 6e 20 61   inputs within a
30920 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74   single SQL stat
30930 65 6d 65 6e 74 2e 20 20 4d 6f 73 74 20 53 51 4c  ement.  Most SQL
30940 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 0a 2a   functions are.*
30950 2a 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e  * deterministic.
30960 20 20 54 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b    The built-in [
30970 72 61 6e 64 6f 6d 28 29 5d 20 53 51 4c 20 66 75  random()] SQL fu
30980 6e 63 74 69 6f 6e 20 69 73 20 61 6e 20 65 78 61  nction is an exa
30990 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a 20 66 75 6e  mple of a.** fun
309a0 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20 6e 6f  ction that is no
309b0 74 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e  t deterministic.
309c0 20 20 54 68 65 20 53 51 4c 69 74 65 20 71 75 65    The SQLite que
309d0 72 79 20 70 6c 61 6e 6e 65 72 20 69 73 20 61 62  ry planner is ab
309e0 6c 65 20 74 6f 0a 2a 2a 20 70 65 72 66 6f 72 6d  le to.** perform
309f0 20 61 64 64 69 74 69 6f 6e 61 6c 20 6f 70 74 69   additional opti
30a00 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e 20 64 65 74  mizations on det
30a10 65 72 6d 69 6e 69 73 74 69 63 20 66 75 6e 63 74  erministic funct
30a20 69 6f 6e 73 2c 20 73 6f 20 75 73 65 0a 2a 2a 20  ions, so use.** 
30a30 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 44  of the [SQLITE_D
30a40 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 20 66 6c  ETERMINISTIC] fl
30a50 61 67 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ag is recommende
30a60 64 20 77 68 65 72 65 20 70 6f 73 73 69 62 6c 65  d where possible
30a70 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69  ..**.** ^(The fi
30a80 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  fth parameter is
30a90 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f   an arbitrary po
30aa0 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c  inter.  The impl
30ab0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
30ac0 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61  e.** function ca
30ad0 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f  n gain access to
30ae0 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73   this pointer us
30af0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65  ing [sqlite3_use
30b00 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a  r_data()].)^.**.
30b10 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20 73  ** ^The sixth, s
30b20 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68 74  eventh and eight
30b30 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46  h parameters, xF
30b40 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78  unc, xStep and x
30b50 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f  Final, are.** po
30b60 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67  inters to C-lang
30b70 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74  uage functions t
30b80 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  hat implement th
30b90 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
30ba0 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20  r.** aggregate. 
30bb0 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75  ^A scalar SQL fu
30bc0 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
30bd0 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  an implementatio
30be0 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a  n of the xFunc.*
30bf0 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b  * callback only;
30c00 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d   NULL pointers m
30c10 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73  ust be passed as
30c20 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20 78   the xStep and x
30c30 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74  Final.** paramet
30c40 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 61  ers. ^An aggrega
30c50 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  te SQL function 
30c60 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c  requires an impl
30c70 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53  ementation of xS
30c80 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61  tep.** and xFina
30c90 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74  l and NULL point
30ca0 65 72 20 6d 75 73 74 20 62 65 20 70 61 73 73 65  er must be passe
30cb0 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f  d for xFunc. ^To
30cc0 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74   delete an exist
30cd0 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  ing.** SQL funct
30ce0 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
30cf0 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e  , pass NULL poin
30d00 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 72  ters for all thr
30d10 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63  ee function.** c
30d20 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20  allbacks..**.** 
30d30 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20 70  ^(If the ninth p
30d40 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
30d50 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
30d60 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20  ion_v2() is not 
30d70 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74  NULL,.** then it
30d80 20 69 73 20 64 65 73 74 72 75 63 74 6f 72 20 66   is destructor f
30d90 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  or the applicati
30da0 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e  on data pointer.
30db0 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75 63   .** The destruc
30dc0 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  tor is invoked w
30dd0 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  hen the function
30de0 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69 74   is deleted, eit
30df0 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20  her by being.** 
30e00 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 68  overloaded or wh
30e10 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
30e20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65  connection close
30e30 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73  s.)^.** ^The des
30e40 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f 20  tructor is also 
30e50 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63  invoked if the c
30e60 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  all to.** sqlite
30e70 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
30e80 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a  n_v2() fails..**
30e90 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74 72   ^When the destr
30ea0 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f  uctor callback o
30eb0 66 20 74 68 65 20 74 65 6e 74 68 20 70 61 72 61  f the tenth para
30ec0 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 64  meter is invoked
30ed0 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 65  , it.** is passe
30ee0 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  d a single argum
30ef0 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 63  ent which is a c
30f00 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c 69  opy of the appli
30f10 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20  cation data .** 
30f20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77 61  pointer which wa
30f30 73 20 74 68 65 20 66 69 66 74 68 20 70 61 72 61  s the fifth para
30f40 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
30f50 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
30f60 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74  _v2()..**.** ^It
30f70 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f   is permitted to
30f80 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70   register multip
30f90 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
30fa0 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a  ns of the same.*
30fb0 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68  * functions with
30fc0 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62   the same name b
30fd0 75 74 20 77 69 74 68 20 65 69 74 68 65 72 20 64  ut with either d
30fe0 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73  iffering numbers
30ff0 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73   of.** arguments
31000 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 72   or differing pr
31010 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
31020 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65  odings.  ^SQLite
31030 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65   will use.** the
31040 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
31050 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c  that most closel
31060 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61  y matches the wa
31070 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a  y in which the.*
31080 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  * SQL function i
31090 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63  s used.  ^A func
310a0 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
310b0 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e  ion with a non-n
310c0 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20  egative.** nArg 
310d0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62  parameter is a b
310e0 65 74 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e  etter match than
310f0 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c   a function impl
31100 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a  ementation with.
31110 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41  ** a negative nA
31120 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e  rg.  ^A function
31130 20 77 68 65 72 65 20 74 68 65 20 70 72 65 66 65   where the prefe
31140 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
31150 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68  ng.** matches th
31160 65 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64  e database encod
31170 69 6e 67 20 69 73 20 61 20 62 65 74 74 65 72 0a  ing is a better.
31180 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  ** match than a 
31190 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
311a0 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64  he encoding is d
311b0 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e  ifferent.  .** ^
311c0 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  A function where
311d0 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69   the encoding di
311e0 66 66 65 72 65 6e 63 65 20 69 73 20 62 65 74 77  fference is betw
311f0 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20  een UTF16le and 
31200 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20  UTF16be.** is a 
31210 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61  closer match tha
31220 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  n a function whe
31230 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
31240 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a  difference is.**
31250 20 62 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e   between UTF8 an
31260 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e  d UTF16..**.** ^
31270 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f  Built-in functio
31280 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f  ns may be overlo
31290 61 64 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c  aded by new appl
312a0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
312b0 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  functions..**.**
312c0 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e   ^An application
312d0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
312e0 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74  n is permitted t
312f0 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20  o call other.** 
31300 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
31310 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63  s.  However, suc
31320 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74  h calls must not
31330 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61  .** close the da
31340 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
31350 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f  n nor finalize o
31360 72 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70  r reset the prep
31370 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  ared.** statemen
31380 74 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 66  t in which the f
31390 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
313a0 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ng..*/.int sqlit
313b0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
313c0 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  on(.  sqlite3 *d
313d0 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  b,.  const char 
313e0 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
313f0 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
31400 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
31410 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64  id *pApp,.  void
31420 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65   (*xFunc)(sqlite
31430 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
31440 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
31450 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
31460 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
31470 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
31480 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
31490 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33  *xFinal)(sqlite3
314a0 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e  _context*).);.in
314b0 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
314c0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73  _function16(.  s
314d0 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
314e0 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74  nst void *zFunct
314f0 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
31500 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
31510 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
31520 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
31530 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
31540 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
31550 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
31560 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
31570 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
31580 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
31590 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
315a0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
315b0 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  t*).);.int sqlit
315c0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
315d0 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  on_v2(.  sqlite3
315e0 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68   *db,.  const ch
315f0 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  ar *zFunctionNam
31600 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
31610 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
31620 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76   void *pApp,.  v
31630 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c  oid (*xFunc)(sql
31640 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
31650 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
31660 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74  *),.  void (*xSt
31670 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ep)(sqlite3_cont
31680 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
31690 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
316a0 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69  d (*xFinal)(sqli
316b0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20  te3_context*),. 
316c0 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29   void(*xDestroy)
316d0 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a  (void*).);../*.*
316e0 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74  * CAPI3REF: Text
316f0 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a   Encodings.**.**
31700 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20   These constant 
31710 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63  define integer c
31720 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73  odes that repres
31730 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a  ent the various.
31740 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ** text encoding
31750 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53  s supported by S
31760 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  QLite..*/.#defin
31770 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20  e SQLITE_UTF8   
31780 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
31790 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45  e SQLITE_UTF16LE
317a0 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
317b0 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45  e SQLITE_UTF16BE
317c0 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
317d0 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20  e SQLITE_UTF16  
317e0 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20          4    /* 
317f0 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  Use native byte 
31800 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65  order */.#define
31810 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20   SQLITE_ANY     
31820 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 44         5    /* D
31830 65 70 72 65 63 61 74 65 64 20 2a 2f 0a 23 64 65  eprecated */.#de
31840 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
31850 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20  6_ALIGNED  8    
31860 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  /* sqlite3_creat
31870 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79  e_collation only
31880 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
31890 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 46 6c  REF: Function Fl
318a0 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ags.**.** These 
318b0 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20 62 65  constants may be
318c0 20 4f 52 65 64 20 74 6f 67 65 74 68 65 72 20 77   ORed together w
318d0 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ith the .** [SQL
318e0 49 54 45 5f 55 54 46 38 20 7c 20 70 72 65 66 65  ITE_UTF8 | prefe
318f0 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
31900 6e 67 5d 20 61 73 20 74 68 65 20 66 6f 75 72 74  ng] as the fourt
31910 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  h argument.** to
31920 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
31930 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 5b 73  _function()], [s
31940 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
31950 6e 63 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a  nction16()], or.
31960 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ** [sqlite3_crea
31970 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29  te_function_v2()
31980 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ]..*/.#define SQ
31990 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54  LITE_DETERMINIST
319a0 49 43 20 20 20 20 30 78 38 30 30 0a 0a 2f 2a 0a  IC    0x800../*.
319b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 70  ** CAPI3REF: Dep
319c0 72 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f 6e  recated Function
319d0 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a  s.** DEPRECATED.
319e0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63  **.** These func
319f0 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 65  tions are [depre
31a00 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65  cated].  In orde
31a10 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a  r to maintain.**
31a20 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
31a30 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c  tibility with ol
31a40 64 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65 20  der code, these 
31a50 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e  functions contin
31a60 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70  ue .** to be sup
31a70 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65 72  ported.  However
31a80 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  , new applicatio
31a90 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a  ns should avoid.
31aa0 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74 68  ** the use of th
31ab0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  ese functions.  
31ac0 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 61 67  To help encourag
31ad0 65 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69  e people to avoi
31ae0 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 73 65  d.** using these
31af0 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61   functions, we a
31b00 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20  re not going to 
31b10 74 65 6c 6c 20 79 6f 75 20 77 68 61 74 20 74 68  tell you what th
31b20 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65  ey do..*/.#ifnde
31b30 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45  f SQLITE_OMIT_DE
31b40 50 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45 5f  PRECATED.SQLITE_
31b50 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
31b60 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
31b70 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63  _count(sqlite3_c
31b80 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45  ontext*);.SQLITE
31b90 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
31ba0 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28  sqlite3_expired(
31bb0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
31bc0 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
31bd0 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72  D int sqlite3_tr
31be0 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28  ansfer_bindings(
31bf0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73  sqlite3_stmt*, s
31c00 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53  qlite3_stmt*);.S
31c10 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
31c20 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f   int sqlite3_glo
31c30 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64  bal_recover(void
31c40 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
31c50 41 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74 65  ATED void sqlite
31c60 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70  3_thread_cleanup
31c70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44  (void);.SQLITE_D
31c80 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
31c90 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61  lite3_memory_ala
31ca0 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  rm(void(*)(void*
31cb0 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69  ,sqlite3_int64,i
31cc0 6e 74 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20  nt),.           
31cd0 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 2a             void*
31ce0 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b  ,sqlite3_int64);
31cf0 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43  .#endif../*.** C
31d00 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69  API3REF: Obtaini
31d10 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20  ng SQL Function 
31d20 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73  Parameter Values
31d30 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e  .**.** The C-lan
31d40 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61  guage implementa
31d50 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63  tion of SQL func
31d60 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
31d70 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69  ates uses.** thi
31d80 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61  s set of interfa
31d90 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61  ce routines to a
31da0 63 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65  ccess the parame
31db0 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a  ter values on.**
31dc0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72   the function or
31dd0 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a   aggregate..**.*
31de0 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72  * The xFunc (for
31df0 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e   scalar function
31e00 73 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72  s) or xStep (for
31e10 20 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72   aggregates) par
31e20 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73  ameters.** to [s
31e30 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
31e40 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  nction()] and [s
31e50 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
31e60 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64  nction16()].** d
31e70 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20  efine callbacks 
31e80 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74  that implement t
31e90 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  he SQL functions
31ea0 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e   and aggregates.
31eb0 0a 2a 2a 20 54 68 65 20 33 72 64 20 70 61 72 61  .** The 3rd para
31ec0 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63  meter to these c
31ed0 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61  allbacks is an a
31ee0 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
31ef0 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65   to.** [protecte
31f00 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
31f10 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65   objects.  There
31f20 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33   is one [sqlite3
31f30 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66  _value] object f
31f40 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d  or.** each param
31f50 65 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20  eter to the SQL 
31f60 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65  function.  These
31f70 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
31f80 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74  ed to.** extract
31f90 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65   values from the
31fa0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
31fb0 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20   objects..**.** 
31fc0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77  These routines w
31fd0 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70  ork only with [p
31fe0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
31ff0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
32000 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20  .** Any attempt 
32010 74 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f 75  to use these rou
32020 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70  tines on an [unp
32030 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
32040 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63  _value].** objec
32050 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64  t results in und
32060 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e  efined behavior.
32070 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
32080 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74  utines work just
32090 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73   like the corres
320a0 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20  ponding [column 
320b0 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73  access functions
320c0 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74  ].** except that
320d0 20 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73    these routines
320e0 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b   take a single [
320f0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
32100 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a  3_value] object.
32110 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65  ** pointer inste
32120 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33  ad of a [sqlite3
32130 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20  _stmt*] pointer 
32140 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63  and an integer c
32150 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a  olumn number..**
32160 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
32170 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20  _value_text16() 
32180 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 61 63  interface extrac
32190 74 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  ts a UTF-16 stri
321a0 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74  ng.** in the nat
321b0 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f  ive byte-order o
321c0 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69  f the host machi
321d0 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c  ne.  ^The.** sql
321e0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
321f0 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  6be() and sqlite
32200 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
32210 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
32220 20 65 78 74 72 61 63 74 20 55 54 46 2d 31 36 20   extract UTF-16 
32230 73 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65  strings as big-e
32240 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65  ndian and little
32250 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69  -endian respecti
32260 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  vely..**.** ^(Th
32270 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
32280 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69  numeric_type() i
32290 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
322a0 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75  s to apply.** nu
322b0 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 74  meric affinity t
322c0 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68  o the value.  Th
322d0 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e  is means that an
322e0 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d   attempt is.** m
322f0 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ade to convert t
32300 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69  he value to an i
32310 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69  nteger or floati
32320 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a  ng point.  If.**
32330 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69   such a conversi
32340 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77  on is possible w
32350 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69  ithout loss of i
32360 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f  nformation (in o
32370 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69  ther.** words, i
32380 66 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 61  f the value is a
32390 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f   string that loo
323a0 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72  ks like a number
323b0 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f  ).** then the co
323c0 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66  nversion is perf
323d0 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73  ormed.  Otherwis
323e0 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20  e no conversion 
323f0 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b  occurs..** The [
32400 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c  SQLITE_INTEGER |
32410 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65 72   datatype] after
32420 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72   conversion is r
32430 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a  eturned.)^.**.**
32440 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 74   Please pay part
32450 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e  icular attention
32460 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 61   to the fact tha
32470 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65  t the pointer re
32480 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  turned.** from [
32490 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
324a0 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ob()], [sqlite3_
324b0 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f  value_text()], o
324c0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61  r.** [sqlite3_va
324d0 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61  lue_text16()] ca
324e0 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64  n be invalidated
324f0 20 62 79 20 61 20 73 75 62 73 65 71 75 65 6e 74   by a subsequent
32500 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
32510 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
32520 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
32530 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20  lue_bytes16()], 
32540 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
32550 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73  ext()],.** or [s
32560 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
32570 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  t16()]..**.** Th
32580 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73  ese routines mus
32590 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
325a0 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
325b0 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66   as.** the SQL f
325c0 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70  unction that sup
325d0 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74  plied the [sqlit
325e0 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d  e3_value*] param
325f0 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  eters..*/.const 
32600 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
32610 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  lue_blob(sqlite3
32620 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
32630 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
32640 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  s(sqlite3_value*
32650 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
32660 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c  alue_bytes16(sql
32670 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f  ite3_value*);.do
32680 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  uble sqlite3_val
32690 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  ue_double(sqlite
326a0 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
326b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
326c0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
326d0 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
326e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
326f0 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  t64(sqlite3_valu
32700 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67  e*);.const unsig
32710 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65  ned char *sqlite
32720 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c  3_value_text(sql
32730 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
32740 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
32750 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73  3_value_text16(s
32760 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
32770 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
32780 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
32790 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le(sqlite3_value
327a0 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
327b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
327c0 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76  xt16be(sqlite3_v
327d0 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
327e0 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73  te3_value_type(s
327f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
32800 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
32810 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73  e_numeric_type(s
32820 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
32830 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
32840 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74   Obtain Aggregat
32850 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  e Function Conte
32860 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65  xt.**.** Impleme
32870 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67 72  ntations of aggr
32880 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
32890 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20  ons use this.** 
328a0 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63  routine to alloc
328b0 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73  ate memory for s
328c0 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61  toring their sta
328d0 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  te..**.** ^The f
328e0 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71  irst time the sq
328f0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
32900 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75  context(C,N) rou
32910 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a  tine is called .
32920 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  ** for a particu
32930 6c 61 72 20 61 67 67 72 65 67 61 74 65 20 66 75  lar aggregate fu
32940 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a  nction, SQLite.*
32950 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66  * allocates N of
32960 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20   memory, zeroes 
32970 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c  out that memory,
32980 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70   and returns a p
32990 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
329a0 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e   new memory. ^On
329b0 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   second and subs
329c0 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a  equent calls to.
329d0 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  ** sqlite3_aggre
329e0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66  gate_context() f
329f0 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 72  or the same aggr
32a00 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69  egate function i
32a10 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20  nstance,.** the 
32a20 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72  same buffer is r
32a30 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65  eturned.  Sqlite
32a40 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
32a50 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c  ext() is normall
32a60 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65  y.** called once
32a70 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61   for each invoca
32a80 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65  tion of the xSte
32a90 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74  p callback and t
32aa0 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20  hen one.** last 
32ab0 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46  time when the xF
32ac0 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73  inal callback is
32ad0 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65   invoked.  ^(Whe
32ae0 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a  n no rows match.
32af0 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65 20  ** an aggregate 
32b00 71 75 65 72 79 2c 20 74 68 65 20 78 53 74 65 70  query, the xStep
32b10 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74  () callback of t
32b20 68 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  he aggregate fun
32b30 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65  ction.** impleme
32b40 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72  ntation is never
32b50 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e   called and xFin
32b60 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65  al() is called e
32b70 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20  xactly once..** 
32b80 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20  In those cases, 
32b90 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
32ba0 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68  e_context() migh
32bb0 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20  t be called for 
32bc0 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d  the.** first tim
32bd0 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46  e from within xF
32be0 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  inal().)^.**.** 
32bf0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67  ^The sqlite3_agg
32c00 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
32c10 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ,N) routine retu
32c20 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
32c30 65 72 20 0a 2a 2a 20 77 68 65 6e 20 66 69 72 73  er .** when firs
32c40 74 20 63 61 6c 6c 65 64 20 69 66 20 4e 20 69 73  t called if N is
32c50 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71   less than or eq
32c60 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69  ual to zero or i
32c70 66 20 61 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  f a memory.** al
32c80 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63  locate error occ
32c90 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  urs..**.** ^(The
32ca0 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65   amount of space
32cb0 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71   allocated by sq
32cc0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
32cd0 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a  context(C,N) is.
32ce0 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79  ** determined by
32cf0 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72   the N parameter
32d00 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65 73   on first succes
32d10 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e  sful call.  Chan
32d20 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75  ging the.** valu
32d30 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71  e of N in subseq
32d40 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c  uent call to sql
32d50 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
32d60 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a  ontext() within.
32d70 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67 72  ** the same aggr
32d80 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69  egate function i
32d90 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74  nstance will not
32da0 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f   resize the memo
32db0 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
32dc0 2e 29 5e 20 20 57 69 74 68 69 6e 20 74 68 65 20  .)^  Within the 
32dd0 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 2c  xFinal callback,
32de0 20 69 74 20 69 73 20 63 75 73 74 6f 6d 61 72 79   it is customary
32df0 20 74 6f 20 73 65 74 0a 2a 2a 20 4e 3d 30 20 69   to set.** N=0 i
32e00 6e 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  n calls to sqlit
32e10 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
32e20 74 65 78 74 28 43 2c 4e 29 20 73 6f 20 74 68 61  text(C,N) so tha
32e30 74 20 6e 6f 20 0a 2a 2a 20 70 6f 69 6e 74 6c 65  t no .** pointle
32e40 73 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ss memory alloca
32e50 74 69 6f 6e 73 20 6f 63 63 75 72 2e 0a 2a 2a 0a  tions occur..**.
32e60 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d  ** ^SQLite autom
32e70 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74  atically frees t
32e80 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
32e90 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74  ted by .** sqlit
32ea0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
32eb0 74 65 78 74 28 29 20 77 68 65 6e 20 74 68 65 20  text() when the 
32ec0 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79 20  aggregate query 
32ed0 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a  concludes..**.**
32ee0 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
32ef0 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 20 63  eter must be a c
32f00 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  opy of the.** [s
32f10 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c  qlite3_context |
32f20 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f   SQL function co
32f30 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74  ntext] that is t
32f40 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
32f50 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 74  er.** to the xSt
32f60 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c  ep or xFinal cal
32f70 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68  lback routine th
32f80 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  at implements th
32f90 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66  e aggregate.** f
32fa0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  unction..**.** T
32fb0 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74  his routine must
32fc0 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
32fd0 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
32fe0 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
32ff0 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
33000 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
33010 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  g..*/.void *sqli
33020 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
33030 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f  ntext(sqlite3_co
33040 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74  ntext*, int nByt
33050 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  es);../*.** CAPI
33060 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 20  3REF: User Data 
33070 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  For Functions.**
33080 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
33090 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74  _user_data() int
330a0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
330b0 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
330c0 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 73  pointer that was
330d0 20 74 68 65 20 70 55 73 65 72 44 61 74 61 20 70   the pUserData p
330e0 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 74  arameter (the 5t
330f0 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20  h parameter).** 
33100 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
33110 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
33120 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
33130 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
33140 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73  on16()] routines
33150 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79   that originally
33160 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74  .** registered t
33170 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
33180 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
33190 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
331a0 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  ine must be call
331b0 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
331c0 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
331d0 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
331e0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
331f0 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
33200 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
33210 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69  3_user_data(sqli
33220 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a  te3_context*);..
33230 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
33240 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
33250 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e  ion For Function
33260 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
33270 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
33280 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61  handle() interfa
33290 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  ce returns a cop
332a0 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e  y of.** the poin
332b0 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61  ter to the [data
332c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
332d0 20 28 74 68 65 20 31 73 74 20 70 61 72 61 6d 65   (the 1st parame
332e0 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  ter).** of the [
332f0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
33300 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e  unction()].** an
33310 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
33320 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20  e_function16()] 
33330 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72  routines that or
33340 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69  iginally.** regi
33350 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69  stered the appli
33360 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66  cation defined f
33370 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69  unction..*/.sqli
33380 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e  te3 *sqlite3_con
33390 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73  text_db_handle(s
333a0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
333b0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
333c0 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69  F: Function Auxi
333d0 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a  liary Data.**.**
333e0 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
333f0 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79 20   may be used by 
33400 28 6e 6f 6e 2d 61 67 67 72 65 67 61 74 65 29 20  (non-aggregate) 
33410 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f  SQL functions to
33420 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65  .** associate me
33430 74 61 64 61 74 61 20 77 69 74 68 20 61 72 67 75  tadata with argu
33440 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 20  ment values. If 
33450 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20 69  the same value i
33460 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d  s passed to.** m
33470 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69  ultiple invocati
33480 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
33490 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 72  SQL function dur
334a0 69 6e 67 20 71 75 65 72 79 20 65 78 65 63 75 74  ing query execut
334b0 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f  ion, under.** so
334c0 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73  me circumstances
334d0 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 64 20   the associated 
334e0 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62 65 20  metadata may be 
334f0 70 72 65 73 65 72 76 65 64 2e 20 20 41 6e 20 65  preserved.  An e
33500 78 61 6d 70 6c 65 0a 2a 2a 20 6f 66 20 77 68 65  xample.** of whe
33510 72 65 20 74 68 69 73 20 6d 69 67 68 74 20 62 65  re this might be
33520 20 75 73 65 66 75 6c 20 69 73 20 69 6e 20 61 20   useful is in a 
33530 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69  regular-expressi
33540 6f 6e 20 6d 61 74 63 68 69 6e 67 0a 2a 2a 20 66  on matching.** f
33550 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d  unction. The com
33560 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66  piled version of
33570 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70   the regular exp
33580 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 73  ression can be s
33590 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61  tored as.** meta
335a0 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20  data associated 
335b0 77 69 74 68 20 74 68 65 20 70 61 74 74 65 72 6e  with the pattern
335c0 20 73 74 72 69 6e 67 2e 20 20 0a 2a 2a 20 54 68   string.  .** Th
335d0 65 6e 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  en as long as th
335e0 65 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67  e pattern string
335f0 20 72 65 6d 61 69 6e 73 20 74 68 65 20 73 61 6d   remains the sam
33600 65 2c 0a 2a 2a 20 74 68 65 20 63 6f 6d 70 69 6c  e,.** the compil
33610 65 64 20 72 65 67 75 6c 61 72 20 65 78 70 72 65  ed regular expre
33620 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75  ssion can be reu
33630 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a  sed on multiple.
33640 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  ** invocations o
33650 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  f the same funct
33660 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ion..**.** ^The 
33670 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
33680 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
33690 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
336a0 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74  r to the metadat
336b0 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  a.** associated 
336c0 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  by the sqlite3_s
336d0 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e  et_auxdata() fun
336e0 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e  ction with the N
336f0 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76  th argument.** v
33700 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c  alue to the appl
33710 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
33720 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 74 68  function. ^If th
33730 65 72 65 20 69 73 20 6e 6f 20 6d 65 74 61 64 61  ere is no metada
33740 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  ta.** associated
33750 20 77 69 74 68 20 74 68 65 20 66 75 6e 63 74 69   with the functi
33760 6f 6e 20 61 72 67 75 6d 65 6e 74 2c 20 74 68 69  on argument, thi
33770 73 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  s sqlite3_get_au
33780 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  xdata() interfac
33790 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 4e  e.** returns a N
337a0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
337b0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
337c0 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c  set_auxdata(C,N,
337d0 50 2c 58 29 20 69 6e 74 65 72 66 61 63 65 20 73  P,X) interface s
337e0 61 76 65 73 20 50 20 61 73 20 6d 65 74 61 64 61  aves P as metada
337f0 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a  ta for the N-th.
33800 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74  ** argument of t
33810 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
33820 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
33830 20 20 5e 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a    ^Subsequent.**
33840 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
33850 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 43 2c  3_get_auxdata(C,
33860 4e 29 20 72 65 74 75 72 6e 20 50 20 66 72 6f 6d  N) return P from
33870 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
33880 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  .** sqlite3_set_
33890 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29  auxdata(C,N,P,X)
338a0 20 63 61 6c 6c 20 69 66 20 74 68 65 20 6d 65 74   call if the met
338b0 61 64 61 74 61 20 69 73 20 73 74 69 6c 6c 20 76  adata is still v
338c0 61 6c 69 64 20 6f 72 0a 2a 2a 20 4e 55 4c 4c 20  alid or.** NULL 
338d0 69 66 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  if the metadata 
338e0 68 61 73 20 62 65 65 6e 20 64 69 73 63 61 72 64  has been discard
338f0 65 64 2e 0a 2a 2a 20 5e 41 66 74 65 72 20 65 61  ed..** ^After ea
33900 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ch call to sqlit
33910 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43  e3_set_auxdata(C
33920 2c 4e 2c 50 2c 58 29 20 77 68 65 72 65 20 58 20  ,N,P,X) where X 
33930 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20  is not NULL,.** 
33940 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f  SQLite will invo
33950 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  ke the destructo
33960 72 20 66 75 6e 63 74 69 6f 6e 20 58 20 77 69 74  r function X wit
33970 68 20 70 61 72 61 6d 65 74 65 72 20 50 20 65 78  h parameter P ex
33980 61 63 74 6c 79 0a 2a 2a 20 6f 6e 63 65 2c 20 77  actly.** once, w
33990 68 65 6e 20 74 68 65 20 6d 65 74 61 64 61 74 61  hen the metadata
339a0 20 69 73 20 64 69 73 63 61 72 64 65 64 2e 0a 2a   is discarded..*
339b0 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72 65 65  * SQLite is free
339c0 20 74 6f 20 64 69 73 63 61 72 64 20 74 68 65 20   to discard the 
339d0 6d 65 74 61 64 61 74 61 20 61 74 20 61 6e 79 20  metadata at any 
339e0 74 69 6d 65 2c 20 69 6e 63 6c 75 64 69 6e 67 3a  time, including:
339f0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 77 68   <ul>.** <li> wh
33a00 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  en the correspon
33a10 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61  ding function pa
33a20 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 2c  rameter changes,
33a30 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e   or.** <li> when
33a40 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
33a50 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
33a60 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61  inalize()] is ca
33a70 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20  lled for the.** 
33a80 20 20 20 20 20 53 51 4c 20 73 74 61 74 65 6d 65       SQL stateme
33a90 6e 74 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77  nt, or.** <li> w
33aa0 68 65 6e 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  hen sqlite3_set_
33ab0 61 75 78 64 61 74 61 28 29 20 69 73 20 69 6e 76  auxdata() is inv
33ac0 6f 6b 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68  oked again on th
33ad0 65 20 73 61 6d 65 20 70 61 72 61 6d 65 74 65 72  e same parameter
33ae0 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 64 75 72  , or.** <li> dur
33af0 69 6e 67 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  ing the original
33b00 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
33b10 64 61 74 61 28 29 20 63 61 6c 6c 20 77 68 65 6e  data() call when
33b20 20 61 20 6d 65 6d 6f 72 79 20 0a 2a 2a 20 20 20   a memory .**   
33b30 20 20 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72     allocation er
33b40 72 6f 72 20 6f 63 63 75 72 73 2e 20 3c 2f 75 6c  ror occurs. </ul
33b50 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  >)^.**.** Note t
33b60 68 65 20 6c 61 73 74 20 62 75 6c 6c 65 74 20 69  he last bullet i
33b70 6e 20 70 61 72 74 69 63 75 6c 61 72 2e 20 20 54  n particular.  T
33b80 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 58 20  he destructor X 
33b90 69 6e 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  in .** sqlite3_s
33ba0 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50  et_auxdata(C,N,P
33bb0 2c 58 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c  ,X) might be cal
33bc0 6c 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c  led immediately,
33bd0 20 62 65 66 6f 72 65 20 74 68 65 0a 2a 2a 20 73   before the.** s
33be0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
33bf0 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 65  ta() interface e
33c00 76 65 6e 20 72 65 74 75 72 6e 73 2e 20 20 48 65  ven returns.  He
33c10 6e 63 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  nce sqlite3_set_
33c20 61 75 78 64 61 74 61 28 29 0a 2a 2a 20 73 68 6f  auxdata().** sho
33c30 75 6c 64 20 62 65 20 63 61 6c 6c 65 64 20 6e 65  uld be called ne
33c40 61 72 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68  ar the end of th
33c50 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  e function imple
33c60 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 20 74 68  mentation and th
33c70 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6d  e.** function im
33c80 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f  plementation sho
33c90 75 6c 64 20 6e 6f 74 20 6d 61 6b 65 20 61 6e 79  uld not make any
33ca0 20 75 73 65 20 6f 66 20 50 20 61 66 74 65 72 0a   use of P after.
33cb0 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  ** sqlite3_set_a
33cc0 75 78 64 61 74 61 28 29 20 68 61 73 20 62 65 65  uxdata() has bee
33cd0 6e 20 63 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  n called..**.** 
33ce0 5e 28 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d  ^(In practice, m
33cf0 65 74 61 64 61 74 61 20 69 73 20 70 72 65 73 65  etadata is prese
33d00 72 76 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e  rved between fun
33d10 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a  ction calls for.
33d20 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61  ** function para
33d30 6d 65 74 65 72 73 20 74 68 61 74 20 61 72 65 20  meters that are 
33d40 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 63 6f 6e  compile-time con
33d50 73 74 61 6e 74 73 2c 20 69 6e 63 6c 75 64 69 6e  stants, includin
33d60 67 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c  g literal.** val
33d70 75 65 73 20 61 6e 64 20 5b 70 61 72 61 6d 65 74  ues and [paramet
33d80 65 72 73 5d 20 61 6e 64 20 65 78 70 72 65 73 73  ers] and express
33d90 69 6f 6e 73 20 63 6f 6d 70 6f 73 65 64 20 66 72  ions composed fr
33da0 6f 6d 20 74 68 65 20 73 61 6d 65 2e 29 5e 0a 2a  om the same.)^.*
33db0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
33dc0 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  nes must be call
33dd0 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
33de0 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
33df0 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63  .** the SQL func
33e00 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
33e10 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
33e20 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73 71  3_get_auxdata(sq
33e30 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
33e40 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20 73 71 6c  int N);.void sql
33e50 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
33e60 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
33e70 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c  *, int N, void*,
33e80 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a 29   void (*)(void*)
33e90 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  );.../*.** CAPI3
33ea0 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44  REF: Constants D
33eb0 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c 20  efining Special 
33ec0 44 65 73 74 72 75 63 74 6f 72 20 42 65 68 61 76  Destructor Behav
33ed0 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ior.**.** These 
33ee0 61 72 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75  are special valu
33ef0 65 73 20 66 6f 72 20 74 68 65 20 64 65 73 74 72  es for the destr
33f00 75 63 74 6f 72 20 74 68 61 74 20 69 73 20 70 61  uctor that is pa
33f10 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a  ssed in as the.*
33f20 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74  * final argument
33f30 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b   to routines lik
33f40 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
33f50 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e 49 66 20  t_blob()].  ^If 
33f60 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a  the destructor.*
33f70 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 53 51  * argument is SQ
33f80 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69 74 20  LITE_STATIC, it 
33f90 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63  means that the c
33fa0 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72 20 69  ontent pointer i
33fb0 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e  s constant.** an
33fc0 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63 68 61  d will never cha
33fd0 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f  nge.  It does no
33fe0 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64 65 73  t need to be des
33ff0 74 72 6f 79 65 64 2e 20 20 5e 54 68 65 0a 2a 2a  troyed.  ^The.**
34000 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e   SQLITE_TRANSIEN
34010 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20 74 68  T value means th
34020 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 77  at the content w
34030 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67  ill likely chang
34040 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72  e in.** the near
34050 20 66 75 74 75 72 65 20 61 6e 64 20 74 68 61 74   future and that
34060 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d   SQLite should m
34070 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72 69 76  ake its own priv
34080 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  ate copy of.** t
34090 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72  he content befor
340a0 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a  e returning..**.
340b0 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66 20 69  ** The typedef i
340c0 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20 77  s necessary to w
340d0 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c  ork around probl
340e0 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a  ems in certain.*
340f0 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e  * C++ compilers.
34100 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64  .*/.typedef void
34110 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72   (*sqlite3_destr
34120 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64  uctor_type)(void
34130 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  *);.#define SQLI
34140 54 45 5f 53 54 41 54 49 43 20 20 20 20 20 20 28  TE_STATIC      (
34150 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63  (sqlite3_destruc
34160 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66  tor_type)0).#def
34170 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ine SQLITE_TRANS
34180 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33  IENT   ((sqlite3
34190 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
341a0 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  )-1)../*.** CAPI
341b0 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68  3REF: Setting Th
341c0 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53  e Result Of An S
341d0 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a  QL Function.**.*
341e0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
341f0 20 61 72 65 20 75 73 65 64 20 62 79 20 74 68 65   are used by the
34200 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c   xFunc or xFinal
34210 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a   callbacks that.
34220 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c  ** implement SQL
34230 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
34240 67 67 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a  ggregates.  See.
34250 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ** [sqlite3_crea
34260 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61  te_function()] a
34270 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
34280 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
34290 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  .** for addition
342a0 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
342b0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63  **.** These func
342c0 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20  tions work very 
342d0 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70  much like the [p
342e0 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67  arameter binding
342f0 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66  ] family of.** f
34300 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f  unctions used to
34310 20 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20   bind values to 
34320 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20  host parameters 
34330 69 6e 20 70 72 65 70 61 72 65 64 20 73 74 61 74  in prepared stat
34340 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72  ements..** Refer
34350 20 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72   to the [SQL par
34360 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74  ameter] document
34370 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
34380 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
34390 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
343a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
343b0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
343c0 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f  s the result fro
343d0 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74  m.** an applicat
343e0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
343f0 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42  tion to be the B
34400 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e  LOB whose conten
34410 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20  t is pointed.** 
34420 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  to by the second
34430 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77   parameter and w
34440 68 69 63 68 20 69 73 20 4e 20 62 79 74 65 73 20  hich is N bytes 
34450 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20  long where N is 
34460 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72  the.** third par
34470 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ameter..**.** ^T
34480 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
34490 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74  t_zeroblob() int
344a0 65 72 66 61 63 65 73 20 73 65 74 20 74 68 65 20  erfaces set the 
344b0 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65  result of.** the
344c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
344d0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
344e0 20 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61   be a BLOB conta
344f0 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a  ining all zero.*
34500 2a 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79  * bytes and N by
34510 74 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65  tes in size, whe
34520 72 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75  re N is the valu
34530 65 20 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72  e of the 2nd par
34540 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ameter..**.** ^T
34550 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
34560 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72  t_double() inter
34570 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
34580 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20  sult from.** an 
34590 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
345a0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
345b0 62 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f  be a floating po
345c0 69 6e 74 20 76 61 6c 75 65 20 73 70 65 63 69 66  int value specif
345d0 69 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e  ied.** by its 2n
345e0 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
345f0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
34600 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e  esult_error() an
34610 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
34620 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74  _error16() funct
34630 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68  ions.** cause th
34640 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51  e implemented SQ
34650 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68  L function to th
34660 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e  row an exception
34670 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65  ..** ^SQLite use
34680 73 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69  s the string poi
34690 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a  nted to by the.*
346a0 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  * 2nd parameter 
346b0 6f 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  of sqlite3_resul
346c0 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c  t_error() or sql
346d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
346e0 72 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20  r16().** as the 
346f0 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72  text of an error
34700 20 6d 65 73 73 61 67 65 2e 20 20 5e 53 51 4c 69   message.  ^SQLi
34710 74 65 20 69 6e 74 65 72 70 72 65 74 73 20 74 68  te interprets th
34720 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61  e error.** messa
34730 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73  ge string from s
34740 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
34750 72 6f 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20  ror() as UTF-8. 
34760 5e 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72  ^SQLite.** inter
34770 70 72 65 74 73 20 74 68 65 20 73 74 72 69 6e 67  prets the string
34780 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65   from sqlite3_re
34790 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61  sult_error16() a
347a0 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69  s UTF-16 in nati
347b0 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72  ve.** byte order
347c0 2e 20 20 5e 49 66 20 74 68 65 20 74 68 69 72 64  .  ^If the third
347d0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
347e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
347f0 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  or().** or sqlit
34800 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
34810 36 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 20  6() is negative 
34820 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65  then SQLite take
34830 73 20 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a  s as the error.*
34840 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65  * message all te
34850 78 74 20 75 70 20 74 68 72 6f 75 67 68 20 74 68  xt up through th
34860 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61  e first zero cha
34870 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74  racter..** ^If t
34880 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
34890 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
348a0 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a  sult_error() or.
348b0 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
348c0 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e  t_error16() is n
348d0 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e  on-negative then
348e0 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68   SQLite takes th
348f0 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73  at many.** bytes
34900 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73   (not characters
34910 29 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70  ) from the 2nd p
34920 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20  arameter as the 
34930 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a  error message..*
34940 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
34950 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e  esult_error() an
34960 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
34970 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f  _error16().** ro
34980 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72  utines make a pr
34990 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
349a0 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
349b0 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74  text before.** t
349c0 68 65 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e  hey return.  Hen
349d0 63 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20  ce, the calling 
349e0 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61  function can dea
349f0 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f  llocate or.** mo
34a00 64 69 66 79 20 74 68 65 20 74 65 78 74 20 61 66  dify the text af
34a10 74 65 72 20 74 68 65 79 20 72 65 74 75 72 6e 20  ter they return 
34a20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a  without harm..**
34a30 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
34a40 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28  sult_error_code(
34a50 29 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67  ) function chang
34a60 65 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  es the error cod
34a70 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79  e.** returned by
34a80 20 53 51 4c 69 74 65 20 61 73 20 61 20 72 65 73   SQLite as a res
34a90 75 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20  ult of an error 
34aa0 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20  in a function.  
34ab0 5e 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20  ^By default,.** 
34ac0 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69  the error code i
34ad0 73 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20  s SQLITE_ERROR. 
34ae0 20 5e 41 20 73 75 62 73 65 71 75 65 6e 74 20 63   ^A subsequent c
34af0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  all to sqlite3_r
34b00 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a  esult_error().**
34b10 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
34b20 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73  lt_error16() res
34b30 65 74 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f  ets the error co
34b40 64 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52  de to SQLITE_ERR
34b50 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  OR..**.** ^The s
34b60 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
34b70 72 6f 72 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74  ror_toobig() int
34b80 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51  erface causes SQ
34b90 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e  Lite to throw an
34ba0 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69 63 61  .** error indica
34bb0 74 69 6e 67 20 74 68 61 74 20 61 20 73 74 72 69  ting that a stri
34bc0 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f  ng or BLOB is to
34bd0 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 73  o long to repres
34be0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ent..**.** ^The 
34bf0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
34c00 72 72 6f 72 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74  rror_nomem() int
34c10 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51  erface causes SQ
34c20 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e  Lite to throw an
34c30 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69 63 61  .** error indica
34c40 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f  ting that a memo
34c50 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
34c60 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  iled..**.** ^The
34c70 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34c80 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65 20  int() interface 
34c90 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20  sets the return 
34ca0 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20  value.** of the 
34cb0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
34cc0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
34cd0 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 73 69  be the 32-bit si
34ce0 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
34cf0 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74  value given in t
34d00 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e  he 2nd argument.
34d10 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
34d20 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20  _result_int64() 
34d30 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
34d40 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
34d50 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ** of the applic
34d60 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
34d70 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65  nction to be the
34d80 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
34d90 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20  nteger.** value 
34da0 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64  given in the 2nd
34db0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
34dc0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
34dd0 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65  sult_null() inte
34de0 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
34df0 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f  eturn value.** o
34e00 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
34e10 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
34e20 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a  on to be NULL..*
34e30 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
34e40 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c  3_result_text(),
34e50 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34e60 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c  text16(),.** sql
34e70 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
34e80 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69  16le(), and sqli
34e90 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
34ea0 36 62 65 28 29 20 69 6e 74 65 72 66 61 63 65 73  6be() interfaces
34eb0 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74 75  .** set the retu
34ec0 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  rn value of the 
34ed0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
34ee0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
34ef0 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72  be.** a text str
34f00 69 6e 67 20 77 68 69 63 68 20 69 73 20 72 65 70  ing which is rep
34f10 72 65 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d  resented as UTF-
34f20 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65  8, UTF-16 native
34f30 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20   byte order,.** 
34f40 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e  UTF-16 little en
34f50 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20  dian, or UTF-16 
34f60 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70  big endian, resp
34f70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51  ectively..** ^SQ
34f80 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65 20 74  Lite takes the t
34f90 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20  ext result from 
34fa0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
34fb0 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20  from.** the 2nd 
34fc0 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65  parameter of the
34fd0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34fe0 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
34ff0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64  ..** ^If the 3rd
35000 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
35010 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
35020 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
35030 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65  s.** is negative
35040 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  , then SQLite ta
35050 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 20  kes result text 
35060 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72  from the 2nd par
35070 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67  ameter.** throug
35080 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  h the first zero
35090 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e   character..** ^
350a0 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
350b0 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
350c0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
350d0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69   interfaces.** i
350e0 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
350f0 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74  then as many byt
35100 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65  es (not characte
35110 72 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a  rs) of the text.
35120 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ** pointed to by
35130 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
35140 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20  er are taken as 
35150 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
35160 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74  defined.** funct
35170 69 6f 6e 20 72 65 73 75 6c 74 2e 20 20 49 66 20  ion result.  If 
35180 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
35190 72 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  r is non-negativ
351a0 65 2c 20 74 68 65 6e 20 69 74 0a 2a 2a 20 6d 75  e, then it.** mu
351b0 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f  st be the byte o
351c0 66 66 73 65 74 20 69 6e 74 6f 20 74 68 65 20 73  ffset into the s
351d0 74 72 69 6e 67 20 77 68 65 72 65 20 74 68 65 20  tring where the 
351e0 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77  NUL terminator w
351f0 6f 75 6c 64 0a 2a 2a 20 61 70 70 65 61 72 20 69  ould.** appear i
35200 66 20 74 68 65 20 73 74 72 69 6e 67 20 77 68 65  f the string whe
35210 72 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 65  re NUL terminate
35220 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63  d.  If any NUL c
35230 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 0a  haracters occur.
35240 2a 2a 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67  ** in the string
35250 20 61 74 20 61 20 62 79 74 65 20 6f 66 66 73 65   at a byte offse
35260 74 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 74  t that is less t
35270 68 61 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66  han the value of
35280 20 74 68 65 20 33 72 64 0a 2a 2a 20 70 61 72 61   the 3rd.** para
35290 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  meter, then the 
352a0 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67  resulting string
352b0 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 65 6d   will contain em
352c0 62 65 64 64 65 64 20 4e 55 4c 73 20 61 6e 64 20  bedded NULs and 
352d0 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 6f 66  the.** result of
352e0 20 65 78 70 72 65 73 73 69 6f 6e 73 20 6f 70 65   expressions ope
352f0 72 61 74 69 6e 67 20 6f 6e 20 73 74 72 69 6e 67  rating on string
35300 73 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 20  s with embedded 
35310 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65  NULs is undefine
35320 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74  d..** ^If the 4t
35330 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
35340 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
35350 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
35360 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  es.** or sqlite3
35370 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20  _result_blob is 
35380 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
35390 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  er, then SQLite 
353a0 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75  calls that.** fu
353b0 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65  nction as the de
353c0 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20  structor on the 
353d0 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73  text or BLOB res
353e0 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a  ult when it has.
353f0 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e  ** finished usin
35400 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a  g that result..*
35410 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61  * ^If the 4th pa
35420 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
35430 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
35440 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f  xt* interfaces o
35450 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  r to.** sqlite3_
35460 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74  result_blob is t
35470 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74  he special const
35480 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49  ant SQLITE_STATI
35490 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a  C, then SQLite.*
354a0 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  * assumes that t
354b0 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20  he text or BLOB 
354c0 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e  result is in con
354d0 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20  stant space and 
354e0 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79  does not.** copy
354f0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
35500 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6e 6f  the parameter no
35510 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63  r call a destruc
35520 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65  tor on the conte
35530 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68 61  nt.** when it ha
35540 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67  s finished using
35550 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a   that result..**
35560 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72   ^If the 4th par
35570 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
35580 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
35590 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
355a0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
355b0 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73  lt_blob is the s
355c0 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20  pecial constant 
355d0 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
355e0 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20  .** then SQLite 
355f0 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
35600 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20  the result into 
35610 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66  space obtained f
35620 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  rom.** from [sql
35630 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62  ite3_malloc()] b
35640 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73  efore it returns
35650 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
35660 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
35670 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  e() interface se
35680 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  ts the result of
35690 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
356a0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
356b0 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70  tion to be a cop
356c0 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74  y the.** [unprot
356d0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
356e0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63  lue] object spec
356f0 69 66 69 65 64 20 62 79 20 74 68 65 20 32 6e 64  ified by the 2nd
35700 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68   parameter.  ^Th
35710 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  e.** sqlite3_res
35720 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65  ult_value() inte
35730 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f  rface makes a co
35740 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  py of the [sqlit
35750 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20  e3_value].** so 
35760 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65  that the [sqlite
35770 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69  3_value] specifi
35780 65 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65  ed in the parame
35790 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f  ter may change o
357a0 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61  r.** be dealloca
357b0 74 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65  ted after sqlite
357c0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
357d0 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74   returns without
357e0 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72   harm..** ^A [pr
357f0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
35800 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61  value] object ma
35810 79 20 61 6c 77 61 79 73 20 62 65 20 75 73 65 64  y always be used
35820 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e   where an.** [un
35830 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
35840 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
35850 69 73 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20  is required, so 
35860 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f  either.** kind o
35870 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  f [sqlite3_value
35880 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20  ] object can be 
35890 75 73 65 64 20 77 69 74 68 20 74 68 69 73 20 69  used with this i
358a0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
358b0 49 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  If these routine
358c0 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f  s are called fro
358d0 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64 69 66  m within the dif
358e0 66 65 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a  ferent thread.**
358f0 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f   than the one co
35900 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70  ntaining the app
35910 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
35920 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72   function that r
35930 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b  eceived.** the [
35940 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d  sqlite3_context]
35950 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65   pointer, the re
35960 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
35970 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  ned..*/.void sql
35980 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
35990 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
359a0 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
359b0 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
359c0 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
359d0 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65  e3_result_double
359e0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
359f0 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64  *, double);.void
35a00 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35a10 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f  error(sqlite3_co
35a20 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68  ntext*, const ch
35a30 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  ar*, int);.void 
35a40 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
35a50 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63  rror16(sqlite3_c
35a60 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
35a70 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  oid*, int);.void
35a80 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35a90 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c  error_toobig(sql
35aa0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
35ab0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
35ac0 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28  ult_error_nomem(
35ad0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
35ae0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
35af0 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64  result_error_cod
35b00 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
35b10 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  t*, int);.void s
35b20 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
35b30 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
35b40 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  t*, int);.void s
35b50 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
35b60 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  t64(sqlite3_cont
35b70 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ext*, sqlite3_in
35b80 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  t64);.void sqlit
35b90 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73  e3_result_null(s
35ba0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
35bb0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
35bc0 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74  esult_text(sqlit
35bd0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
35be0 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76  st char*, int, v
35bf0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
35c00 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
35c10 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74  ult_text16(sqlit
35c20 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
35c30 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
35c40 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
35c50 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
35c60 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c  ult_text16le(sql
35c70 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
35c80 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
35c90 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
35ca0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
35cb0 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73 71  sult_text16be(sq
35cc0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
35cd0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
35ce0 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
35cf0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
35d00 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69  esult_value(sqli
35d10 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71  te3_context*, sq
35d20 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76  lite3_value*);.v
35d30 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
35d40 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69  lt_zeroblob(sqli
35d50 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
35d60 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t n);../*.** CAP
35d70 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65  I3REF: Define Ne
35d80 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75  w Collating Sequ
35d90 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ences.**.** ^The
35da0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 64 64  se functions add
35db0 2c 20 72 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64  , remove, or mod
35dc0 69 66 79 20 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e  ify a [collation
35dd0 5d 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20  ] associated.** 
35de0 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
35df0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73  se connection] s
35e00 70 65 63 69 66 69 65 64 20 61 73 20 74 68 65 20  pecified as the 
35e10 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a  first argument..
35e20 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20  **.** ^The name 
35e30 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  of the collation
35e40 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69   is a UTF-8 stri
35e50 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65  ng.** for sqlite
35e60 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
35e70 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  on() and sqlite3
35e80 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
35e90 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20  n_v2().** and a 
35ea0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e  UTF-16 string in
35eb0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
35ec0 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63  er for sqlite3_c
35ed0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
35ee0 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69  6()..** ^Collati
35ef0 6f 6e 20 6e 61 6d 65 73 20 74 68 61 74 20 63 6f  on names that co
35f00 6d 70 61 72 65 20 65 71 75 61 6c 20 61 63 63 6f  mpare equal acco
35f10 72 64 69 6e 67 20 74 6f 20 5b 73 71 6c 69 74 65  rding to [sqlite
35f20 33 5f 73 74 72 6e 69 63 6d 70 28 29 5d 20 61 72  3_strnicmp()] ar
35f30 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20  e.** considered 
35f40 74 6f 20 62 65 20 74 68 65 20 73 61 6d 65 20 6e  to be the same n
35f50 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ame..**.** ^(The
35f60 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
35f70 28 65 54 65 78 74 52 65 70 29 20 6d 75 73 74 20  (eTextRep) must 
35f80 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f  be one of the co
35f90 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e  nstants:.** <ul>
35fa0 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
35fb0 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  _UTF8],.** <li> 
35fc0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d  [SQLITE_UTF16LE]
35fd0 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
35fe0 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c  E_UTF16BE],.** <
35ff0 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  li> [SQLITE_UTF1
36000 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b  6], or.** <li> [
36010 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49  SQLITE_UTF16_ALI
36020 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29  GNED]..** </ul>)
36030 5e 0a 2a 2a 20 5e 54 68 65 20 65 54 65 78 74 52  ^.** ^The eTextR
36040 65 70 20 61 72 67 75 6d 65 6e 74 20 64 65 74 65  ep argument dete
36050 72 6d 69 6e 65 73 20 74 68 65 20 65 6e 63 6f 64  rmines the encod
36060 69 6e 67 20 6f 66 20 73 74 72 69 6e 67 73 20 70  ing of strings p
36070 61 73 73 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20  assed.** to the 
36080 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
36090 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c 20 78 43 61  on callback, xCa
360a0 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20  llback..** ^The 
360b0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 61  [SQLITE_UTF16] a
360c0 6e 64 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  nd [SQLITE_UTF16
360d0 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 73  _ALIGNED] values
360e0 20 66 6f 72 20 65 54 65 78 74 52 65 70 0a 2a 2a   for eTextRep.**
360f0 20 66 6f 72 63 65 20 73 74 72 69 6e 67 73 20 74   force strings t
36100 6f 20 62 65 20 55 54 46 31 36 20 77 69 74 68 20  o be UTF16 with 
36110 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
36120 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  r..** ^The [SQLI
36130 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44  TE_UTF16_ALIGNED
36140 5d 20 76 61 6c 75 65 20 66 6f 72 20 65 54 65 78  ] value for eTex
36150 74 52 65 70 20 66 6f 72 63 65 73 20 73 74 72 69  tRep forces stri
36160 6e 67 73 20 74 6f 20 62 65 67 69 6e 0a 2a 2a 20  ngs to begin.** 
36170 6f 6e 20 61 6e 20 65 76 65 6e 20 62 79 74 65 20  on an even byte 
36180 61 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e  address..**.** ^
36190 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  The fourth argum
361a0 65 6e 74 2c 20 70 41 72 67 2c 20 69 73 20 61 6e  ent, pArg, is an
361b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
361c0 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69  a pointer that i
361d0 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 68 72 6f  s passed.** thro
361e0 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74  ugh as the first
361f0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
36200 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
36210 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ion callback..**
36220 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61  .** ^The fifth a
36230 72 67 75 6d 65 6e 74 2c 20 78 43 61 6c 6c 62 61  rgument, xCallba
36240 63 6b 2c 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ck, is a pointer
36250 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e   to the collatin
36260 67 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e  g function..** ^
36270 4d 75 6c 74 69 70 6c 65 20 63 6f 6c 6c 61 74 69  Multiple collati
36280 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 63 61 6e  ng functions can
36290 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 75   be registered u
362a0 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61  sing the same na
362b0 6d 65 20 62 75 74 0a 2a 2a 20 77 69 74 68 20 64  me but.** with d
362c0 69 66 66 65 72 65 6e 74 20 65 54 65 78 74 52 65  ifferent eTextRe
362d0 70 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64  p parameters and
362e0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65   SQLite will use
362f0 20 77 68 69 63 68 65 76 65 72 0a 2a 2a 20 66 75   whichever.** fu
36300 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
36310 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74  the least amount
36320 20 6f 66 20 64 61 74 61 20 74 72 61 6e 73 66 6f   of data transfo
36330 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20  rmation..** ^If 
36340 74 68 65 20 78 43 61 6c 6c 62 61 63 6b 20 61 72  the xCallback ar
36350 67 75 6d 65 6e 74 20 69 73 20 4e 55 4c 4c 20 74  gument is NULL t
36360 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e  hen the collatin
36370 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a  g function is.**
36380 20 64 65 6c 65 74 65 64 2e 20 20 5e 57 68 65 6e   deleted.  ^When
36390 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67 20 66   all collating f
363a0 75 6e 63 74 69 6f 6e 73 20 68 61 76 69 6e 67 20  unctions having 
363b0 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 61 72  the same name ar
363c0 65 20 64 65 6c 65 74 65 64 2c 0a 2a 2a 20 74 68  e deleted,.** th
363d0 61 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20  at collation is 
363e0 6e 6f 20 6c 6f 6e 67 65 72 20 75 73 61 62 6c 65  no longer usable
363f0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c  ..**.** ^The col
36400 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
36410 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
36420 6b 65 64 20 77 69 74 68 20 61 20 63 6f 70 79 20  ked with a copy 
36430 6f 66 20 74 68 65 20 70 41 72 67 20 0a 2a 2a 20  of the pArg .** 
36440 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
36450 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 77 69 74   pointer and wit
36460 68 20 74 77 6f 20 73 74 72 69 6e 67 73 20 69 6e  h two strings in
36470 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70   the encoding sp
36480 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68  ecified.** by th
36490 65 20 65 54 65 78 74 52 65 70 20 61 72 67 75 6d  e eTextRep argum
364a0 65 6e 74 2e 20 20 54 68 65 20 63 6f 6c 6c 61 74  ent.  The collat
364b0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  ing function mus
364c0 74 20 72 65 74 75 72 6e 20 61 6e 0a 2a 2a 20 69  t return an.** i
364d0 6e 74 65 67 65 72 20 74 68 61 74 20 69 73 20 6e  nteger that is n
364e0 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 2c 20 6f  egative, zero, o
364f0 72 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20 69 66  r positive.** if
36500 20 74 68 65 20 66 69 72 73 74 20 73 74 72 69 6e   the first strin
36510 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 20  g is less than, 
36520 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65  equal to, or gre
36530 61 74 65 72 20 74 68 61 6e 20 74 68 65 20 73 65  ater than the se
36540 63 6f 6e 64 2c 0a 2a 2a 20 72 65 73 70 65 63 74  cond,.** respect
36550 69 76 65 6c 79 2e 20 20 41 20 63 6f 6c 6c 61 74  ively.  A collat
36560 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  ing function mus
36570 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20  t always return 
36580 74 68 65 20 73 61 6d 65 20 61 6e 73 77 65 72 0a  the same answer.
36590 2a 2a 20 67 69 76 65 6e 20 74 68 65 20 73 61 6d  ** given the sam
365a0 65 20 69 6e 70 75 74 73 2e 20 20 49 66 20 74 77  e inputs.  If tw
365b0 6f 20 6f 72 20 6d 6f 72 65 20 63 6f 6c 6c 61 74  o or more collat
365c0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  ing functions ar
365d0 65 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20  e registered.** 
365e0 74 6f 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 6c  to the same coll
365f0 61 74 69 6f 6e 20 6e 61 6d 65 20 28 75 73 69 6e  ation name (usin
36600 67 20 64 69 66 66 65 72 65 6e 74 20 65 54 65 78  g different eTex
36610 74 52 65 70 20 76 61 6c 75 65 73 29 20 74 68 65  tRep values) the
36620 6e 20 61 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67 69  n all.** must gi
36630 76 65 20 61 6e 20 65 71 75 69 76 61 6c 65 6e 74  ve an equivalent
36640 20 61 6e 73 77 65 72 20 77 68 65 6e 20 69 6e 76   answer when inv
36650 6f 6b 65 64 20 77 69 74 68 20 65 71 75 69 76 61  oked with equiva
36660 6c 65 6e 74 20 73 74 72 69 6e 67 73 2e 0a 2a 2a  lent strings..**
36670 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   The collating f
36680 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6f 62 65  unction must obe
36690 79 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  y the following 
366a0 70 72 6f 70 65 72 74 69 65 73 20 66 6f 72 20 61  properties for a
366b0 6c 6c 0a 2a 2a 20 73 74 72 69 6e 67 73 20 41 2c  ll.** strings A,
366c0 20 42 2c 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a   B, and C:.**.**
366d0 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66   <ol>.** <li> If
366e0 20 41 3d 3d 42 20 74 68 65 6e 20 42 3d 3d 41 2e   A==B then B==A.
366f0 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42  .** <li> If A==B
36700 20 61 6e 64 20 42 3d 3d 43 20 74 68 65 6e 20 41   and B==C then A
36710 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20  ==C..** <li> If 
36720 41 26 6c 74 3b 42 20 54 48 45 4e 20 42 26 67 74  A&lt;B THEN B&gt
36730 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41  ;A..** <li> If A
36740 26 6c 74 3b 42 20 61 6e 64 20 42 26 6c 74 3b 43  &lt;B and B&lt;C
36750 20 74 68 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a 2a   then A&lt;C..**
36760 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20   </ol>.**.** If 
36770 61 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  a collating func
36780 74 69 6f 6e 20 66 61 69 6c 73 20 61 6e 79 20 6f  tion fails any o
36790 66 20 74 68 65 20 61 62 6f 76 65 20 63 6f 6e 73  f the above cons
367a0 74 72 61 69 6e 74 73 20 61 6e 64 20 74 68 61 74  traints and that
367b0 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  .** collating fu
367c0 6e 63 74 69 6f 6e 20 69 73 20 20 72 65 67 69 73  nction is  regis
367d0 74 65 72 65 64 20 61 6e 64 20 75 73 65 64 2c 20  tered and used, 
367e0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
367f0 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 69  r of SQLite.** i
36800 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
36810 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
36820 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
36830 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65  _v2() works like
36840 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
36850 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 77  collation().** w
36860 69 74 68 20 74 68 65 20 61 64 64 69 74 69 6f 6e  ith the addition
36870 20 74 68 61 74 20 74 68 65 20 78 44 65 73 74 72   that the xDestr
36880 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  oy callback is i
36890 6e 76 6f 6b 65 64 20 6f 6e 20 70 41 72 67 20 77  nvoked on pArg w
368a0 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61  hen.** the colla
368b0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73  ting function is
368c0 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43 6f   deleted..** ^Co
368d0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
368e0 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 77 68  s are deleted wh
368f0 65 6e 20 74 68 65 79 20 61 72 65 20 6f 76 65 72  en they are over
36900 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72 0a  ridden by later.
36910 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20  ** calls to the 
36920 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74 69  collation creati
36930 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  on functions or 
36940 77 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 64 61 74  when the.** [dat
36950 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
36960 5d 20 69 73 20 63 6c 6f 73 65 64 20 75 73 69 6e  ] is closed usin
36970 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  g [sqlite3_close
36980 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ()]..**.** ^The 
36990 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63  xDestroy callbac
369a0 6b 20 69 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e 20  k is <u>not</u> 
369b0 63 61 6c 6c 65 64 20 69 66 20 74 68 65 20 0a 2a  called if the .*
369c0 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
369d0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20  _collation_v2() 
369e0 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 2e 20  function fails. 
369f0 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
36a00 61 74 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c  at invoke.** sql
36a10 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
36a20 61 74 69 6f 6e 5f 76 32 28 29 20 77 69 74 68 20  ation_v2() with 
36a30 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73 74  a non-NULL xDest
36a40 72 6f 79 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  roy argument sho
36a50 75 6c 64 20 0a 2a 2a 20 63 68 65 63 6b 20 74 68  uld .** check th
36a60 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 61 6e  e return code an
36a70 64 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65  d dispose of the
36a80 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
36a90 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65  a pointer.** the
36aa0 6d 73 65 6c 76 65 73 20 72 61 74 68 65 72 20 74  mselves rather t
36ab0 68 61 6e 20 65 78 70 65 63 74 69 6e 67 20 53 51  han expecting SQ
36ac0 4c 69 74 65 20 74 6f 20 64 65 61 6c 20 77 69 74  Lite to deal wit
36ad0 68 20 69 74 20 66 6f 72 20 74 68 65 6d 2e 0a 2a  h it for them..*
36ae0 2a 20 54 68 69 73 20 69 73 20 64 69 66 66 65 72  * This is differ
36af0 65 6e 74 20 66 72 6f 6d 20 65 76 65 72 79 20 6f  ent from every o
36b00 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
36b10 72 66 61 63 65 2e 20 20 54 68 65 20 69 6e 63 6f  rface.  The inco
36b20 6e 73 69 73 74 65 6e 63 79 20 0a 2a 2a 20 69 73  nsistency .** is
36b30 20 75 6e 66 6f 72 74 75 6e 61 74 65 20 62 75 74   unfortunate but
36b40 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67   cannot be chang
36b50 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ed without break
36b60 69 6e 67 20 62 61 63 6b 77 61 72 64 73 20 0a 2a  ing backwards .*
36b70 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  * compatibility.
36b80 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
36b90 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61    [sqlite3_colla
36ba0 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61  tion_needed()] a
36bb0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  nd [sqlite3_coll
36bc0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29  ation_needed16()
36bd0 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
36be0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
36bf0 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  on(.  sqlite3*, 
36c00 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
36c10 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65  Name, .  int eTe
36c20 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a  xtRep, .  void *
36c30 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f  pArg,.  int(*xCo
36c40 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74  mpare)(void*,int
36c50 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74  ,const void*,int
36c60 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b  ,const void*).);
36c70 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
36c80 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
36c90 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
36ca0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
36cb0 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74  me, .  int eText
36cc0 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41  Rep, .  void *pA
36cd0 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70  rg,.  int(*xComp
36ce0 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  are)(void*,int,c
36cf0 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63  onst void*,int,c
36d00 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76  onst void*),.  v
36d10 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76  oid(*xDestroy)(v
36d20 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  oid*).);.int sql
36d30 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
36d40 61 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74  ation16(.  sqlit
36d50 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f  e3*, .  const vo
36d60 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74  id *zName,.  int
36d70 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f   eTextRep, .  vo
36d80 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28  id *pArg,.  int(
36d90 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a  *xCompare)(void*
36da0 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
36db0 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
36dc0 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ).);../*.** CAPI
36dd0 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20  3REF: Collation 
36de0 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b 73  Needed Callbacks
36df0 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69 64  .**.** ^To avoid
36e00 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73   having to regis
36e10 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f  ter all collatio
36e20 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f  n sequences befo
36e30 72 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a  re a database.**
36e40 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20   can be used, a 
36e50 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20  single callback 
36e60 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20  function may be 
36e70 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20  registered with 
36e80 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  the.** [database
36e90 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20   connection] to 
36ea0 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
36eb0 76 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64  ver an undefined
36ec0 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65   collation.** se
36ed0 71 75 65 6e 63 65 20 69 73 20 72 65 71 75 69 72  quence is requir
36ee0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
36ef0 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65  e function is re
36f00 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 74  gistered using t
36f10 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  he sqlite3_colla
36f20 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 50  tion_needed() AP
36f30 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73  I,.** then it is
36f40 20 70 61 73 73 65 64 20 74 68 65 20 6e 61 6d 65   passed the name
36f50 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 63  s of undefined c
36f60 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
36f70 65 73 20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a  es as strings.**
36f80 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d   encoded in UTF-
36f90 38 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63  8. ^If sqlite3_c
36fa0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
36fb0 36 28 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20  6() is used,.** 
36fc0 74 68 65 20 6e 61 6d 65 73 20 61 72 65 20 70 61  the names are pa
36fd0 73 73 65 64 20 61 73 20 55 54 46 2d 31 36 20 69  ssed as UTF-16 i
36fe0 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 65  n machine native
36ff0 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20   byte order..** 
37000 5e 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65  ^A call to eithe
37010 72 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61  r function repla
37020 63 65 73 20 74 68 65 20 65 78 69 73 74 69 6e 67  ces the existing
37030 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64 65   collation-neede
37040 64 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  d callback..**.*
37050 2a 20 5e 28 57 68 65 6e 20 74 68 65 20 63 61 6c  * ^(When the cal
37060 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
37070 2c 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  , the first argu
37080 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73 20 61  ment passed is a
37090 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20   copy.** of the 
370a0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
370b0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  to sqlite3_colla
370c0 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72  tion_needed() or
370d0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  .** sqlite3_coll
370e0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29  ation_needed16()
370f0 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  .  The second ar
37100 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 64 61  gument is the da
37110 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
37120 74 69 6f 6e 2e 20 20 54 68 65 20 74 68 69 72 64  tion.  The third
37130 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65   argument is one
37140 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38   of [SQLITE_UTF8
37150 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  ], [SQLITE_UTF16
37160 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  BE],.** or [SQLI
37170 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64  TE_UTF16LE], ind
37180 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73 74  icating the most
37190 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d 20   desirable form 
371a0 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  of the collation
371b0 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66 75 6e  .** sequence fun
371c0 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e 20  ction required. 
371d0 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   The fourth para
371e0 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d  meter is the nam
371f0 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 75  e of the.** requ
37200 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73  ired collation s
37210 65 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a  equence.)^.**.**
37220 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75   The callback fu
37230 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65  nction should re
37240 67 69 73 74 65 72 20 74 68 65 20 64 65 73 69 72  gister the desir
37250 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69  ed collation usi
37260 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ng.** [sqlite3_c
37270 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
37280 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
37290 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
372a0 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  )], or.** [sqlit
372b0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
372c0 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e  ion_v2()]..*/.in
372d0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  t sqlite3_collat
372e0 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71  ion_needed(.  sq
372f0 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a  lite3*, .  void*
37300 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69  , .  void(*)(voi
37310 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20  d*,sqlite3*,int 
37320 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63  eTextRep,const c
37330 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  har*).);.int sql
37340 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
37350 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74  eeded16(.  sqlit
37360 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20  e3*, .  void*,. 
37370 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73   void(*)(void*,s
37380 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78  qlite3*,int eTex
37390 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  tRep,const void*
373a0 29 0a 29 3b 0a 0a 23 69 66 64 65 66 20 53 51 4c  ).);..#ifdef SQL
373b0 49 54 45 5f 48 41 53 5f 43 4f 44 45 43 0a 2f 2a  ITE_HAS_CODEC./*
373c0 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20  .** Specify the 
373d0 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72 79  key for an encry
373e0 70 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 20  pted database.  
373f0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68 6f  This routine sho
37400 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64  uld be.** called
37410 20 72 69 67 68 74 20 61 66 74 65 72 20 73 71 6c   right after sql
37420 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a  ite3_open()..**.
37430 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69  ** The code to i
37440 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50  mplement this AP
37450 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62  I is not availab
37460 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63  le in the public
37470 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53   release.** of S
37480 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  QLite..*/.int sq
37490 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c  lite3_key(.  sql
374a0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
374b0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
374c0 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65  atabase to be re
374d0 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74  keyed */.  const
374e0 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74   void *pKey, int
374f0 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65   nKey     /* The
37500 20 6b 65 79 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73   key */.);.int s
37510 71 6c 69 74 65 33 5f 6b 65 79 5f 76 32 28 0a 20  qlite3_key_v2(. 
37520 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
37530 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
37540 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62  /* Database to b
37550 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63  e rekeyed */.  c
37560 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61  onst char *zDbNa
37570 6d 65 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a  me,           /*
37580 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   Name of the dat
37590 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  abase */.  const
375a0 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74   void *pKey, int
375b0 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65   nKey     /* The
375c0 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a   key */.);../*.*
375d0 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65 79  * Change the key
375e0 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 61   on an open data
375f0 62 61 73 65 2e 20 20 49 66 20 74 68 65 20 63 75  base.  If the cu
37600 72 72 65 6e 74 20 64 61 74 61 62 61 73 65 20 69  rrent database i
37610 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74  s not.** encrypt
37620 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ed, this routine
37630 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 74   will encrypt it
37640 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72  .  If pNew==0 or
37650 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a   nNew==0, the.**
37660 20 64 61 74 61 62 61 73 65 20 69 73 20 64 65 63   database is dec
37670 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  rypted..**.** Th
37680 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d  e code to implem
37690 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20  ent this API is 
376a0 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  not available in
376b0 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65   the public rele
376c0 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65  ase.** of SQLite
376d0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
376e0 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74 65  _rekey(.  sqlite
376f0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
37700 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
37710 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79  base to be rekey
37720 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  ed */.  const vo
37730 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b  id *pKey, int nK
37740 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65  ey     /* The ne
37750 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 69 6e 74 20  w key */.);.int 
37760 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 5f 76 32  sqlite3_rekey_v2
37770 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
37780 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
37790 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74     /* Database t
377a0 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a  o be rekeyed */.
377b0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44    const char *zD
377c0 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20 20  bName,          
377d0 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20   /* Name of the 
377e0 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f  database */.  co
377f0 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20  nst void *pKey, 
37800 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20  int nKey     /* 
37810 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29  The new key */.)
37820 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79  ;../*.** Specify
37830 20 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20   the activation 
37840 6b 65 79 20 66 6f 72 20 61 20 53 45 45 20 64 61  key for a SEE da
37850 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20  tabase.  Unless 
37860 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e  .** activated, n
37870 6f 6e 65 20 6f 66 20 74 68 65 20 53 45 45 20 72  one of the SEE r
37880 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72  outines will wor
37890 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  k..*/.void sqlit
378a0 65 33 5f 61 63 74 69 76 61 74 65 5f 73 65 65 28  e3_activate_see(
378b0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
378c0 50 61 73 73 50 68 72 61 73 65 20 20 20 20 20 20  PassPhrase      
378d0 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20    /* Activation 
378e0 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e  phrase */.);.#en
378f0 64 69 66 0a 0a 23 69 66 64 65 66 20 53 51 4c 49  dif..#ifdef SQLI
37900 54 45 5f 45 4e 41 42 4c 45 5f 43 45 52 4f 44 0a  TE_ENABLE_CEROD.
37910 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68  /*.** Specify th
37920 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 79  e activation key
37930 20 66 6f 72 20 61 20 43 45 52 4f 44 20 64 61 74   for a CEROD dat
37940 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a  abase.  Unless .
37950 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f  ** activated, no
37960 6e 65 20 6f 66 20 74 68 65 20 43 45 52 4f 44 20  ne of the CEROD 
37970 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f  routines will wo
37980 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  rk..*/.void sqli
37990 74 65 33 5f 61 63 74 69 76 61 74 65 5f 63 65 72  te3_activate_cer
379a0 6f 64 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  od(.  const char
379b0 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20 20   *zPassPhrase   
379c0 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69       /* Activati
379d0 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a  on phrase */.);.
379e0 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
379f0 50 49 33 52 45 46 3a 20 53 75 73 70 65 6e 64 20  PI3REF: Suspend 
37a00 45 78 65 63 75 74 69 6f 6e 20 46 6f 72 20 41 20  Execution For A 
37a10 53 68 6f 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a 2a  Short Time.**.**
37a20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c 65   The sqlite3_sle
37a30 65 70 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 61  ep() function ca
37a40 75 73 65 73 20 74 68 65 20 63 75 72 72 65 6e 74  uses the current
37a50 20 74 68 72 65 61 64 20 74 6f 20 73 75 73 70 65   thread to suspe
37a60 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20  nd execution.** 
37a70 66 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20 6e  for at least a n
37a80 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65  umber of millise
37a90 63 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64 20  conds specified 
37aa0 69 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65 72  in its parameter
37ab0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f  ..**.** If the o
37ac0 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
37ad0 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74  does not support
37ae0 20 73 6c 65 65 70 20 72 65 71 75 65 73 74 73 20   sleep requests 
37af0 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63  with.** millisec
37b00 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75 74  ond time resolut
37b10 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74 69  ion, then the ti
37b20 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64  me will be round
37b30 65 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20  ed up to.** the 
37b40 6e 65 61 72 65 73 74 20 73 65 63 6f 6e 64 2e 20  nearest second. 
37b50 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69  The number of mi
37b60 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
37b70 65 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20  eep actually.** 
37b80 72 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20 74  requested from t
37b90 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
37ba0 74 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  tem is returned.
37bb0 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 69  .**.** ^SQLite i
37bc0 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69  mplements this i
37bd0 6e 74 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c  nterface by call
37be0 69 6e 67 20 74 68 65 20 78 53 6c 65 65 70 28 29  ing the xSleep()
37bf0 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  .** method of th
37c00 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
37c10 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20  e3_vfs] object. 
37c20 20 49 66 20 74 68 65 20 78 53 6c 65 65 70 28 29   If the xSleep()
37c30 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68   method.** of th
37c40 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 73  e default VFS is
37c50 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64   not implemented
37c60 20 63 6f 72 72 65 63 74 6c 79 2c 20 6f 72 20 6e   correctly, or n
37c70 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61  ot implemented a
37c80 74 0a 2a 2a 20 61 6c 6c 2c 20 74 68 65 6e 20 74  t.** all, then t
37c90 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73  he behavior of s
37ca0 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20 6d  qlite3_sleep() m
37cb0 61 79 20 64 65 76 69 61 74 65 20 66 72 6f 6d 20  ay deviate from 
37cc0 74 68 65 20 64 65 73 63 72 69 70 74 69 6f 6e 0a  the description.
37cd0 2a 2a 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  ** in the previo
37ce0 75 73 20 70 61 72 61 67 72 61 70 68 73 2e 0a 2a  us paragraphs..*
37cf0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c  /.int sqlite3_sl
37d00 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  eep(int);../*.**
37d10 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20   CAPI3REF: Name 
37d20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f  Of The Folder Ho
37d30 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72 79 20  lding Temporary 
37d40 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  Files.**.** ^(If
37d50 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72   this global var
37d60 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f  iable is made to
37d70 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69   point to a stri
37d80 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74  ng which is.** t
37d90 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c  he name of a fol
37da0 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65  der (a.k.a. dire
37db0 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c  ctory), then all
37dc0 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73   temporary files
37dd0 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 53  .** created by S
37de0 51 4c 69 74 65 20 77 68 65 6e 20 75 73 69 6e 67  QLite when using
37df0 20 61 20 62 75 69 6c 74 2d 69 6e 20 5b 73 71 6c   a built-in [sql
37e00 69 74 65 33 5f 76 66 73 20 7c 20 56 46 53 5d 0a  ite3_vfs | VFS].
37e10 2a 2a 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 65  ** will be place
37e20 64 20 69 6e 20 74 68 61 74 20 64 69 72 65 63 74  d in that direct
37e30 6f 72 79 2e 29 5e 20 20 5e 49 66 20 74 68 69 73  ory.)^  ^If this
37e40 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20   variable.** is 
37e50 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
37e60 74 68 65 6e 20 53 51 4c 69 74 65 20 70 65 72 66  then SQLite perf
37e70 6f 72 6d 73 20 61 20 73 65 61 72 63 68 20 66 6f  orms a search fo
37e80 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  r an appropriate
37e90 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69  .** temporary fi
37ea0 6c 65 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a  le directory..**
37eb0 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
37ec0 20 61 72 65 20 73 74 72 6f 6e 67 6c 79 20 64 69   are strongly di
37ed0 73 63 6f 75 72 61 67 65 64 20 66 72 6f 6d 20 75  scouraged from u
37ee0 73 69 6e 67 20 74 68 69 73 20 67 6c 6f 62 61 6c  sing this global
37ef0 20 76 61 72 69 61 62 6c 65 2e 0a 2a 2a 20 49 74   variable..** It
37f00 20 69 73 20 72 65 71 75 69 72 65 64 20 74 6f 20   is required to 
37f10 73 65 74 20 61 20 74 65 6d 70 6f 72 61 72 79 20  set a temporary 
37f20 66 6f 6c 64 65 72 20 6f 6e 20 57 69 6e 64 6f 77  folder on Window
37f30 73 20 52 75 6e 74 69 6d 65 20 28 57 69 6e 52 54  s Runtime (WinRT
37f40 29 2e 0a 2a 2a 20 42 75 74 20 66 6f 72 20 61 6c  )..** But for al
37f50 6c 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d  l other platform
37f60 73 2c 20 69 74 20 69 73 20 68 69 67 68 6c 79 20  s, it is highly 
37f70 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
37f80 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
37f90 20 6e 65 69 74 68 65 72 20 72 65 61 64 20 6e 6f   neither read no
37fa0 72 20 77 72 69 74 65 20 74 68 69 73 20 76 61 72  r write this var
37fb0 69 61 62 6c 65 2e 20 20 54 68 69 73 20 67 6c 6f  iable.  This glo
37fc0 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20  bal variable is 
37fd0 61 20 72 65 6c 69 63 0a 2a 2a 20 74 68 61 74 20  a relic.** that 
37fe0 65 78 69 73 74 73 20 66 6f 72 20 62 61 63 6b 77  exists for backw
37ff0 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
38000 74 79 20 6f 66 20 6c 65 67 61 63 79 20 61 70 70  ty of legacy app
38010 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 68  lications and sh
38020 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 76 6f 69 64  ould.** be avoid
38030 65 64 20 69 6e 20 6e 65 77 20 70 72 6f 6a 65 63  ed in new projec
38040 74 73 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20  ts..**.** It is 
38050 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64  not safe to read
38060 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20   or modify this 
38070 76 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65  variable in more
38080 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72   than one.** thr
38090 65 61 64 20 61 74 20 61 20 74 69 6d 65 2e 20 20  ead at a time.  
380a0 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
380b0 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79  o read or modify
380c0 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a   this variable.*
380d0 2a 20 69 66 20 61 20 5b 64 61 74 61 62 61 73 65  * if a [database
380e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20   connection] is 
380f0 62 65 69 6e 67 20 75 73 65 64 20 61 74 20 74 68  being used at th
38100 65 20 73 61 6d 65 20 74 69 6d 65 20 69 6e 20 61  e same time in a
38110 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 74 68 72   separate.** thr
38120 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e  ead..** It is in
38130 74 65 6e 64 65 64 20 74 68 61 74 20 74 68 69 73  tended that this
38140 20 76 61 72 69 61 62 6c 65 20 62 65 20 73 65 74   variable be set
38150 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74   once.** as part
38160 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74   of process init
38170 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62  ialization and b
38180 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65  efore any SQLite
38190 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f   interface.** ro
381a0 75 74 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e  utines have been
381b0 20 63 61 6c 6c 65 64 20 61 6e 64 20 74 68 61 74   called and that
381c0 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 72   this variable r
381d0 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a  emain unchanged.
381e0 2a 2a 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a  ** thereafter..*
381f0 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74 65 6d 70 5f  *.** ^The [temp_
38200 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
38210 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69  pragma] may modi
38220 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  fy this variable
38230 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 74   and cause.** it
38240 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d   to point to mem
38250 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
38260 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
38270 63 5d 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f 72  c].  ^Furthermor
38280 65 2c 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f  e,.** the [temp_
38290 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
382a0 70 72 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 61  pragma] always a
382b0 73 73 75 6d 65 73 20 74 68 61 74 20 61 6e 79 20  ssumes that any 
382c0 73 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74  string.** that t
382d0 68 69 73 20 76 61 72 69 61 62 6c 65 20 70 6f 69  his variable poi
382e0 6e 74 73 20 74 6f 20 69 73 20 68 65 6c 64 20 69  nts to is held i
382f0 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  n memory obtaine
38300 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69  d from .** [sqli
38310 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20  te3_malloc] and 
38320 74 68 65 20 70 72 61 67 6d 61 20 6d 61 79 20 61  the pragma may a
38330 74 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74  ttempt to free t
38340 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73  hat memory.** us
38350 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  ing [sqlite3_fre
38360 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66  e]..** Hence, if
38370 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69   this variable i
38380 73 20 6d 6f 64 69 66 69 65 64 20 64 69 72 65 63  s modified direc
38390 74 6c 79 2c 20 65 69 74 68 65 72 20 69 74 20 73  tly, either it s
383a0 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65  hould be.** made
383b0 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f   NULL or made to
383c0 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79   point to memory
383d0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
383e0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a  sqlite3_malloc].
383f0 2a 2a 20 6f 72 20 65 6c 73 65 20 74 68 65 20 75  ** or else the u
38400 73 65 20 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f  se of the [temp_
38410 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
38420 70 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62  pragma] should b
38430 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2a 20 45 78  e avoided..** Ex
38440 63 65 70 74 20 77 68 65 6e 20 72 65 71 75 65 73  cept when reques
38450 74 65 64 20 62 79 20 74 68 65 20 5b 74 65 6d 70  ted by the [temp
38460 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
38470 20 70 72 61 67 6d 61 5d 2c 20 53 51 4c 69 74 65   pragma], SQLite
38480 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 66 72 65  .** does not fre
38490 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61  e the memory tha
384a0 74 20 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64  t sqlite3_temp_d
384b0 69 72 65 63 74 6f 72 79 20 70 6f 69 6e 74 73 20  irectory points 
384c0 74 6f 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 61  to.  If.** the a
384d0 70 70 6c 69 63 61 74 69 6f 6e 20 77 61 6e 74 73  pplication wants
384e0 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 74 6f 20   that memory to 
384f0 62 65 20 66 72 65 65 64 2c 20 69 74 20 6d 75 73  be freed, it mus
38500 74 20 64 6f 0a 2a 2a 20 73 6f 20 69 74 73 65 6c  t do.** so itsel
38510 66 2c 20 74 61 6b 69 6e 67 20 63 61 72 65 20 74  f, taking care t
38520 6f 20 6f 6e 6c 79 20 64 6f 20 73 6f 20 61 66 74  o only do so aft
38530 65 72 20 61 6c 6c 20 5b 64 61 74 61 62 61 73 65  er all [database
38540 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20   connection].** 
38550 6f 62 6a 65 63 74 73 20 68 61 76 65 20 62 65 65  objects have bee
38560 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a  n destroyed..**.
38570 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69  ** <b>Note to Wi
38580 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73  ndows Runtime us
38590 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65  ers:</b>  The te
385a0 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72  mporary director
385b0 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a  y must be set.**
385c0 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e   prior to callin
385d0 67 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5d  g [sqlite3_open]
385e0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
385f0 6e 5f 76 32 5d 2e 20 20 4f 74 68 65 72 77 69 73  n_v2].  Otherwis
38600 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65  e, various.** fe
38610 61 74 75 72 65 73 20 74 68 61 74 20 72 65 71 75  atures that requ
38620 69 72 65 20 74 68 65 20 75 73 65 20 6f 66 20 74  ire the use of t
38630 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d  emporary files m
38640 61 79 20 66 61 69 6c 2e 20 20 48 65 72 65 20 69  ay fail.  Here i
38650 73 20 61 6e 0a 2a 2a 20 65 78 61 6d 70 6c 65 20  s an.** example 
38660 6f 66 20 68 6f 77 20 74 6f 20 64 6f 20 74 68 69  of how to do thi
38670 73 20 75 73 69 6e 67 20 43 2b 2b 20 77 69 74 68  s using C++ with
38680 20 74 68 65 20 57 69 6e 64 6f 77 73 20 52 75 6e   the Windows Run
38690 74 69 6d 65 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  time:.**.** <blo
386a0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
386b0 20 4c 50 43 57 53 54 52 20 7a 50 61 74 68 20 3d   LPCWSTR zPath =
386c0 20 57 69 6e 64 6f 77 73 3a 3a 53 74 6f 72 61 67   Windows::Storag
386d0 65 3a 3a 41 70 70 6c 69 63 61 74 69 6f 6e 44 61  e::ApplicationDa
386e0 74 61 3a 3a 43 75 72 72 65 6e 74 2d 3e 0a 2a 2a  ta::Current->.**
386f0 20 26 6e 62 73 70 3b 20 20 20 20 20 54 65 6d 70   &nbsp;     Temp
38700 6f 72 61 72 79 46 6f 6c 64 65 72 2d 3e 50 61 74  oraryFolder->Pat
38710 68 2d 3e 44 61 74 61 28 29 3b 0a 2a 2a 20 63 68  h->Data();.** ch
38720 61 72 20 7a 50 61 74 68 42 75 66 26 23 39 31 3b  ar zPathBuf&#91;
38730 4d 41 58 5f 50 41 54 48 20 2b 20 31 26 23 39 33  MAX_PATH + 1&#93
38740 3b 3b 0a 2a 2a 20 6d 65 6d 73 65 74 28 7a 50 61  ;;.** memset(zPa
38750 74 68 42 75 66 2c 20 30 2c 20 73 69 7a 65 6f 66  thBuf, 0, sizeof
38760 28 7a 50 61 74 68 42 75 66 29 29 3b 0a 2a 2a 20  (zPathBuf));.** 
38770 57 69 64 65 43 68 61 72 54 6f 4d 75 6c 74 69 42  WideCharToMultiB
38780 79 74 65 28 43 50 5f 55 54 46 38 2c 20 30 2c 20  yte(CP_UTF8, 0, 
38790 7a 50 61 74 68 2c 20 2d 31 2c 20 7a 50 61 74 68  zPath, -1, zPath
387a0 42 75 66 2c 20 73 69 7a 65 6f 66 28 7a 50 61 74  Buf, sizeof(zPat
387b0 68 42 75 66 29 2c 0a 2a 2a 20 26 6e 62 73 70 3b  hBuf),.** &nbsp;
387c0 20 20 20 20 20 4e 55 4c 4c 2c 20 4e 55 4c 4c 29       NULL, NULL)
387d0 3b 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 65 6d  ;.** sqlite3_tem
387e0 70 5f 64 69 72 65 63 74 6f 72 79 20 3d 20 73 71  p_directory = sq
387f0 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 25  lite3_mprintf("%